FAQ

FAQ

The questions that keep arriving in Discussions and issues. For "why is it doing that", go to Troubleshooting instead.

The basics

What is Codeman, in one sentence?

A self-hosted dashboard that runs AI coding agents in persistent tmux sessions on your own machine and lets you drive them from any browser, including a phone.

Is it free? What is the licence?

MIT, free, and open source. There is no paid tier and no account.

Do I need an API key?

No. Codeman drives agent CLIs you have already installed and logged in yourself. Whatever subscription or key that CLI uses is what pays for the tokens. Codeman never collects, stores, or refreshes your credentials.

Does Codeman send my code or prompts anywhere?

No. There is no telemetry, no analytics, and no phone-home. The only network traffic Codeman itself makes is between your browser and your server.

Your agent CLI is a separate matter: Claude Code talks to Anthropic, Codex talks to OpenAI, and so on. That traffic is the CLI's, on your own account, exactly as it would be in a terminal.

Two features do send data outward, both off by default and both stated where they appear: voice dictation through your own Claude login, and the Read My Mind prediction call.

Does it work on Windows?

Through WSL2. Codeman requires tmux. Install it inside WSL, run your agent CLI inside WSL, and http://localhost:3000 works from your Windows browser. Work in the Linux filesystem rather than /mnt/c/..., which is dramatically slower for file watching and git.

Is there a mobile app?

The web UI is built for phones and installs as a PWA. There is no App Store or Play Store app.

Sessions and persistence

Do my agents keep running when I close the browser?

Yes. Agents run in tmux on the server, not in your browser. Close the tab, close the laptop, lose the network. When you come back, the session is still there with its scrollback.

The same holds when the Codeman server itself restarts. What does end a session is killing the tmux server or rebooting the machine.

What happens after a reboot?

tmux dies with the machine, so the sessions are gone. Conversations are not: Claude transcripts persist on disk, and the welcome screen's Resume Conversation list picks them back up. Install Codeman as a service and the server itself comes back on boot.

How many sessions can I run at once?

The design target is 20 sessions and 50 agent windows at 60fps. The hard cap is higher, and what you will actually hit first is the CPU and memory of the machine running the agents.

Can I run Claude Code and Codex side by side?

Yes, that is a normal setup. The run mode is per session, so one case can have a Claude tab, a Codex tab, and a shell tab open at the same time, each with its own colour. Some Codeman features are Claude-only; Agent CLIs lists exactly which.

Can I attach to a session from a terminal instead of the browser?

Yes. sc is an interactive chooser (sc 2 attaches directly, sc -l lists), or use tmux directly on the codeman socket. Detach with Ctrl+A D.

Running unattended

I hit my Claude usage limit overnight. Can Codeman resume automatically?

Yes, and it is the reason the feature exists. Turn on auto-resume at the top of the Respawn tab for that session. When Claude halts on a subscription limit, Codeman parses the reset time from the message, waits until two minutes past it, and continues the conversation.

Respawn cycles are blocked while a session is limit-paused, which is what stops a /clear from wiping the conversation you are waiting to resume. Claude-only.

Will it keep prompting my agent forever?

Only if you configure it to. Respawn cycling is per session and off unless you turn it on, and it has presets ranging from a 60 minute solo session to an 8 hour overnight run. There are circuit breakers to stop a thrashing session from spinning indefinitely. See Keeping Agents Running.

Does an idle session cost tokens?

No. An idle agent is a process waiting for input. Tokens are spent when a turn runs, so what costs money is the re-prompting you configured, not the session sitting there.

Can I schedule work for a specific time?

Yes. Cron Jobs saves named jobs on a once, interval, daily, or weekly schedule; each spins up a session and sends a prompt when due, with per-job run history.

Access

How do I reach Codeman from my phone when I am away from home?

Tailscale is the recommended answer: your devices join a private network, Codeman keeps its loopback bind, and you get real HTTPS. The installer sets it up, and install.sh tailscale retrofits it onto an existing install.

A Cloudflare tunnel gives a public URL faster, and requires CODEMAN_PASSWORD. Full comparison in Remote Access.

