@agentteams/runner

A background runner that polls and executes AI agent tasks from the AgentTeams platform.

Prerequisites

• Node.js 18 or later
• AgentTeams API server running
• A daemon token issued from the web UI (x-daemon-token)

Installation

npm install -g @agentteams/runner

Verify the installation:

agentrunner --help

Short alias (agr)

agentrunner is also installed as agr. The canonical name keeps working — the alias is an addition, not a replacement.

agr --help    # same as: agentrunner --help

• The alias symlink is created at install time. If you installed an earlier version, rerun npm install -g @agentteams/runner to get it.
• Use the alias only when you type commands yourself. Autostart entries, scripts, and agent guides should keep using agentrunner, which exists in every environment.
• Usage text echoes the alias only where npm installs bins as symlinks (POSIX). Windows .cmd/.ps1 shims and pnpm global installs are shell wrappers, so agr --help still prints Usage: agentrunner ... there. Running the alias itself works everywhere.

Quick Start

1. Initialize

agentrunner init --token <DAEMON_TOKEN>

The init command:

1. Saves the token to ~/.agentteams/daemon.json
2. Validates the token against the API server
3. Registers an OS-level autostart service and starts the runner immediately
   • macOS: ~/Library/LaunchAgents/run.agentteams.runner.plist (launchd)
   • Linux: ~/.config/systemd/user/agentrunner.service (systemd)
   • Windows: Task Scheduler task AgentRunner (current-user logon trigger)

Options

• --token <token> — Required. Daemon token issued from the web UI
• --no-autostart — Optional. Skip autostart registration (manual start only)

Examples:

# Standard setup (with autostart)
agentrunner init --token daemon_xxxxx

# Token-only setup (no autostart)
agentrunner init --token daemon_xxxxx --no-autostart

2. Start (start)

agentrunner start

Running without a subcommand defaults to start:

agentrunner

If autostart was registered via init, you do not need to run start manually. The OS will start the runner automatically on login/boot.

3. Check Status (status)

agentrunner status

Shows whether the runner process is active and whether autostart is registered.

Example output:

[...] INFO Daemon is running { pid: 12345 }
[...] INFO Autostart is enabled { platform: 'launchd' }

4. Stop (stop)

agentrunner stop

Sends SIGTERM to the running process for a graceful shutdown. On Windows, it ends the current AgentRunner scheduled-task instance first so the failure policy does not restart an intentionally stopped runner. The task remains registered and can start again at the next logon.

On macOS and Linux, the registered OS supervisor may restart the runner automatically. Use uninstall to stop completely.

5. Restart (restart)

agentrunner restart

Restarts the runner using the current environment:

• If autostart is registered, AgentRunner restarts through the registered OS service.
• On Windows, restart ends the existing AgentRunner task instance before running it again.
• If autostart is not registered, AgentRunner starts a new detached background process.

6. Update (update)

agentrunner update

Updates the globally installed @agentteams/runner package to the latest npm version and then restarts the runner.

7. Uninstall (uninstall)

agentrunner uninstall

Performs the following:

1. Removes or disables the autostart supervisor so it cannot respawn the runner
2. Stops the running process
3. Cleans up the PID file

Configuration

Settings are resolved in the following priority order at runtime.

Token

1. AGENTTEAMS_DAEMON_TOKEN environment variable
2. daemonToken in ~/.agentteams/daemon.json

Environment Variables

| Variable | Default | Description | | ---------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | POLLING_INTERVAL_MS | 30000 (30s) | Polling interval for pending triggers | | IDLE_TIMEOUT_MS | 1800000 (30min) | Primary timeout. Priority: task Idle Timeout label on the trigger > valid configured IDLE_TIMEOUT_MS > runner-specific default > global 30-minute default | | TIMEOUT_MS | 86400000 (24h) | Fail-safe timeout. Stops a runner only if it stays alive for the full wall-clock limit | | RUNNER_CMD | opencode | Command used to execute agent tasks | | CODEX_SANDBOX_LEVEL | workspace-write | Codex runner sandbox level. Allowed values: workspace-write, off | | LOG_LEVEL | info | Log level: debug, info, warn, error | | DAEMON_VERBOSE_RUNNER_LOGS | true | When false, reduces runner stdout/stderr to start/stop/error only | | DAEMON_PROMPT_LOG_MODE | preview | Prompt logging: off, length, preview, full |

