Docs
Everything about the Flockbox agent and how the app works with it. New here? Start with the guide.
How Flockbox works
Flockbox has two parts:
- The app (iPhone and Android) lists every session, lets you chat with each one, and answers their questions and approvals. It runs no AI tools itself.
- The Flockbox agent runs on each of your computers. It starts the providers' own command-line tools (Claude Code, Codex, Gemini CLI, Cursor, Grok) headless, with your accounts, in the folders you choose, and streams what they do to your phone.
The app can also talk directly to API providers (Hermes Agent's API server, Claude API, OpenAI-compatible APIs, Cursor Cloud Agents, Jules). Those don't need the agent.
Requirements
- macOS, Linux or Windows (x64 or ARM).
- Node.js 22 or newer. If it's missing, the installer puts a private copy in
~/.flockbox/node. - An account for each AI tool you use (see Providers).
- The computer on, with the agent running, while you use it from your phone.
Install, update, remove
curl -fsSL https://flockbox.app/install.sh | bash& ([scriptblock]::Create((irm https://flockbox.app/install.ps1)))The installer puts the agent in ~/.flockbox/lib and the flockbox command on your PATH (~/.local/bin on macOS and Linux, your user PATH on Windows), then runs flockbox setup. Options: --no-setup (-NoSetup on Windows) installs without starting the setup.
Updates
The agent checks for a new version of itself every six hours and installs it when no session is running. flockbox upgrade does it now. Running the install command again also updates, and keeps your settings and pairings.
Removing it
flockbox service uninstallstops it starting at login.- Delete
~/.flockbox(your keys, pairings and settings) and~/.local/bin/flockbox. On Windows, also remove%USERPROFILE%\.flockbox\binfrom your user PATH. - In the app, remove the computer under Setup.
Your AI tools, their sign-ins and your project folders aren't touched.
The flockbox command
| Command | What it does |
|---|---|
flockbox setup | The first-time setup: name, AI tools, start at login, pairing. A bare flockbox runs it the first time. |
flockbox add <tool> | Adds an AI tool: installs its latest version if it's missing, then runs its own sign-in. Tools: claude, codex, gemini, cursor, grok. |
flockbox login <tool> | Signs a tool in again. --api-key [key] keeps an API key for it instead (Gemini, Cursor, Grok). |
flockbox pair | Shows a QR code (and a link) to pair a phone. One use, ten minutes. |
flockbox status | The agent, the relay, start at login, paired phones, and each tool's version and sign-in. |
flockbox devices | Paired phones. flockbox unpair <id> (or all) removes them. |
flockbox service install | Starts the agent now and at every login (systemd user service on Linux, LaunchAgent on macOS, the Startup folder on Windows). uninstall removes it. |
flockbox serve | Runs the agent in this terminal instead (Ctrl+C stops it). |
flockbox install <tool> | Installs (or reinstalls) a tool's latest version without signing in. |
flockbox update [tool] | Updates the AI tools now (also done every six hours). |
flockbox upgrade | Updates the Flockbox agent itself. |
flockbox config | Shows or changes settings. |
Settings
flockbox config <setting> <value>, then restart the agent (flockbox service install).
| Setting | Default | Meaning |
|---|---|---|
name | the computer's name | How the app shows this computer. |
relay | default | The relay phones use away from home. off: only your network and Tailscale. Or your own relay's wss:// address. |
auto-update | on | Keep the AI tools and the agent up to date on their own. |
address | none | Another address phones can reach this computer at (a DNS name, a reverse proxy). address-remove removes one. |
public | off | Accept direct connections from public IP addresses. Not needed with the relay. |
port | 7787 | The port the agent listens on. |
Providers
| Tool | Installed with | Signs in with | Permission modes |
|---|---|---|---|
| Claude Code | Anthropic's installer | Your Claude account (claude auth login) | default (asks you), acceptEdits, plan, bypassPermissions |
| Codex | npm (@openai/codex) | ChatGPT or an API key (codex login) | workspace-write, read-only, danger-full-access |
| Gemini CLI | npm (@google/gemini-cli) | Google (its first-run screen) or GEMINI_API_KEY | auto_edit, default, yolo |
| Cursor CLI | Cursor's installer | cursor-agent login or CURSOR_API_KEY | default, force |
| Grok Build | xAI's installer (macOS, Linux) | XAI_API_KEY | default |
API keys saved with flockbox login <tool> --api-key are kept in ~/.flockbox/secrets.json (readable only by you) and passed to that tool only when it runs.
Sessions and folders
- The home screen lists every Claude Code session on each computer (including ones you started in a terminal there), and every session started from the app with any tool, newest first.
- Folders are chosen per session in the app: a recent one, one you browse to, or a new folder you create while browsing. Without a choice, each session gets its own new folder:
~/Flockbox/<tool>/<session id>. - A Claude Code session that's open in a terminal on the computer can't take a second writer, so replying from the phone continues it in a copy.
- Long-press a session to rename it or hide it from the list. Hiding never deletes the tool's own history.
- Claude Code cloud sessions (claude.ai/code) aren't listed: the Claude CLI can't list them or read them back.
Approvals and permissions
Claude Code in the default mode asks before anything that needs approval (running a command, editing a file), and you answer Allow or Deny in the chat. The session shows Waiting for you until you do, on the home screen too. The other tools can't stop to ask while running headless, so their permission mode decides what they may do on their own; pick the strictest one that still lets them do the job.
Connecting from anywhere
The phone tries every address it knows for a computer at once and uses the best one that answers:
- Your network: the computer's address on your Wi-Fi. Fastest, direct.
- Tailscale, if the computer is on a tailnet.
- The relay (
flockbox.app/relay): the agent keeps one outgoing connection to it, so the phone can reach the computer from any network, with nothing opened on your router.
The relay only passes encrypted messages along. It can't read them, change them, or pose as your computer or your phone; to connect, an agent has to prove it holds its private key. Turn it off with flockbox config relay off.
Security
- Pairing: the QR code holds the computer's public key, its addresses and a one-time code (ten minutes, rate-limited). The phone checks that the answer really comes from the key in the QR code, and the app always asks before it pairs.
- End-to-end encryption: every message between phone and computer is encrypted and authenticated (X25519 and XSalsa20-Poly1305, NaCl box). Each time the app connects, both sides make throwaway keys that exist only in memory (forward secrecy): even a key stolen later can't unlock earlier traffic.
- No replays: every request is time-stamped and carries a one-off number; replies and event streams are tied to the request that asked for them.
- Who may connect: directly, only your own network and Tailscale; from elsewhere, only through the relay; and in every case only paired phones.
- Keys: on the phone in the iOS Keychain or Android Keystore; on the computer in
~/.flockbox, readable only by you.flockbox unpairor Setup in the app removes a phone.
Files
In ~/.flockbox | What it is |
|---|---|
identity.json | The agent's key pair (private: keep it to yourself). |
devices.json | Paired phones. |
config.json, secrets.json | Settings, and API keys for tools that use them. |
sessions.json, transcripts/ | Sessions started from the app, and transcripts for tools whose history can't be read back. |
agent.log | The background agent's log. |
lib/, bin/, node/ | The agent, the flockbox command, and its private Node.js (if it needed one). |
Session folders made by default are in ~/Flockbox (capital F), separate from the agent's own files.
Troubleshooting
The app can't reach the computer
Run flockbox status on it. If the agent isn't running, start it: flockbox service install. If the relay says "not connected", check the computer's internet connection; it reconnects on its own. On the same Wi-Fi it should work even without the relay.
"That pairing code was wrong or has expired"
Each code works once, for ten minutes. Run flockbox pair again.
"This computer no longer knows this phone"
The phone was unpaired on the computer, or ~/.flockbox was reset. Remove the computer in the app and pair again.
A tool says it isn't signed in
On the computer: flockbox login <tool>, then check with flockbox status.
"flockbox: command not found" after installing
Open a new terminal (the installer added it to your PATH), or run it directly: ~/.flockbox/bin/flockbox (%USERPROFILE%\.flockbox\bin\flockbox.cmd on Windows).
The agent stops when I log out (Linux)
Allow your user's services to keep running: loginctl enable-linger $USER.
Where are the logs?
~/.flockbox/agent.log on macOS and Windows; journalctl --user -u flockbox on Linux.