Getting started

About ten minutes: put the Flockbox agent on a computer, pair your phone, and start your first session from the couch.

1. Install the agent

On the computer, open a terminal (PowerShell on Windows) and run:

It installs into your own user folder (~/.flockbox), with no admin rights. If the computer has no Node.js 22 or newer, the agent gets its own copy there. Every download is checked against its checksum.

Then the setup starts:

1. A name for the computer, the way the app will show it ("Desk PC", "MacBook").
2. Your AI tools. Pick the ones you use, for example claude,codex. Any that aren't installed are installed at their latest version, then each one's own sign-in opens: a browser window for Claude Code or Codex, an API key prompt for Grok.
3. Keep it running. Say yes and the agent starts now and every time you log in.
4. Pair. It shows a QR code. Keep the terminal open for the next steps.

2. Get the app

Flockbox for iPhone (App Store) and Android (Google Play) is coming soon. The store links will be on the home page as soon as it's out.

3. Pair your phone

1. Open Flockbox and tap Pair a computer, then Scan QR code. Or point your phone's camera at the code: it opens Flockbox.
2. Check the name and tap Pair. The terminal says "Paired with" your phone.

The code works once and expires after ten minutes. For another phone, or if it expired, run flockbox pair on the computer for a new one.

4. Start a session

Tap ＋ New, then the computer.

• Agent: Claude Code, Codex, Gemini CLI, Cursor or Grok. One that isn't on the computer yet is installed first.
• Folder: a project you've worked in recently, one you browse to, or a new folder you create right there. If you don't choose one, the session gets a fresh folder of its own (~/Flockbox/claude/…).
• Permission mode: how much it may do without asking. For Claude Code, default asks you before anything that needs approval.
• Message: what to do, then Start.

5. Approve and follow

The chat shows what the agent says and does as it happens: tool calls in amber while they run, green when done, red when they fail, subagents in purple. When it wants to run something that needs your OK, you get Allow and Deny.

Leave the chat, or close the app, and the work carries on on the computer. The home screen shows every session's state: running, waiting for you, finished or failed. Sessions you started on the computer in Claude Code show up too.

6. Away from home

Nothing to do. At home the phone talks to the computer directly over your Wi-Fi; elsewhere it goes through the Flockbox relay automatically. The computer only needs to be on, with the agent running. Everything is end-to-end encrypted, so the relay can't read any of it. How connecting works.

More computers and tools

• Another computer: run the install command there and pair it the same way. Its sessions join the same list.
• Another AI tool on a computer: flockbox add codex (installs it if needed, then signs in).
• Check a computer: flockbox status shows the agent, the relay, and each tool's version and sign-in. The app shows the same under Setup.
• API providers such as Hermes, the Claude or OpenAI API, OpenRouter or Ollama: add them in the app under Setup → Add a provider.

Next

Every command, setting and troubleshooting tip is in the docs.