Why can't other devices reach Codeman?

Because the default bind is 127.0.0.1, on purpose. Codeman starts agents with permission prompts skipped, so whoever reaches the dashboard can run code on your machine. Exposing it is a deliberate step, and Remote Access covers the safe ways.

My reverse proxy domain is rejected with 403 host not allowed

The always-on Host-header allowlist blocks DNS rebinding, and it does not know your domain. Add it:

CODEMAN_ALLOWED_HOSTS='codeman.example.com,.internal.example.com'

A leading dot matches subdomains. Also make sure the proxy forwards WebSocket upgrades.

Do I have to type a password on my phone?

No. Scan the QR code shown on the desktop dashboard. Tokens are single use and rotate every 60 seconds. The password remains the fallback.

Multiple people, multiple instances

Can several people share one Codeman?

Yes, with codeman web --multiuser. Each person gets a login and their own case space, and sessions, cases, search, and events are scoped to their owner.

Be clear about what that is: it separates workspaces, not operating system accounts. Every session still runs as the same OS user, so a determined user's agent can reach another user's files. For real isolation, pair users with Docker cases or run separate instances under separate OS accounts. See Multi-User Mode.

How do I run a second instance, a beta beside my main one?

Give it its own instance name, which scopes the data directory and the tmux socket together:

CODEMAN_INSTANCE=beta CODEMAN_PORT=5000 codeman web

Do not skip this. The data directory and tmux socket are process wide, so a second server on the defaults discovers and attaches your live sessions.

Updating and maintenance

What is the right way to update Codeman?

Install route	Update with
Installer	Re-run the install one-liner, or App Settings → System → Updates.
npm	npm update -g aicodeman
git clone	git pull && npm install && npm run build, then restart the service.

The in-app updater covers git-clone installs supervised by systemd or launchd. It stashes a dirty tree rather than discarding it, and streams progress across the restart. npm installs report as non-updatable.

Will updating kill my running sessions?

No. Sessions live in tmux, so restarting the server reattaches to them.

Where is my data?

Everything under ~/.codeman/, with cases created from scratch in ~/codeman-cases/. Nothing needs root and nothing leaves the machine. Uninstalling does not delete either directory.

Features

What is the difference between respawn, Ralph, and the orchestrator?

• Respawn restarts a session's CLI when it goes idle, to keep a long run going. It is the one most people want.
• Ralph loop is an autonomous single-session task loop with its own tracker.
• Orchestrator turns one goal into a phased plan and drives it across agents.

Keeping Agents Running and Autonomous Loops cover them properly.

Can agents start and supervise other agents?

Yes. Codeman ships an agent skill that lets an agent inside a session drive the HTTP API: list sessions, spawn workers, send prompts, and block until a worker's turn finishes. It is off by default and enabled per case.

See Driving Codeman From An Agent.

Can I run a case in a container?

Yes. One container per case, shared by all its sessions, non-root and capability-dropped by default, with your host CLI logins seeded in so nothing asks you to log in again. You can export a container plus its workspace and move it to another machine. See Docker Cases.

Can the agent run on a different machine?

Yes. Point a case at a remote host over SSH and the agent runs there, inside a durable remote tmux, so a dropped connection does not kill the run. See Remote SSH Sessions.

Can I put my Grafana or other dashboards in here?

Yes. Saved URLs render as tabs beside your sessions, proxied through Codeman's own origin so that mixed content and frame-blocking headers do not break them. See Web Tabs.

Why is a feature I read about not on screen?

Most of Codeman's UI is opt-in and defaults to off, so a stock install stays small. Check App Settings → Header & Panels. Settings Reference lists the defaults.

Contributing

How do I request a feature?

Open an Idea and it gets voted on. Roadmap decisions happen there.

How do I contribute code?

CONTRIBUTING.md has the full map. Small fixes can go straight to a PR; anything larger starts as an issue or Discussion so the design gets a nod first. Skins, translations, and docs are good first contributions.

How do I fix a mistake in this wiki?

These pages are generated from docs/wiki/ in the main repository. Editing a page in the browser gets overwritten on the next sync, so send a PR against that directory instead.