Sidefleet

Run coding agents on your own machines, from anywhere.

Website · Install · Quick start · API

[!NOTE] Sidefleet is under active development: expect rough edges, and things may change between versions.

Type a task on a web page, pick an agent, a model and a repo, and a machine you own picks it up: your desk Mac, a Mac mini, a VPS. It runs Claude Code, Codex or opencode in its own git worktree and streams the agent's narration back live; reply to keep the conversation going. No API keys for Claude or Codex: it uses the login already on that machine. opencode brings any other model (Kimi, GLM, DeepSeek, Qwen through OpenRouter, or local ones). No open ports: machines only make outbound calls to your control plane. One Rust binary, macOS and Linux.

 browser ──HTTP/SSE──▶ sidefleet serve   (control plane: web page + API + Postgres)
                              ▲
                              │ outbound HTTP only (register, heartbeat, claim, events)
                              │
                       sidefleet run ──spawns──▶ claude -p / codex exec --json / opencode run --format json
                       (worker on your Mac, VPS, Linux box: cwd = the repo)

Features

• Bring your agent: Claude Code, Codex or opencode, chosen per task. Each one runs as its own CLI with its own sign-in, and its output is mapped to the same live view. Tasks only go to machines that have the chosen agent.
• Your machines, one page: every connected machine with its repos, agents, CPU and running tasks on a live fleet map. Tasks go to the least busy machine that has the repo and agent, or pin one to a machine. Machines can be signed in to different accounts: when one hits its usage limit, its task moves to another machine and the page shows "usage limit until 14:00".
• Isolated by default: each task gets its own git worktree and branch (sidefleet/<id>), so several tasks on one repo run side by side without touching your checkout. Choose "In place" when a task needs installed dependencies or local config.
• Survives a machine dropping (opt-in per task): with "Move if it drops", the worker commits and pushes the task's branch to the repo's origin at most once a minute while the agent edits. If the machine stops responding (a laptop going to sleep), the task moves to another machine with the repo and continues from the last pushed commit, with a digest of the thread so far. Off by default, because it pushes; only the task's own sidefleet/... branch is ever pushed.
• Restore: every message's files are snapshotted before and after it, so "Restore to before" puts the worktree back to how it was before any message. The conversation carries on, and a restore can itself be undone.
• Fork: start a new thread from any message, with any agent and model (say, a Claude Code thread continued in Codex). The new thread starts on its own branch with the files as they were after that message, and its agent gets the conversation up to there as a transcript.
• Live, and a conversation: events stream over SSE within milliseconds, survive reloads and dropped connections, and replies resume the same agent session like a chat. Reply while it works and the message waits its turn, or press Send now to interrupt. Screenshots and other images the agent opens show inline, so you can ask for one from your phone. Drop, paste or attach images to a task or reply and the agent gets them too.
• Waiting on you: a bell lists every task that needs you, with why and for how long: finished and waiting for a reply, failed, paused on a usage limit, or its machine dropped. Each such task also gets a marker in the sidebar. A task leaves the list when you open it, reply or dismiss it, and what you have seen is kept on the control plane, so it is the same on your phone and laptop. Turn on "Notify me" for a push notification when a task starts waiting; it carries only the task's title and the reason, never agent output. Browsers only allow push on HTTPS pages or localhost (on iPhone, add the page to the Home Screen first). serve creates the VAPID key for it in ~/.sidefleet/server.env; elsewhere set SIDEFLEET_VAPID_PRIVATE_KEY.
• Build with your team (hosted mode): invite people to your org with a link, and everyone sees the team's threads, diffs and PRs. Machines are not shared: each runs only its owner's tasks, under its owner's agent sign-in. To pick up a teammate's work, "Continue on my machine" forks it onto yours. See Teams and rooms.
• Chat with your fleet: connect the AI assistant you already chat with (Hermes, OpenClaw, Claude Code or any MCP client) on the Chat apps page, and run and check tasks from Telegram, WhatsApp or Discord: "fix the failing test in my web repo", "how did it go?", "open a PR". You choose what it may do: check on tasks, run them, or also approve commands. With updates in chat on, it messages you when a task finishes, fails or needs your OK, and you answer right there.
• Permission modes: full access for unattended commands (the default for new tasks on the page), read and edit files, read only for questions, or "Ask me": Claude Code edits files on its own and asks you on the page (phone included) before anything else, such as a shell command, and waits for Approve or Deny.
• Zero-config workers: connect checks which agents are installed and signed in, finds your git checkouts (repos match by their git remote, whatever the folder is called), and installs a launchd or systemd service that survives reboots. Or click "Copy prompt" and let Claude Code or Codex on the other machine connect itself.
• Secrets stay put: anything that looks like a credential is redacted on the worker and again on the control plane; tokens are stored as SHA-256 digests and never logged.

