Codeman MCP server

Codeman is a self-hosted mission control for AI coding agents. It spawns Claude Code, OpenCode, Codex, Antigravity, Gemini, Pi, Grok, DeepSeek Harness, OMP, or GitHub Copilot CLI inside persistent tmux sessions, streams the real terminal to any browser, and keeps agents productive after you walk away: it re-prompts on idle, resumes when a usage limit resets, runs scheduled jobs, and shows every background agent working in real time.

Get started in one line (macOS & Linux, Windows via WSL):

curl -fsSL https://getcodeman.com/install | bash

codeman web
# Open http://localhost:3000 and start your first session

The installer asks before every system change, and re-running the same line updates in place. Full details: Quick Start - Installation.

On a Mac you can skip the terminal: download Codeman.dmg, and the app installs Codeman for you, opens the one already running, or connects to one on another machine. More in On a Mac: the Codeman app.

• One dashboard, ten CLIs - run Claude Code, OpenCode, Codex, Antigravity, Gemini, Pi, Grok, DeepSeek, OMP, or GitHub Copilot per session (plus plain shell), locally, in Docker, or over SSH, with your own dashboards open as web tabs beside them
• Truly phone-friendly - a touch-optimized terminal with instant local echo, QR login, swipe navigation, and push notifications
• Runs while you sleep - idle detection + respawn cycling and auto-resume when a subscription limit resets, for 24+ hour unattended runs
• See your agents think - live floating windows for every subagent and teammate, with real-time transcripts
• Agents can drive it too - the codeman skill (for every agent CLI), codeman agent and an MCP server let one agent start workers in any CLI, prompt them, wait for them and collect their answers
• Nothing gets lost - tmux persistence across restarts and network drops, exactly-once input delivery, full-scrollback replay
• Self-hosted and private - loopback-only by default, MIT licensed, no telemetry, runs entirely on your machine

---

Quick Start - Installation

curl -fsSL https://getcodeman.com/install | bash

This installs Node.js, tmux and a build toolchain if missing (node-pty ships no Linux prebuilds, so it compiles from source), clones Codeman to ~/.codeman/app, and builds it. It looks at what is already on the machine, asks at most three questions, then does all the work unattended and ends on the URL with a QR code for your phone. A few things worth knowing:

• Three questions, all up front. How the dashboard is reached, optionally what to call this machine on your tailnet, and whether to run Codeman as a background service (systemd/launchd, auto-start on boot; Enter says yes). Everything that needs you, including one consent for all missing packages, one sudo password, and the Tailscale login, happens before the build, so you can walk away while it compiles.
• How it's reachable, your choice. Tailscale (loopback bind fronted by tailscale serve, so you get https://<machine>.<tailnet>.ts.net with a real certificate and your tailnet as the login, no password needed), any device on your network (0.0.0.0, with a strongly recommended password prompt), or this machine only (127.0.0.1, safest). Skipping the password on a network bind requires an explicit confirmation and ends with a loud warning. The highlighted default reflects what is already on the machine (Tailscale when it is already connected, your existing binding on a re-run), and a bare Enter never pulls in new software. If another app already owns :443 on your node, Codeman goes under https://<machine>.<tailnet>.ts.net/codeman or on a second port instead of replacing it. A bare codeman web started by hand still defaults to loopback.
• The name is yours to choose. By default the URL uses the machine's existing tailnet name. Answering yes to the second question renames the machine to codeman-<hostname> (which also renames it for SSH, so the default is no); install.sh name does it later.
• Re-run to update. The same one-liner updates a finished install in place: local changes in ~/.codeman/app are stashed (never discarded), and a running service is restarted and verified. If a first install was interrupted, re-running resumes the full setup instead. install.sh status prints the URLs and the QR code again; install.sh update, install.sh tailscale and install.sh uninstall also exist.
• No administrator rights needed. On an account without sudo, one whose sudo rights the installer cannot confirm (outside the sudo, wheel and admin groups, with a password still required) or a Mac account that is not an administrator and has no Homebrew it can write to, the installer downloads Node.js from nodejs.org and the tmux project's own build into ~/.codeman/runtime, each checked against its SHA-256, and takes the source as an archive when there is no working git. --no-admin forces that route and CODEMAN_NO_ADMIN=0 turns it off. Two limits: Linux needs make, a C++ compiler and python3 to be there already, and the tmux download needs macOS 15 or newer. Details in the wiki.
• Flags for the impatient. curl -fsSL https://getcodeman.com/install | bash -s -- --tailscale --service answers the questions from the command line (--lan, --local, --run, --no-start, --name <n>, --port <n>, --yes too). CI / headless: without a terminal attached, steps that would change your system abort with instructions instead of running silently; set CODEMAN_NONINTERACTIVE=1 to approve them for automation.

