agents

What it is

agents is two Go binaries. agentsd runs on a server that has the coding CLIs installed: it starts each agent in a tmux session and exposes an HTTP API plus a WebSocket that carries a full terminal. agentsctl runs on your laptop: a session picker TUI, a CLI, and a raw-terminal client for that WebSocket.

  laptop                          server
 ┌─────────────┐    WebSocket    ┌──────────────────────────┐
 │ agentsctl   │ ──────────────► │ agentsd                  │
 │  · tui      │    + REST API   │  · tmux sessions         │
 │  · session  │                 │  · claude/grok/codex/…   │
 │  · status   │                 │  · full PTY bridge       │
 └─────────────┘                 └──────────────────────────┘

Why a real TTY

Interactive agent CLIs want a real terminal: subscription sign-in, the full UI, key handling. Their headless print modes (-p) behave differently and can bill against API credits. agents keeps the agent interactive on the server and streams the terminal to you. A print-job queue exists, but it is opt-in and labelled as such.

How a session works

1. POST /v1/sessions with an agent and a working directory.
2. The directory is resolved under workspace_root and checked against an allowlist — .. is rejected and symlinks are resolved before matching.
3. agentsd runs tmux new-session -d -s la-<id> -c <dir> -- <agent>. An optional first prompt is typed in with tmux send-keys, not passed as a CLI flag.
4. agentsctl session open connects to /v1/sessions/{id}/pty. The server opens a PTY running tmux attach; binary frames carry terminal I/O and JSON text frames carry resizes and keepalive pings.
5. Detaching ends only the attach process. The agent keeps running until you kill the session, and the client reconnects automatically after a drop.

SSH remains an optional fallback (session open --ssh).

Quick start

# server: tmux + the CLIs you want
echo "AGENTSD_TOKEN=$(openssl rand -hex 32)" > ~/.config/agentsd/env
agentsd serve --config ~/.config/agentsd/config.toml

# laptop
agentsctl config init      # set url + token
agentsctl                  # TUI session picker
agentsctl session start -a claude --open

Optional: headed Chromium for Playwright through Xvfb, so agents can drive a visible browser on the server.

Security and status

The token is effectively remote interactive access to the agent tools on that host — treat it like a shell. The defaults and docs push toward 127.0.0.1 plus a tunnel (Tailscale, Cloudflare Tunnel with Access) rather than a public port, and every /v1/* route, including the PTY WebSocket, requires the bearer token.

It is an early public preview (v0.2.x), suited to a personal or small-team agent box. It is not multi-tenant: multi-user isolation, identity beyond a shared token, session recording and Homebrew packaging are on the roadmap, not shipped.

Stack

Go, tmux, WebSocket, Bubble Tea. Licensed under the GNU AGPL v3.