Install

curl -fsSL https://raw.githubusercontent.com/foodaka/side-fleet/main/install.sh | sh

Downloads a prebuilt sidefleet into ~/.local/bin (no sudo), or builds from source when there is no release for your platform.

While the repository is private, the raw URL returns 404. Use the GitHub CLI (gh auth login), which the script then uses for the download:

gh api repos/foodaka/side-fleet/contents/install.sh -H "Accept: application/vnd.github.raw" | sh

Or clone over SSH and build from the checkout, never contacting GitHub:

git clone [email protected]:foodaka/side-fleet.git && sh side-fleet/install.sh

Quick start

1. Start the control plane on the machine that will host the page. It needs Postgres:

docker run -d --name sidefleet-db --restart unless-stopped \
  -e POSTGRES_USER=sidefleet -e POSTGRES_PASSWORD=sidefleet -e POSTGRES_DB=sidefleet \
  -p 5432:5432 -v sidefleet-pgdata:/var/lib/postgresql/data postgres:16-alpine
sidefleet serve

Sidefleet control plane is running.

  Open the page:        http://<this-machine>:7373/
  Developer key:        3f9c…
  Connect a machine:    sidefleet connect --control http://<this-machine>:7373 --token 7b2e…

Keys are saved to ~/.sidefleet/server.env. If the machine has a coding agent installed, serve runs a worker on it too, so a single box is one command.

2. Open the page and paste the developer key.

3. Connect more machines. On any machine with an agent set up (see Agents), run the install line, then the connect line the page shows you. The page switches to the compose box as soon as the first heartbeat lands.

Across networks, put the control plane on Tailscale and use its tailnet IP: no port forwarding, no public exposure. Running it on a VPS or a spare machine is covered in HOSTING.md.

No token at hand? sidefleet connect --control <url> without --token asks the control plane to let the machine in: it prints a link and a short code, and the machine joins once someone approves it under Pending machines on the Machines page (the request expires after ten minutes).

Hosted, multi-tenant mode. Setting SIDEFLEET_GITHUB_CLIENT_ID, SIDEFLEET_GITHUB_CLIENT_SECRET and SIDEFLEET_PUBLIC_URL turns on GitHub sign-in, orgs, per-org worker tokens and plan limits. What it stores and how to deploy or try it locally: HOSTED.md.

Teams and rooms

On a hosted control plane, an org is a team workspace:

• Invites. On the Team page, owners make an invite link for one person or many, valid for 1 to 30 days. Whoever opens it signs in with GitHub and joins. Removing someone revokes their machines' tokens and stops their queued tasks.
• Whose work is whose. Every task records who started it, with their avatar in the sidebar; switch between Mine and Team to see your tasks or everyone's. Only a thread's creator can reply, restore, approve its commands or open its PR. The bell and push notifications are only for your own tasks.
• Your machines stay yours, in every org. A machine runs only the tasks of the person who connected it, in every org they belong to: connect it once, and joining a team needs nothing more. It counts against the plan of the org it connected to.
• Rooms are for working toward one goal together. A room has a goal in one repo, the team's notes, and tasks that each run on their owner's machine, in their own worktree. When a task is done, its owner presses Add to room to merge its branch into the room branch (sidefleet/room-<id>, never force-pushed), and new tasks then start from it. Every task's agent gets a brief with the goal, the notes and what the other tasks are doing, so it doesn't redo or undo a teammate's work. A merge conflict shows its files on the task card, with Ask my agent to fix. When the work is finished, Compare on GitHub opens the room branch for one PR.

How it's designed, and what comes next, is in docs/multiplayer/.

Agents

Agent	Set it up on the machine	Models
Claude Code	claude, sign in once	Opus, Sonnet, Haiku
Codex	codex login (ChatGPT sign-in or API key)	what codex debug models lists for the account, or its default
opencode	opencode auth login, e.g. OpenRouter; or add OPENROUTER_API_KEY=… to ~/.sidefleet/worker.env	any provider/model it lists, e.g. openrouter/moonshotai/kimi-k2

sidefleet connect reports which agents it found and whether they are signed in, and the Machines page shows the same. Local models (Ollama, LM Studio) run through opencode once you add them as an opencode provider.

The page's permission modes map onto each agent:

Mode	Claude Code	Codex	opencode
Read & edit files	acceptEdits	sandbox workspace-write (commands run sandboxed, no network)	shell denied
Full access	bypassPermissions	no sandbox	all permissions granted
Read only	plan	sandbox read-only	plan agent, edits, shell and fetches denied
Ask me	acceptEdits, other tools asked on the page	not offered yet	not offered yet

