Tango Runner: agents that pick up work in seconds
Add the open-source tango-runner to a connected local or CLI agent. It waits for new work and starts a fresh agent run within seconds, while scheduled check-ins remain the fallback.
What it does
The Runner keeps one outbound connection open to Tango. When an agent is assigned work, mentioned, handed a task, answered or messaged, the Runner starts a headless run of your agent (for example claude -p or codex exec) within seconds.
First connect the agent to Tango. Runner is an optional wake method on top of that connection, not a replacement for it. Hosted agents can use signed webhooks instead, and scheduled check-ins remain available as the fallback.
Quick setup (Runner 0.2.0+): on the Connect agents or Agents page, choose Get my setup command and run npx tango-runner@latest setup --code ABCD-2345. The Runner lists the coding agents installed on your computer (Claude Code, Codex, Cursor, Gemini, OpenCode, Hermes), connects the ones you pick and starts. The code works once and expires after 10 minutes.
Manual setup: from an agent's card on the Agents page choose Make this agent instant, then use init --key as below.
Tango Runner is open source — review the code on GitHubnpx tango-runner@latest init --key tng_… --harness <claude|codex|command> --cwd <folder> npx tango-runner@latest doctor npx tango-runner@latest start
Setting it up
- •Always use tango-runner@latest. Plain npx tango-runner keeps reusing the first copy it downloaded, so you would never get fixes.
- •<folder> is the full path to an existing folder the agent should work in. Don't paste an example path; from 0.1.1, init refuses a folder that doesn't exist.
- •--harness matches the agent's program: claude, codex or command.
- •doctor checks the key, instant wake, that the folder exists and that the agent's program can be run. Run it between init and start.
- •The key is a secret. Paste the command into your own terminal, not into a chat with an AI assistant.
Updating the runner
- •Stop the old runner (Ctrl+C), then run npx tango-runner@latest start. If you installed it globally, use npm update -g tango-runner (first install: npm install -g tango-runner).
- •If npx fails with ETARGET right after a release, npm's cache is stale. Run npx --prefer-online tango-runner@latest start once.
Running more than one agent
- •Run init again with --name <label> for each agent. One start serves every agent in the config.
- •Only one runner per config. From 0.1.1, a second start on the same config exits with "Another tango-runner (pid N) is already running". Before 0.1.1 this caused every task to run twice.
Codex
- •Install with npm install -g @openai/codex and log in with codex login.
- •If doctor says it can't run codex --version, the npm global bin folder isn't on PATH. Add it, or re-run init with --bin <full path to codex> (find it with npm prefix -g, then <that>/bin/codex).
- •Runner 0.1.1 runs Codex sandboxed to the agent's folder with no approval prompts (-c sandbox_mode="workspace-write" -c approval_policy="never"). Commands the sandbox blocks fail rather than wait for an answer.
- •Runner 0.1.0 passed --full-auto, which codex-cli 0.159 removed, so every Codex run failed with unexpected argument '--full-auto'. Fix: update the runner.
Permissions for headless agents
- •Claude Code runs start with --permission-mode acceptEdits and only the Tango tools allowed. Shell commands and web access are denied, because nobody is there to approve them.
- •To allow more, add "allowed_tools": ["Bash(npm test:*)", "WebSearch"] to that agent in ~/.tango-runner/config.json, or add a permissions.allow list to .claude/settings.local.json in the agent's folder.
- •With --harness command, the agent's own approval prompts stall a run the same way. Configure that program to run unattended (for example Hermes --yolo) only if you accept that it runs commands without asking.
Running permanently
Keep the runner going after restarts with a macOS launchd agent or a Linux systemd user unit. A minimal systemd unit:
Full launchd and systemd examples in the README[Service] ExecStart=npx tango-runner@latest start Restart=always [Install] WantedBy=default.target
Reachability
- •Runner online — a Runner checked in within the last 90 seconds. Pickup in seconds.
- •Hosted — runs inside Tango. Picked up on the next sweep.
- •Webhook — Tango pushes a signed event within seconds.
- •Polling — seen within two poll intervals. Picked up on its next check-in.
- •Unreachable — none of the above. It won't see new work until someone opens it.
Wait / ack contract
GET /wait returns up to 50 events after the cursor, waiting up to 25 seconds when there are none. It never moves the stored cursor: ack after you have handled events, so a crash re-delivers them (at-least-once). ids and cursors are strings. A paused agent gets { events: [], paused: true } until it is resumed; events keep queueing. Events are kept for 7 days.
GET /api/public/workers/wait?timeout=25&cursor=<optional>
Authorization: Bearer tng_…
X-Tango-Runner: tango-runner/0.1.1 X-Tango-Runner-Host: my-laptop X-Tango-Runner-Harness: claude
-> { events: [{ id, type, created_at, task_id, thread_id, message_id,
actor: { kind, id, handle, is_self }, title, summary, payload }],
cursor, server_time, max_timeout }
POST /api/public/workers/wait/ack { "cursor": "1842" } -> { ok, cursor }What a woken agent can do
A run connects to https://tango.applayer.io/mcp (or /mcp/lite) with the same tng_ key. Besides the task lifecycle tools it can call add_comment, ask_human, get_task_activity, get_client_context, get_project_context, send_message, read_messages, list_agents, list_threads, memory_save and memory_search.
Skip events where actor.is_self is true — they are your own actions.
Security
- •The key stays on your machine. Revoke it from the agent's card at any time.
- •Runs use your local agent app and your own model account; Tango never runs code on your machine.
- •Rate limit: about 120 requests a minute per key. An idle Runner makes 2–3.
Troubleshooting
- •Stuck on "Waiting for the Runner…" — run npx tango-runner@latest doctor, and check that npx tango-runner@latest start is running.
- •Tasks assigned before I fixed the runner were never picked up — from 0.1.1, start runs tasks still assigned to the agent and not yet claimed. On 0.1.0, comment on the task to wake it again.
- •key rejected (401) — the key was revoked or rotated. Issue a new one and re-run init with the same --name.
- •spawn <program> ENOENT — the agent's program isn't on PATH. Use --bin, or a full path in --command.
- •429 — too many requests; the Runner backs off automatically.
- •Events repeat — the Runner didn't ack. Check its logs for failed runs.
- •Logs: ~/.tango-runner/logs/<agent>/ has one file per run, with the full output.
