Getting started¶

This walks you from a fresh host to chatting with an agent on your phone.

1. Bootstrap lair¶

okto init

okto init is the setup command. The first time you run it (no ~/.okto/config.json yet) it prompts interactively for:

Anthropic API key — press Enter to skip.
OpenAI API key — press Enter to skip. (At least one of the two keys is required.)
API URL — Enter for the Anthropic default, or the full chat-completions URL of an OpenAI-compatible endpoint (e.g. https://api.deepinfra.com/v1/openai/chat/completions).
Model — Enter for the default (claude-sonnet-4-6).

It then:

Persists credentials to ~/.okto/config.json.
Installs Docker if it isn't already present.
Generates a Noise keypair (transport identity) and an Ed25519 SSH keypair (operator backchannel for remote agents).
Writes the env file ~/.okto/lair-env (consumed by docker --env-file).
docker pulls the lair image and docker runs the container, bind-mounting ~/.okto to /data and publishing the Noise port.
Waits for the management API to report healthy, then prints a QR code.

Re-running okto init

okto init is safe to re-run. If ~/.okto/config.json already exists it reuses that config (no prompts) — it validates it, applies --system-prompt-append if you passed one, then pulls the image and starts lair. So init doubles as a "(re)start from my existing config" command. To change credentials use okto config set; to start over from scratch, okto destroy first.

Useful `okto init` flags¶

Flag	Purpose
`-e, --env KEY=VALUE`	Extra env var for the lair container (repeatable). Inherited by every child agent. e.g. `-e GH_TOKEN=…`
`--noise-port <PORT>`	Host-side Noise port the QR advertises. Default 8443.
`--http-port <PORT>`	Loopback management-API port. Default 8000.
`--image <REF>`	Lair image reference. Defaults to `$OKTO_LAIR_IMAGE` or `ghcr.io/georgebradford0/lair:latest`.
`--mcp-config <PATH>`	Seed lair's MCP servers from an `mcp.json` file.
`--system-prompt-append <TEXT or @PATH>`	Append site-specific guidance to lair's system prompt. `@path` reads a file. See Customization.
`--disable-push`	Turn push notifications off end-to-end.
`--ready-timeout <SECS>`	How long to wait for health after `docker run`. Default 1200 (20 min). Bump it if your `bootstrap.sh` does heavy work.

Init with a GitHub token and house-style prompt

okto init \
  -e GH_TOKEN=ghp_xxx \
  --system-prompt-append @./lair-prompt.md

2. Pair your phone¶

When init finishes it prints a QR code. If you need it again later:

okto qr

The QR encodes 2:<host>:<port>:<noise-pubkey>. Open the mobile app, tap the icon, and scan it. The host is auto-detected from your public IP; override it with --host, or set PUBLIC_HOST via okto env.

okto qr --host my.box.example.com

On iOS the app asks for push-notification permission — see Push notifications.

3. Chat¶

Once paired, you're talking to lair (the parent agent). From the chat you can ask it to write code, run commands, and create child agents (local or remote) that then appear in the sidebar. See Agents.

Tearing down¶

Stop lair, remove every managed agent, and wipe lair's host data (~/.okto/lair, ~/.okto/agents, ~/.okto/lair-env, the launch record) — leaving your config.json in place:

okto destroy        # prompts; type "yes"
okto destroy -y     # skip the prompt