Install and run

One command to install

All you need is uv. The command below fetches the release wheel and installs lobster0 as a standalone CLI tool, leaving your existing Python environments untouched.

W=lobster0_agent-0.7.0-py3-none-any.whlcurl -fL --proto '=https' --tlsv1.2 -o /tmp/${W} \  https://github.com/NEDONION/lobster0/releases/download/v0.7.0/${W} \  && uv tool install --python 3.12 "/tmp/${W}[feishu]"

Keep the filename exactly as published. uv reads the version out of the wheel's filename and fails with Must have a version if you rename it. The braces in ${W} matter too: a bare $W[feishu] is array subscripting in zsh, the default shell on macOS.

Configure and start

lobster0 --version     # prints the version you just installed
lobster0 setup         # prompts for the model API key, Feishu app credentials, and owner
lobster0 gateway       # starts the Feishu gateway over a WebSocket connection — no public port

lobster0 setup is interactive, so run it separately rather than pasting it together with the install command.

To fix or rotate a single credential, use lobster0 secret set LOBSTER0_MODEL_API_KEY. lobster0 secret list prints only the names of configured variables, never their values.

Do not rm -rf ~/.lobster0. That deletes memory, conversation history, scheduled tasks, and audit records along with the configuration.

Release status

v0.7.0 is a prerelease. It has been verified on a clean Ubuntu 24.04 machine through a fully green doctor, so it is usable for self-hosting — but the Tier 1 hardware matrix, the PyPI release, and image attestation have not run, so treat it as unverified for production.

A one-line install.sh is not available yet, for two independent reasons. First, install.sh is produced by the release pipeline's assemble stage, which does not pass. Second, releases/latest/ only resolves to a stable release, and v0.7.0 is marked as a prerelease, so this repository has no latest release at all — the URL would keep returning 404 even once install.sh exists, until a stable version ships. Use the wheel install above for now.

Run from source

You only need this path to change code or run the test suite. Beyond uv it also needs Node.js 22.22.3 <= v < 23 or 24.15.0 <= v < 25 plus pnpm, because the TUI is built locally.

git clone https://github.com/NEDONION/lobster0.git
cd lobster0
uv sync --extra dev --extra channels
pnpm --dir tui install
pnpm --dir tui build
cp .env.example .env
uv run lobster0 init
uv run lobster0 doctor
uv run lobster0

cp .env.example .env creates local configuration only. Fill in the Provider and optional Channel settings from the template. Never commit a real API key, app secret, or token.

Without a compliant Node.js you can fall back to Textual: LOBSTER0_TUI=textual uv run lobster0.

Start with the TUI

Complete one normal conversation and one tool call that needs approval before connecting a messaging platform. This makes it easier to separate Core, Provider, and Channel Transport issues.

Next, read Runtime and Security boundaries. Development, test, and release commands remain authoritative in the repository README and pyproject.toml.