Codeman: A Self-Hosted Control Plane for AI Coding Agents That Runs Them 24/7

What Codeman Actually Solves

AI coding agents like Claude Code and Codex are interactive by default. They expect a terminal, they pause when idle, and they stop when you close the laptop. Codeman addresses that by running each agent inside a persistent tmux session, so the process survives network drops and machine restarts. It also adds a web dashboard that streams the live terminal to any browser, which means you can check on an agent from a phone or a second computer. The README mentions re-prompting on idle and resuming when a usage limit resets, both of which are aimed at long unattended runs. This is for developers who want to kick off a large refactor or a multi-hour migration and come back later, not for someone who just wants a pretty wrapper around a single command.

Persistent Sessions and Input Delivery

The core mechanism is tmux. Codeman spawns each agent inside a tmux session, and the web UI connects to that session. The README claims tmux persistence across restarts and network drops, and exactly-once input delivery. That last point is worth attention, because sending keystrokes to a tmux session is not the same as sending them to a real terminal. The project has to handle the timing and the escape sequences correctly, or agents will see garbage. The documentation does not explain how it guarantees exactly-once delivery, so you should test it with your specific CLI before relying on it. The live floating windows for subagents are a differentiator: they show transcripts in real time, which is useful when Claude Code spawns parallel subagents. But again, the README does not detail the protocol, so treat it as a feature to verify.

Installation and First Run

The one-line installer is the primary path: `curl -fsSL https://getcodeman.com/install | bash`. It installs Node.js, tmux, and a build toolchain if missing, because node-pty ships no Linux prebuilds and must compile from source. It clones the app to `~/.codeman/app` and builds it. The installer is interactive: it prompts before every system change, and at the end offers to run Codeman in the terminal, install it as a background service, or do nothing. A bare Enter never pulls in new software, which is a good safety property. After install, you run `codeman web` and open `http://localhost:3000`. The default bind is loopback-only, which is the safest option. For a team, the README shows `codeman users add alice --admin` and `codeman web --multiuser` to create named logins and per-user workspaces. The installer also supports Tailscale as a reachability option, fronting the loopback bind with `tailscale serve` so you get a real certificate and no password needed.

Running in the Background and as a Service

For long-running use, `codeman web -d` detaches and logs to `~/.codeman/web.log`. The `-d` flag waits until the server actually answers before reporting success, and it refuses to start a second server on the same data dir, because two servers sharing a tmux socket would attach to each other's sessions. That is a real constraint: you cannot run two instances on the same machine with the same data directory. For reboot persistence, `codeman service install` writes a systemd user unit on Linux or a LaunchAgent on macOS. The README warns that launchd hands a job a limited PATH, so a Homebrew or nvm `node`, `tmux`, or `claude` is invisible to a hand-written plist. The service install bakes in your current PATH, which solves that. It never copies `CODEMAN_PASSWORD` into the unit file, so you must add auth manually if the service needs it.

Scheduling and Unattended Operation

The README mentions scheduled jobs and a respawn controller that handles idle detection and cycling. It says Codeman re-prompts on idle and resumes when a usage limit resets, for 24+ hour unattended runs. That is the core value proposition, but the documentation gives no details on how to define a schedule or configure the respawn policy. There are no example config keys in the README for cron-like syntax or idle timeout thresholds. This is a gap. You can run agents without scheduling, but if you want scheduled jobs, you will need to explore the web UI or the source to find the exact settings. The README also notes that Gemini CLI is enterprise-only since Google's consumer cutover, and Antigravity is its successor, so the list of supported CLIs is not static.

Security and Privacy Trade-offs

The project is self-hosted and MIT licensed, with no telemetry, and the default bind is loopback-only. That is a strong privacy stance. But the README offers a network-wide bind (`0.0.0.0`) with a password prompt, and it warns that skipping the password requires an explicit confirmation and ends with a loud warning. The Tailscale option is interesting because it uses your tailnet as the login, so there is no password to manage. However, the service install does not copy `CODEMAN_PASSWORD` into the unit file, which means if you rely on a password for auth, you must handle that yourself. The README does not mention encryption at rest for session logs or transcripts, so if you run sensitive code, you should consider what is stored in tmux scrollback and in the dashboard's replay buffer.

Limitations and Failure Modes

The most obvious limitation is that Codeman only supports the seven listed CLIs: Claude Code, OpenCode, Codex, Antigravity, Gemini, Pi, and Grok, plus plain shell. If you use a different agent, it will not work. The README also says node-pty ships no Linux prebuilds, so the install compiles from source, which means you need a working build toolchain and the compile can fail on some systems. The installer is interactive, and in CI or headless environments, steps that would change your system abort with instructions unless you set `CODEMAN_NONINTERACTIVE=1`. That is a deliberate safety feature, but it means automation requires an extra step. Another failure mode is the two-server restriction: if you accidentally start a second server on the same data dir, it refuses to start, which is good, but it also means you cannot easily have a separate dashboard for a different set of sessions without a separate data dir.

Alternatives and How They Differ

The main alternative is running agents directly in your own tmux or screen sessions, with no dashboard. That gives you persistence and detachment, but you lose the web UI, the subagent visualization, and the idle re-prompting. Another alternative is a hosted service like Anthropic's Claude Code web interface or OpenAI's Codex cloud, but those are not self-hosted and may not support all the CLIs. A closer comparison is to use a generic terminal multiplexer with a web frontend, like ttyd or Wetty, and then manually start each agent inside it. That approach gives you a browser terminal but no scheduling, no per-agent respawn logic, and no multi-user workspace management. Codeman's advantage is that it is purpose-built for AI agents, with features like idle detection and usage-limit resume that a generic terminal does not provide. The trade-off is that you are tied to its specific implementation and its supported CLI list.

Editorial conclusion

Adopt Codeman if you run AI coding agents unattended for hours or days and need a single, private, browser-accessible control point. It is a good fit for solo developers and small teams who already use tmux or need to watch subagents live. Do not adopt it if you require a managed cloud service, if you cannot handle a Node.js build toolchain, or if you need support for CLIs beyond the seven listed. Before committing, verify that your target AI CLI works with tmux input delivery, test the installer's interactive prompts in your environment, and confirm that the loopback-only default plus your network binding choice satisfies your security requirements. The project is MIT licensed with no telemetry, but the maintenance cost of compiling node-pty and updating via the installer is real.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes