Help & docs

Three steps to a working agent session — most of the platform makes sense once you have one running.

1. Add a host — Open the Hosts page and click Add host. Enter the address, SSH user, and paste a private key (or password). LobsterFarm probes the host immediately so a typo or wrong credential fails right there, not at session-start time. Hosts →
2. Add an AI channel — On the Channels page, pick a provider and paste an API key (OpenAI / Anthropic) or an OAuth refresh token (Gemini CLI / Codex). Lobsterfarm probes the credential up front so a typo or revoked key fails immediately, not at session time. Channels →
3. Run a session — Open the Sessions page and start one. Each session attaches to a tmux pane on the host you picked; the agent runtime (currently Claude Code) is wired to your channels through the gateway. The Live / Ended filter narrows the list once you accumulate history. Sessions →

Tip: hit ⌘ K anywhere to fuzzy-jump between pages, switch color themes, or sign out — no mouse needed.

Once the first session is running, here is what each top-level page is good for. None of these surfaces are stubs — they are wired to real backend endpoints.

• Dashboard — Aggregate health at a glance plus a "recent hosts" panel — the box you SSHed into last is one click away. Dashboard →
• Hosts — Inventory with full-text search across name / address / notes, sort=recent ordering, last-seen timestamps, and a TOFU SHA-256 fingerprint pinned at first connect (also included in CSV export). Drill into a host for the SFTP browser and port-forward manager. Hosts →
• Sessions — Live and historical agent sessions with a Live / Ended filter, automatic reconnect on a dropped SSH pipe, and asciinema recordings on S3. Sessions →
• Deploy — Templates that fan-out to multiple hosts. Run detail aggregates host status, lets you filter by success / failed / running / pending, asks for confirmation before cancel, and surfaces a "retry failed" CTA once the run is terminal. Deploy →
• Proxies — HTTP / SOCKS5 egress proxies fronting outbound LLM calls. Each row shows reference counts so you cannot accidentally delete one still wired to a channel. Proxies →
• Snippets — Reusable command snippets with tag filtering, free-text search, and one-click copy — useful for the same `journalctl -u …` you keep typing. Snippets →

  ┌──────────────┐       ┌────────────────┐       ┌──────────────┐
  │  your agent  │ ────▶ │ lobsterfarm gateway  │ ────▶ │  provider    │
  │ (openai SDK) │       │  router + pool │       │  (Anthropic) │
  └──────────────┘       └────────────────┘       └──────────────┘
                            │      │
                       picks channel by
                       priority + health

A channel is one credential + one upstream model. Lobsterfarm probes it at create-time, then every few minutes while it’s in an active pool. Each channel carries its own health flag, cooldown timer, and quota-remaining counter so routing decisions don’t need a sidecar cache.

When the same provider has multiple accounts (e.g. Google-corp + Google-personal), create a channel per account and give each a descriptive accountLabel.

A pool is a named list of interchangeable channels. The router picks one at request time:

1. Filter out anyone whose cooldown_until is in the future.
2. Sort by priority (lowest first), then by the pool’s selection strategy.
3. Try the first; on 429 / 401 / 5xx, cool them down and try the next.
4. Log a failover row in gateway_events for every hop.

Tip: keep pool sizes small (2–5 members). Deep pools increase tail latency and make failures harder to reason about. If you need more headroom, scale horizontally by creating per-model pools.

Pick API key when the provider issues one (OpenAI platform, Anthropic console, Groq, OpenRouter, …). The key is encrypted at rest and decrypted only in the gateway process when it signs an upstream request.

Pick OAuth when the account is a human login (Gemini CLI flow, ChatGPT plan via Codex CLI). You paste the long-lived refresh token once; LobsterFarm mints short-lived access tokens on demand and refreshes them a minute before they expire. If a refresh fails (revoked consent, password change, MFA re-challenge) you'll see an oauth.refresh-failed event and the channel drops to unhealthy until you rotate credentials.

All channels in the pool are cooling down

The router returned 503 because every member’s cooldown_until is still in the future. Usually a provider-wide incident. Mitigation: add a fallback pool for a different provider of the same model family, or lower defaultCooldownSec if you think the outage is transient.

oauth.refresh-failed event, channel went unhealthy

The refresh token was revoked. Re-run the CLI auth flow (Gemini / Codex), put the new refresh-token in a secret, and point the channel at it via Rotate credential. No router restart needed.

probe.fail with http 404

Almost always a model-name typo. Confirm the spelling against the provider docs — gpt-4o, claude-sonnet-4.7, gemini-2.5-pro.

Quota shows 0 but account works in the CLI

Some providers (Gemini free tier) only expose quota after the first successful call. Wait for one real request (or hit Rotate credential to re-probe) and the counter will populate.

Can’t find the right requestId in my app logs

The gateway propagates X-Request-Id. If your client doesn’t set one, the gateway mints a req_* id and puts it on both gateway_events.request_id and usage_events.request_id.

