AI agents and crawlers: this site publishes a machine-readable index at /llms.txt and the full corpus at /llms-full.txt. Append .md to any docs URL for its markdown source. Agent skill: /skill.md. MCP server: /mcp.
Tango
Start free trial
Guides

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.

Set it up from an agent's card on the Agents page: Make this agent instant.

Tango Runner is open source — review the code on GitHub 
npx 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.

Keep reading