You'll need at least one AI coding CLI installed — Claude Code, OpenCode, Codex, Antigravity, Gemini CLI, Pi, Grok Build, DeepSeek Harness, OMP, or GitHub Copilot CLI (any combination works; Gemini CLI is enterprise-only since Google's consumer cutover, and Antigravity is its successor). The installer detects whichever of the ten is present; if none is found, it offers to install any of them from a menu (DeepSeek excepted, since its npm package installs only a launcher with no runnable profile), or you can skip and install one yourself later. After install:

codeman web
# Open http://localhost:3000 and start your first session

Sharing with a small team? Start it in multi-user mode instead: each person gets their own login and workspace.

codeman users add alice --admin      # create the first admin account
codeman web --multiuser              # named logins + per-user case spaces

Details in Multi-User Mode below.

Prefer Docker Compose? Clone the repo and run one script (Linux, Docker with the Compose v2 plugin):

git clone https://github.com/Ark0N/Codeman.git && cd Codeman
bash docker/Start-Codeman.sh

The first run asks three questions (data folder, port, password; Enter takes the default, including a generated password), writes docker/.env for you, builds the image and ends on the URL once Codeman answers. The image already includes Claude Code, Codex, Gemini CLI and OpenCode. Codeman runs in a container and spawns Docker cases as sibling containers through the host socket. To update, use App Settings → Updates, or git pull and run the script again rather than a plain docker compose up, so the rebuilt image, refreshed volumes and entrypoint arrive together. See the Docker deployment guide for Unraid, direct Compose commands, storage and networking options.

On a Mac: the Codeman app

Download Codeman.dmg · one universal app for Apple Silicon and Intel · macOS 11.3 or later

A small native app that opens Codeman in its own window. On a Mac without Codeman it installs it for you, with no Terminal and no administrator password, shows the install as a checklist, and offers to install a coding agent if the Mac has none yet. On a Mac that already runs Codeman it finds the server and opens it, or starts it when it is stopped. Under Another machine it connects to Codeman on your Mac mini, a home server or your tailnet, with the password kept in the Keychain, and can start an install over there through SSH. On a MacBook Pro with a PROLED XDR display, whose lid logo lights up, View > Blink Apple Logo makes the logo show what your agents are doing: it breathes while they work, blinks when one waits for you and flashes when one needs permission, and each state can take a style of your own. It stays off until you turn it on. The app is Rust around macOS's own WebKit, not a bundled browser, so the download is under 5 MB.

Open Codeman.dmg, drag Codeman into Applications and open it from there. macOS asks once whether to open an app downloaded from the internet: click Open.

• Quitting the app doesn't stop Codeman. An install from the app runs Codeman as a LaunchAgent that starts at login, so your agents keep working with the window closed, and your browser and phone reach it as before.
• Codeman's page needs the WebKit of Safari 16.4. The app starts on macOS 11.3, but Codeman itself needs macOS 13.3 or later, or macOS 11 or 12 with Safari 16.4 or later installed. On an older WebKit the app says so and does not connect.
• The install from the app needs macOS 15, or a tmux that is already there. tmux comes from the tmux project's own builds, which need macOS 15. On an older Mac without tmux the app offers Terminal instead, where Homebrew installs it (that takes an administrator once).
• Updating. The app doesn't update itself yet: download the new Codeman.dmg and drag it over the old copy.

First launch, known limits and how to build it yourself: Installation in the wiki and packages/desktop/README.md.

To outlive the shell you started it in, without setting anything up:

codeman web -d          # detach; logs to ~/.codeman/web.log
codeman web --status    # is it up, and on which pid
codeman web --stop      # graceful SIGTERM; agents keep running in tmux

