Agent-first issue tracking for autonomous agent workflows, with human-readable monitoring.

No local Python, pip, or uv required.

• Black-box agent operator path: stoner launch <provider> ...
• Custom runtime / low-level integration path: stoner session ...
• Mutation guard primitive: stoner guarded ...

If you are not integrating a custom runtime, start with launch.

1. Clone and configure:

git clone [email protected]:gang-thumb/stoner.git
cd stoner
cp deploy/.env.example deploy/.env

2. Set STONER_AUTH_SECRET and STONER_BOOTSTRAP_TOKEN in deploy/.env.

3. Start:

docker compose -f deploy/compose.yaml up -d --build

4. Open UI:

• http://127.0.0.1:3000/ui

5. Mint a human token without entering the container:

export STONER_BOOTSTRAP_TOKEN="<bootstrap-token-from-deploy-env>"
export STONER_BASE_URL="http://127.0.0.1:3000"

stoner auth mint-human

6. If you want a stored agent token for wrappers/launchers:

export STONER_BOOTSTRAP_TOKEN="<bootstrap-token-from-deploy-env>"
export STONER_BASE_URL="http://127.0.0.1:3000"

stoner auth bootstrap \
  --agent-id codex

mint-human returns a human JWT for UI/API use. bootstrap mints a short-lived human token internally, then mints and stores the agent token in the OS keychain.

If you already have a human token and only want the agent token step:

export STONER_HUMAN_TOKEN="<human-jwt>"

stoner auth mint-agent \
  --agent-id codex

Check what the stored token is authorized as:

stoner auth whoami \
  --agent-id codex

For local development, the shortest working path is:

export STONER_BOOTSTRAP_TOKEN="<bootstrap-token-from-deploy-env>"
./scripts/launch-codex.sh --title "Fix login failure" --objective "Restore authentication flow"

If no stored codex agent token exists, launch bootstraps it automatically and then continues.

If launch cannot resolve credentials, the error should tell you:

• what token sources were checked
• what was missing
• the exact next bootstrap command to run

If you want prebuilt image deployment:

echo "<GHCR_TOKEN>" | docker login ghcr.io -u "<github-user>" --password-stdin
cp deploy/.env.example deploy/.env
docker compose -f deploy/compose.ghcr.yaml up -d

Image publish automation:

• .github/workflows/publish-server-image.yml

Run sidecar as containerized plugin command:

export STONER_AGENT_TOKEN="<agent-jwt>"
export STONER_BASE_URL="http://127.0.0.1:3000"
./scripts/stoner-sidecar-docker.sh

Openclaw should keep this process alive and stream JSONL events to stdin.

If the agent runtime is shell-driven and does not want to manage JSONL framing, use the simpler command mode:

export STONER_AGENT_TOKEN="<agent-jwt>"
export STONER_AGENT_ID="nanobot"
export STONER_RUN_ID="run-20260308-001"
export STONER_BASE_URL="http://127.0.0.1:3000"

stoner session start --title "Deploy gate automation" --objective "Coordinate rollout"
stoner session next --profile compact
stoner session note --summary "Selected mitigation path" --why "highest confidence"
stoner session finish --outcome DONE --reason "completed"

stoner session start persists the active runtime state to .stoner/runtime_session.json, so the later commands can run without repeating the connection flags. It also defaults to non-auto-begin behavior, so the first session next usually gives an actionable EXECUTE_TASK. Use --auto-begin if you want immediate execution instead.

If you want one unified entrypoint for external agents, use launch:

stoner launch codex \
  --title "Fix login failure" \
  --objective "Restore authentication flow" \
  -- codex exec

For resumed work:

stoner launch claude --resume -- claude

If you omit the child command, launch uses a provider default:

• codex -> codex
• claude -> claude

launch prepares the tracked session, fetches resume_memory plus the next snapshot, writes a launch context file, passes the effective STONER_* env vars to the child process, and records one automatic exit note after the child returns.

Important:

• child process exit is not the same thing as task completion
• fallback launch behavior records an exit note only
• task finish/fail happens only when a structured launch result explicitly requests it
• launched children receive a short-lived STONER_GUARD_TOKEN for mutation checks instead of inheriting broad auth env tokens

If the child writes a JSON result packet to STONER_LAUNCH_RESULT_PATH, launch will use that packet instead of the fallback auto-note and map it into:

• record_turn
• structural write-back for follow-up task / derived issue
• optional handoff
• optional request_approval
• optional finish / fail

Reference helper:

• scripts/write-launch-result.sh

Result contract:

• docs/LAUNCH_RESULT_CONTRACT.md

When launched through stoner launch, child processes also receive:

• STONER_AGENT_ID
• STONER_RUN_ID
• STONER_ISSUE_ID
• STONER_TASK_ID
• STONER_THREAD_ID
• STONER_GUARD_TOKEN

Launch strips these from the child environment:

• STONER_BOOTSTRAP_TOKEN
• STONER_HUMAN_TOKEN
• inherited STONER_AGENT_TOKEN

launch now prepends a generated git shim to the child PATH, so mutating git subcommands are routed through the ingress mutation gate.

The launch JSON output now separates:

• child_process: what happened to the spawned process
• task_outcome: what Stoner actually recorded as task state or note behavior

For direct use outside launch:

stoner guarded \
  --operation git:commit \
  --issue-id iss_123 \
  -- /usr/bin/git commit -m "fix auth"

Guarded execution details:

• docs/GUARDED_EXECUTION.md

If the runtime is Python-based and already has a turn loop, use stoner.runtime_loop.run_tracked_agent_loop(...) to enforce the same start -> prepare -> record_turn -> finish/fail boundaries in code. The same helper also supports resumed runs with resume=True, so handoff targets and restarted workers can reattach without creating duplicate work.

Ingress auto-ticket + mutation gate (no runtime patching required in agent prompt):

stoner ingress process \
  --message "stoner 로그인 에러 고쳐줘" \
  --conversation-id conv-1 \
  --message-id msg-1 \
  --channel openclaw \
  --policy-mode SUGGEST \
  --token "$STONER_AGENT_TOKEN" \
  --base-url http://127.0.0.1:3000

• Agent runtime quickstart: docs/AGENT_RUNTIME_QUICKSTART.md
• Reference agent walkthrough: docs/REFERENCE_AGENT_WALKTHROUGH.md
• Shell handoff example: examples/reference_shell_handoff.sh
• Launch wrapper guide: docs/LAUNCH_WRAPPERS.md
• Launch result contract: docs/LAUNCH_RESULT_CONTRACT.md
• Guarded execution: docs/GUARDED_EXECUTION.md
• User deployment: docs/DEPLOYMENT_USER.md
• Openclaw install: docs/OPENCLAW_INSTALL.md
• Openclaw ingress runbook: docs/OPENCLAW_INGRESS_RUNBOOK.md
• Ingress policy: docs/INGRESS_POLICY.md
• Developer setup: docs/DEVELOPER_SETUP.md
• Architecture + diagrams: docs/ARCHITECTURE.md
• API spec: docs/API_SPEC.md
• Agent adapter contract: docs/AGENT_ADAPTER_SPEC.md
• Sidecar protocol: docs/SIDECAR_CLI.md

• Preferred command: stoner
• Compatibility alias: stoner-agent-sidecar

• Python: examples/reference_python_agent.py
• Shell: examples/reference_shell_agent.sh