Skip to content

agentd.md

Latest commit

 

History

History
114 lines (82 loc) · 3.17 KB

agentd.md

File metadata and controls

114 lines (82 loc) · 3.17 KB

agentd

agentd runs on each host. It discovers tmux panes, captures snapshots, streams terminal output, and executes commands sent from the control plane.

Install

cd agents/agentd
go build -o agentd ./cmd/agentd
sudo cp agentd /usr/local/bin/

Configure

Copy and edit the example config:

sudo mkdir -p /etc/agentd
sudo cp agents/agentd/config.example.yaml /etc/agentd/config.yaml

Required fields

  • host.id - UUID for the host.
  • host.name - a friendly name displayed in the UI.
  • control_plane.ws_url - WebSocket endpoint (example: wss://agentcommander.example/v1/agent/connect).
  • control_plane.token - host token created by the control plane.

tmux integration

  • tmux.bin - path to tmux.
  • tmux.socket - optional tmux socket if you use tmux -L.
  • tmux.poll_interval_ms - session discovery interval.
  • tmux.snapshot_lines - how many lines to capture for snapshots.
  • tmux.option_session_id - tmux option for stable session IDs.

When tmux metadata includes a session name, agentd can auto group sessions in the UI.

Spawn settings

  • spawn.tmux_session_name - default tmux session for spawned panes.
  • spawn.default_shell - shell used for new panes.
  • spawn.worktrees_root - optional worktree root for multi session templates.

Security flags

  • security.allow_send_input
  • security.allow_kill
  • security.allow_spawn
  • security.allow_console_stream

Disable these if you want read only mode on a host.

Providers

agentd can handle provider specific hooks and usage parsing. See Provider Hooks for setup details.

Metrics

agentd exposes Prometheus metrics at GET /metrics on the same HTTP listener as provider hooks (providers.claude.hooks_http_listen).

  • Default: http://127.0.0.1:7777/metrics
  • If you bind hooks to a non-loopback address, treat /metrics as sensitive (firewall or reverse proxy auth).

Provider usage polling

agentd can run periodic commands to pull usage data from provider CLIs or APIs and report it to the control plane.

Example: OpenCode (Minimax) usage polling

  1. Install the helper script and make it executable:
sudo cp scripts/opencode-usage.sh /usr/local/bin/opencode-usage
sudo chmod +x /usr/local/bin/opencode-usage
  1. Store the API key outside git (systemd environment is recommended):
sudo systemctl edit agentd
# add:
# [Service]
# Environment="MINIMAX_API_KEY=YOUR_KEY_HERE"
  1. Configure agentd:
providers:
  opencode:
    usage_command: "/usr/local/bin/opencode-usage"
    usage_interval_ms: 300000
    usage_parse_json: true

Keep MINIMAX_API_KEY out of version control. The script reads it from the environment at runtime.

Storage

  • storage.state_dir - local state + outbound queue.
  • storage.outbound_queue_max - max queued messages before backpressure.

Run (systemd)

sudo cp deploy/systemd/agentd.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now agentd

Troubleshooting

  • No sessions: verify tmux access with the same user running agentd.
  • Custom tmux socket: set tmux.socket correctly.
  • Permissions: ensure storage.state_dir is writable by the service user.