-d waits until the server actually answers before reporting success, and refuses to start a second one on the same data dir (two servers sharing a tmux socket attach to each other's sessions).

To have it come back after a reboot, install it as a service instead. The installer's final menu does this for you (option 2); codeman service is the equivalent for an npm i -g aicodeman install:

codeman service install     # systemd user unit (Linux) or LaunchAgent (macOS)
codeman service status
codeman service uninstall

service install writes the unit with your current PATH baked in, which matters more than it sounds: launchd hands a job /usr/bin:/bin:/usr/sbin:/sbin, so a Homebrew or nvm node, tmux or claude is invisible to a hand-written plist. It never copies CODEMAN_PASSWORD into the unit file; add that yourself if the service needs auth.

To write the unit by hand instead:

Linux (systemd):

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/codeman-web.service << EOF
[Unit]
Description=Codeman Web Server
After=network.target

[Service]
Type=simple
ExecStart=$(which node) $HOME/.codeman/app/dist/index.js web
Restart=always
RestartSec=10

[Install]
WantedBy=default.target
EOF
systemctl --user daemon-reload
systemctl --user enable --now codeman-web
loginctl enable-linger $USER

macOS (launchd):

mkdir -p ~/Library/LaunchAgents
cat > ~/Library/LaunchAgents/com.codeman.web.plist << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.codeman.web</string>
  <key>ProgramArguments</key>
  <array>
    <string>$(which node)</string>
    <string>$HOME/.codeman/app/dist/index.js</string>
    <string>web</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key>
  <string>/tmp/codeman.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/codeman.log</string>
</dict>
</plist>
EOF
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.codeman.web.plist

wsl bash -c "curl -fsSL https://getcodeman.com/install | bash"

Codeman requires tmux, so Windows users need WSL. If you don't have WSL yet: run wsl --install in an admin PowerShell, reboot, open Ubuntu, then install your preferred AI coding CLI inside WSL (Claude Code, OpenCode, Codex, Antigravity, Gemini CLI, Pi, Grok Build, DeepSeek Harness, or OMP). After installing, http://localhost:3000 is accessible from your Windows browser.

---

Mobile-Optimized Web UI

The most responsive AI coding agent experience on any phone. Full xterm.js terminal with local echo, swipe navigation, and a touch-optimized interface designed for real remote work — not a desktop UI crammed onto a small screen.

• Keyboard accessory bar — /init, /clear, /compact quick-action buttons above the virtual keyboard; destructive commands require a double-press to confirm, so you never fire one by accident; on Codex sessions the bar also shows ⇧← / ⇧→ (Shift+Left / Shift+Right: edit the last queued message / return through the prompt stack)
• Dedicated Enter button — replays the keypress through the terminal, so text buffered by local echo is flushed first rather than stranded
• Attach button: the picture icon beside the mic opens the system photo and file sheet without raising the keyboard. Photos and camera-roll videos (mp4, mov, webm, up to 1 GB) upload into the session's folder and their path lands on your prompt, unsent
• Paste in a shell: a multi-line paste goes in as one block and waits for your Enter, instead of running line by line as it arrives
• Swipe navigation & smart keyboard handling — swipe left/right to switch sessions; toolbar and terminal shift up when the keyboard opens (visualViewport API)
• Built for phones — safe-area insets for notch and home indicator, 44px touch targets, bottom-sheet case picker, native momentum scrolling; on a folding phone (iPhone Duo) dialogs stay clear of the hinge, and opening or closing the device is never mistaken for the keyboard

codeman web --https
# Open on your phone: https://<your-ip>:3000

localhost works over plain HTTP. Use --https when accessing from another device, or use Tailscale (recommended): the installer can set it up for you (choose Tailscale at the network-access prompt, or run bash ~/.codeman/app/install.sh tailscale on an existing install). That gives you https://<your-machine>.<tailnet>.ts.net with a real certificate: private to your tailnet, no password required, and PWA install + push notifications work on your phone. The installer ends on that URL with a QR code to scan, and bash ~/.codeman/app/install.sh status prints it again any time.

Secure QR Code Authentication

Typing passwords on a phone keyboard is miserable. Codeman replaces it with cryptographically secure single-use QR tokens — scan the code displayed on your desktop and your phone is authenticated instantly.

Each QR encodes a URL containing a 6-character short code that maps to a 256-bit secret (crypto.randomBytes(32)) on the server. Tokens auto-rotate every 60 seconds, are atomically consumed on first scan (replays always fail), and use hash-based Map.get() lookup that leaks nothing through response timing. The short code is an opaque pointer — the real secret never appears in browser history, Referer headers, or Cloudflare edge logs.

The security design addresses all 6 critical QR auth flaws identified in "Demystifying the (In)Security of QR Code-based Login" (USENIX Security 2025, which found 47 of the top-100 websites vulnerable): single-use enforcement, short TTL, cryptographic randomness, server-side generation, real-time desktop notification on scan (QRLjacking detection), and IP + User-Agent session binding with manual revocation. Dual-layer rate limiting (per-IP + global) makes brute force infeasible across 62^6 = 56.8 billion possible codes. Full security analysis: docs/qr-auth-plan.md

---

Using Codeman — A Human's Guide

A start-to-finish walkthrough for driving Codeman from the browser. If you just installed, this is where to begin.

1. Launch the server

codeman web                       # localhost:3000 (loopback only — safe default)
codeman web --port 8080           # custom port (or set CODEMAN_PORT)
codeman web --https               # self-signed TLS (only needed for remote access)
codeman web -H 0.0.0.0            # bind LAN — REQUIRES CODEMAN_PASSWORD (see Security)
codeman web -d                    # detach: survives closing the shell (--status, --stop)
codeman service install           # systemd/launchd service: comes back after reboots

Open the printed URL. The page is a single dashboard; everything below happens there.