Sessions — Sessions list lives at /sessions. Each session attaches to a tmux pane on a host and needs an environment (project on host) + an agent profile (model + system prompt). The list filters Live / Ended and survives reconnects; recordings are persisted to S3 as asciinema cast. Sessions →

Routes — Model routes (/model-routes) map a virtual model name like `prod-sonnet` to one or more channels / pools. Your agent uses the virtual name; you re-point the underlying channel without redeploying agents. Routes →

Rotate credential — Rotate a credential without restarting anything: open /channels, hit the Rotate button on a card, paste the new key/token. The old secret is overwritten in place; the next request picks up the new one immediately.

A provisioner tells LobsterFarm how to materialize a host. Today there are two kinds: ssh-static (you registered a remote box you already manage — LobsterFarm just bookmarks the address + key and uses it as-is) and proxmox (a Proxmox cluster credential — LobsterFarm asks the cluster to spin up an LXC or VM on demand and tears it down when the env is destroyed).

For multi-tenant safety the control plane never spawns sandbox containers on its own host. If you need ephemeral throwaway hosts, wire up the proxmox provisioner; if you have your own fleet, ssh-static is the right choice.

Provisioners →

A workflow is a typed DAG you assemble in the editor. Five node kinds cover most ops scenarios: shell (run a command on a host), agent (start a session on an env with a prompt and capture the answer), wait (sleep N seconds — useful for race-condition smoke tests), condition (branch on a previous step’s output), and repeat (loop a sub-DAG until exit criteria match).

Edges define ordering only — context variables move data between nodes. Triggers (manual / cron / webhook) live on the workflow itself; runs are recorded with full per-step output so a failure can be reproduced from history.

Workflows →

A deployment template is a reusable shell script bundled with named variables (typed: string / secret / bool / number) and default targets (host ids or group ids). When you run it, the UI prompts for variable values, expands them server-side, and SSHes to each target in parallel.

Schedules run the same template on a cron without operator interaction. Secret variables are envelope-encrypted at rest and never echoed back to the UI; output is streamed live and archived per run.

Deploy →

The browser-reader is an internal Playwright pool. Agents call it through a tool (browser.read / browser.screenshot) when they need to fetch a JS-heavy page that an HTTP GET wouldn’t render. The pool reuses warm browser contexts, enforces per-org concurrency caps, and times out hung pages.

The /browser page surfaces pool health (active contexts, queue depth, recent failures) so you can tell whether a stuck agent is waiting on a real page or on a saturated pool.

Browser →

OpenClaw is an LLM-driven ops assistant pinned to a single host. Open it from /hosts/[id] → "Open OpenClaw" or directly at /hosts/[id]/ops. Ask in plain language ("why is CPU at 90%") and watch it run safe diagnostics over SSH and report back.

OpenClaw runs read-only triage automatically: shell commands from a strict allowlist (ls, cat, ps, top, df, journalctl, systemctl status, …), SFTP file reads, and directory listings. Write-like commands (apt install, systemctl restart, psql DELETE) now pause for an operator approval button; destructive commands remain hard-blocked.

Every command OpenClaw runs is logged in hermes_command_audit alongside the conversation that proposed it — a self-contained forensics trail you can query without paging through chat prose. Destructive patterns (rm -rf /, mkfs, reboot, fork bombs) are hard-blocked by a regex classifier the LLM cannot override.

Hosts → OpenClaw

How do I set up image generation?

Create an image provider with an API key from OpenAI, Google, Stability AI, or an OpenAI-compatible image endpoint. Then open Tools → Image Gen and select that provider.

What models are supported?

The studio supports DALL·E/OpenAI image models, Gemini Imagen, Stability AI, and generic OpenAI-compatible image APIs. Provider-specific model names remain editable so self-hosted gateways work too.

How do I optimize prompts?

Use Optimize Prompt after writing your idea. The app calls the configured AI feature route and expands composition, lighting, style, camera, and negative prompt details before you generate.

How does post-processing work?

Post-processing can resize, watermark, and convert output formats. Variants stay attached to the original generation so you can compare or reuse them later.

Image Gen →

Use the theme switcher in the top navigation to quickly move between Light, Dark, Ocean, Forest, Sunset, High Contrast, and editor-inspired dark palettes. The choice is stored per browser.

Charts are powered by a shared ECharts wrapper, so dashboard, usage, channel, host, and admin charts all share readable axes, full-date tooltips, theme-aware colors, and responsive resizing.

Bucketed values such as cost and tokens render as bars; continuous host metrics render as lines or areas. Host CPU sparklines use a fixed 0–100% domain so different hosts are visually comparable.

Every page on LobsterFarm leans on a chibi-lobster mascot and a sticker vocabulary that reskins itself when you flip the visual style. Browse the lineup below — the same mascot in three art styles plus the full sticker shelf.

Quick reference for LobsterFarm domain terms

Press ? anywhere to open