AgentRunner defaults to an idle-timeout-first policy. In normal operation, the resolved idle timeout ends stalled runs, while TIMEOUT_MS remains a 24-hour fail-safe for runaway processes.

If you set CODEX_SANDBOX_LEVEL=off, AgentRunner launches Codex with --dangerously-bypass-approvals-and-sandbox. Use this only when you explicitly want full git write access and accept the reduced safety boundary.

How It Works

After start, the runner operates in the following loop:

1. Polls for pending triggers periodically
2. Claims a trigger
3. Fetches runtime info (working directory, API key)
4. Executes RUNNER_CMD run "<prompt>"
5. Updates trigger status based on exit code, idle timeout, or the 24-hour fail-safe timeout

If a process is already running for the same agentConfigId, new triggers are REJECTED.

Logs

• Runner logs: console output (forwarded to OS log system when autostarted)
  • macOS: /tmp/agentrunner.log, /tmp/agentrunner-error.log
  • Linux: journalctl --user -u agentrunner -f
  • Windows: %USERPROFILE%\.agentteams\agentrunner.log
• Task logs: <workdir>/.agentteams/daemonLog/daemon-<triggerId>.log

Windows recovery checks

Windows Task Scheduler uses a signed or explicitly unsigned native GUI launcher instead of starting powershell.exe directly. The launcher is integrity-checked and installed under %USERPROFILE%\.agentteams\bin\agentrunner-launcher-<version>-<sha12>.exe. Legacy tasks migrate during restart — both agentrunner restart and a restart requested from the web UI (the path agentrunner update takes) re-register the task whenever the live definition still points at a console-bound action. The runner also checks the definition during startup and repairs it without restarting the current process. That startup repair takes effect the next time the runner starts. Use agentrunner status to see whether a legacy action is still pending, or run agentrunner restart to migrate and apply the native launcher immediately. The migration never deletes the previous registration first; a failed migration restores the prior task XML from an exported backup.

Windows x64 and Windows 11 ARM64 (through x64 emulation) are supported. Windows 10 ARM64 is not supported and fails closed instead of falling back to a visible PowerShell process. Because the scheduled task points at the content-addressed user copy, a running Runner does not lock the executable inside the npm package during a global update.

The AgentRunner scheduled task ignores duplicate starts and retries failed exits up to three times at one-minute intervals. Inspect it and follow the append-only daemon log with:

schtasks /Query /TN "AgentRunner" /V /FO LIST
Get-Content "$env:USERPROFILE\.agentteams\agentrunner.log" -Wait

For a release smoke test on a disposable Windows test machine:

1. Run agentrunner restart, query schtasks /Query /TN "AgentRunner" /XML, and verify the action points at agentrunner-launcher-*.exe, the task gets one new runner PID, and no console window appears.
2. End the runner process unexpectedly and verify Task Scheduler starts it again after the configured delay.
3. Disconnect and reconnect the network, or suspend and resume Windows. API requests that remain stalled are aborted after 30 seconds and retried; verify a later poll attempt or successful poll appears in the log.
4. Run agentrunner status, then agentrunner stop. Verify the current task instance stops and does not immediately respawn.
5. Run agentrunner uninstall only when cleanup is intended, and verify schtasks /Query /TN "AgentRunner" reports that the task no longer exists.

Troubleshooting

Missing token. Usage: ... init --token <token> ...

The --token flag was not provided to init. The usage line names whichever executable you ran, so it reads agentrunner init ... or agr init ....

Daemon token is missing. Run 'agentrunner init --token <token>' first.

No token found at runtime. Run init first or set the AGENTTEAMS_DAEMON_TOKEN environment variable.

License

Apache-2.0