acc-agent-bootstrap

name	acc-agent-bootstrap
description	Verify and install the ACC agent runtime plus upstream Hermes on an ACC node. Use when onboarding a new agent, confirming `hermes_cli` is operational, or diagnosing why an agent isn't executing tasks.
version	1.2.0
platforms	["linux","macos"]
metadata	{"hermes":{"tags":["acc","hermes","bootstrap","install","artifacts"],"category":"infrastructure"}}

ACC Agent Bootstrap

Why PATH detection is unreliable over SSH

Non-interactive SSH sessions do not source ~/.bashrc or ~/.profile. command -v acc-agent can return nothing even when the runtime is installed, because ~/.acc/bin is only added to PATH in interactive shells.

Never rely on which alone over SSH. Check the canonical path first:

ssh -o StrictHostKeyChecking=no USER@HOST \
  'test -x ~/.acc/bin/acc-agent && test -x ~/.acc/bin/hermes'

---

Step 1 — Check if acc-agent is already installed

# Reliable: search known locations
ssh -o StrictHostKeyChecking=no USER@HOST \
  'find ~/.acc/bin /usr/local/bin ~/.cargo/bin -name acc-agent -type f 2>/dev/null'

# Also check the workspace source
ssh -o StrictHostKeyChecking=no USER@HOST \
  'test -d ~/.acc/workspace && cd ~/.acc/workspace && git rev-parse --short HEAD'

If found, verify the upstream Hermes CLI:

ssh -o StrictHostKeyChecking=no USER@HOST 'hermes -z "hello"'

For interactive host debugging:

ssh -t USER@HOST 'hermes'

---

Step 2 — Install or refresh acc-agent

The native runtime is built from the ACC workspace and installed to ~/.acc/bin/acc-agent:

ssh -o StrictHostKeyChecking=no USER@HOST \
  'cd ~/.acc/workspace && git fetch origin && git reset --hard origin/main && bash deploy/restart-agent.sh'

This is also the preferred repair path for stale Slack gateways because it kills old gateway processes and restarts upstream hermes gateway run --replace.

If the host setup touches Tailscale, disable Tailscale DNS before tailscale up:

tailscale set --accept-dns=false
tailscale up --accept-dns=false

For Boris specifically, do not use the Bullwinkle 100.100.100.100 systemd-resolved override. If Slack DNS fails on Boris, repair it with:

ssh -o StrictHostKeyChecking=no USER@BORIS \
  'cd ~/.acc/workspace && bash deploy/fix-dns-boris.sh'

---

Step 3 — Verify gateway and worker modes

Gateway:

ssh -o StrictHostKeyChecking=no USER@HOST \
  'pgrep -af "hermes .*gateway run|hermes_cli.main .*gateway" || true'

Fleet-wide read-only health check:

bash deploy/slack-gateway-health.sh

Worker:

ssh -o StrictHostKeyChecking=no USER@HOST \
  'pgrep -af "acc-agent (bus|tasks|supervise)" || true'

---

Step 4 — Verify ANTHROPIC_BASE_URL

Hermes routes LLM calls through Tokenhub, not the public Anthropic API. The agent's .env must have ANTHROPIC_BASE_URL pointing to the local proxy:

ssh -o StrictHostKeyChecking=no USER@HOST \
  'grep ANTHROPIC_BASE_URL ~/.acc/.env 2>/dev/null || grep ANTHROPIC_BASE_URL ~/.ccc/.env 2>/dev/null || echo "NOT SET"'

Expected: ANTHROPIC_BASE_URL=http://localhost:9099 (or the Tokenhub address). If missing, add it to ~/.acc/.env.

---

Step 5 — Verify upstream Hermes

Check that the upstream CLI is installed:

ssh -o StrictHostKeyChecking=no USER@HOST '~/.acc/bin/hermes --help >/dev/null && echo hermes-ok'

If missing, run ACC_DIR=~/.acc bash ~/.acc/workspace/deploy/setup-hermes-venv.sh.

---

Step 6 — Verify task workspaces and artifact API

Agents no longer mount a shared project filesystem. Source work happens in isolated git workspaces under ~/.acc/task-workspaces, and non-source artifacts move through the ACC blob/object API.

ssh -o StrictHostKeyChecking=no USER@HOST '
  test -d ~/.acc/task-workspaces && echo "task workspaces OK"
  source ~/.acc/.env 2>/dev/null || source ~/.ccc/.env 2>/dev/null
  curl -sf -H "Authorization: Bearer $ACC_AGENT_TOKEN" "${ACC_URL}/api/resources" \
    | grep -q artifact_store && echo "artifact API advertised"
'

---

Step 7 — Run a smoke test

ssh -o StrictHostKeyChecking=no USER@HOST '
  source ~/.acc/.env 2>/dev/null || source ~/.ccc/.env 2>/dev/null
  export PATH="$HOME/.acc/bin:$HOME/.local/bin:$PATH"
  hermes --version && echo "hermes OK"
'

---

Quick reference: per-agent known paths

Agent	Init	runtime path	Workspace root
rocky	systemd (system)	~/.acc/bin/acc-agent	~/.acc/task-workspaces
natasha	systemd (user)	~/.acc/bin/acc-agent	~/.acc/task-workspaces
bullwinkle	launchd (macOS)	~/.acc/bin/acc-agent	~/.acc/task-workspaces
ollama	systemd (system)	~/.acc/bin/acc-agent	~/.acc/task-workspaces
boris	supervisord (K8s)	~/.acc/bin/acc-agent	~/.acc/task-workspaces

Always verify against the live agent — these can drift.

Common mistakes

• which acc-agent over SSH returns nothing: Non-interactive SSH doesn't load ~/.bashrc. Use ~/.acc/bin/acc-agent directly.
• Legacy gateway command is running: Run bash ~/.acc/workspace/deploy/restart-agent.sh to replace it with hermes -p <profile> gateway run --replace.
• ANTHROPIC_BASE_URL not set: Hermes calls will go to the public Anthropic API (wrong billing, wrong routing). Always set this to the local Tokenhub proxy.
• Task workspace missing: Re-run bash ~/.acc/workspace/deploy/setup-node.sh or create ~/.acc/task-workspaces; agents will clone per-task repos there.

---

Artifact API

Use the blob/object API for non-source artifacts such as screenshots, media, logs, and generated outputs. Source code should stay in git workspaces.

source ~/.acc/.env 2>/dev/null

# Upload a text artifact
curl -sf -X POST \
  -H "Authorization: Bearer $ACC_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mime_type":"text/plain","data_base64":"aGVsbG8="}' \
  "${ACC_URL}/api/bus/blobs/upload"

# List artifacts
curl -sf -H "Authorization: Bearer $ACC_AGENT_TOKEN" \
  "${ACC_URL}/api/bus/blobs"