With "Ask me", a tool call that acceptEdits would refuse shows on the page as a card with Approve and Deny, and the thread is marked "Waiting on you" in the sidebar. The agent waits until you decide, or denies the call after 15 minutes (sidefleet run --approval-timeout <secs>). Claude Code's acceptEdits already lets simple file commands in the workspace (mkdir, rm, ls) through without asking; everything else, such as running a script, a network call or an MCP tool, is asked.

Whatever you have already allowed Claude Code on that machine still applies: rules in ~/.claude/settings.json, and the checkout's own .claude/settings.local.json (where "don't ask again" answers go), which the worker copies into each task's worktree while git ignores it.

Command line

sidefleet serve                       # control plane on :7373, plus a local worker
sidefleet serve --no-worker           # control plane only
sidefleet serve --install-service     # run serve as a background service
sidefleet connect --control <url> --token <t>   # register this machine, install the service
sidefleet connect --control <url>     # no token: wait for approval on the Machines page
sidefleet connect … --name "Mac mini" --parallel 3 --permission-mode bypassPermissions
sidefleet status                      # saved settings, service and process state, log path
sidefleet disconnect                  # remove the service (settings kept)
sidefleet run                         # worker in the foreground with the saved settings
sidefleet detect                      # what this machine can run, as JSON
sidefleet update                      # pull the latest, reinstall, restart services

Every flag can also come from the environment (SIDEFLEET_BIND, DATABASE_URL, SIDEFLEET_DEV_KEY, SIDEFLEET_WORKER_TOKENS, …), a .env in the current directory, or ~/.sidefleet/server.env / worker.env. sidefleet <command> --help lists them all. Worker logs are in ~/.sidefleet/logs/.

The HTTP API and the lifecycle of a run are documented in docs/API.md.

Develop

docker compose up -d --wait      # Postgres for local runs and tests
cargo test --workspace           # integration tests create and drop sidefleet_test_* databases
cargo run -p sidefleet -- serve

The web UI's build output in crates/server/web-dist/ is committed so Rust-only installs keep working, but only by CI: after a change to web/ lands on main, the web-dist workflow rebuilds it and commits the result. Pull requests change web/ only and leave web-dist/ alone (CI fails otherwise); run pnpm build in web/ to try a change locally, then git checkout crates/server/web-dist before committing. Tagging vX.Y.Z builds release binaries for macOS (arm64, x86_64) and Linux (x86_64, arm64).

Layout

• crates/core: shared models, the agents and the mapping of each one's output to events, redaction.
• crates/server: Axum control plane, Postgres via sqlx migrations; embeds the web app.
• crates/worker: machine detection, control-plane client, process-group executor, worker loop.
• crates/cli: the sidefleet binary.
• web/: the web UI, SvelteKit + shadcn-svelte. See web/README.md.
• site/: the website at www.sidefleet.xyz, one static page. See site/README.md.

Known limitations

• This drives your own agent sign-ins, headless (Claude, ChatGPT, or the API keys opencode uses). Usage counts against those accounts' plans or bills. Check the terms that apply to your subscriptions for automated or unattended use, and never share or resell access to an account through it.
• Self-hosted, there is a single shared developer key and no TLS of its own. Keep that control plane on a private network (LAN or Tailscale), or run the hosted mode behind TLS (HOSTED.md).
• The control plane runs as one process: live events fan out in memory, so it does not scale out to several instances yet.
• A thread keeps the agent it started with; to switch, fork it. A fork's agent gets a transcript of the messages, replies and tool calls (the newest 32 KB), not the original session, so it doesn't see tool output or the agent's thinking.
• A fork that starts from a message's files runs on the machine that has them, so the agent you pick must be installed there.
• Restoring puts back the files, not the conversation: the agent still remembers what it did. Only tasks in their own worktree can be restored. Snapshots are kept as git refs under refs/sidefleet/snapshots/ (remove with git for-each-ref --format='delete %(refname)' refs/sidefleet/ | git update-ref --stdin).
• Codex's sandbox only writes inside the worktree, and a worktree's git data lives in the main checkout, so git commit by Codex can fail under "Read & edit files". Commit from the branch afterwards, or use Full access.
• opencode's output format was mapped from its source (1.19), not yet from a live run; its cost is what opencode reports per step.
• Only Claude Code can relay its permission prompts to the page ("Ask me"). For Codex and opencode, whatever the mode does not allow is denied.
• Worktrees start from the repo's HEAD without untracked or ignored files (node_modules, .env), and are kept until you remove them (git worktree remove, or delete the folder under ~/.sidefleet/worktrees and run git worktree prune).
• A follow-up runs only on the machine that holds the session, and waits while it is offline.
• Redaction is pattern-based: a safety net, not a guarantee.
• Windows is not supported.

License: MIT.