Agent Control (AI Agent Control Plane MVP)

Multi-server control plane for AI coding runtimes (Claude Code, Codex, Gemini CLI, OpenCode).

Layout

flowchart LR
    Browser["Browser UI"] --> CC["cc-control"]
    App["macOS/iOS App"] --> CC
    CC <--> A1["cc-agent"]
    CC <--> A2["cc-agent"]

cc-control/: control plane (REST + WS + audit + token management + optional prompt detection)
cc-agent/: per-server agent (WS outbound + PTY spawn/stream/input + chat worker)
cc-web/: static browser UI (xterm.js terminal + chat bubble UI)
app/AgentControlMac/: native macOS/iOS client

Quick Start

For production deployment (including TLS), use docs/deploy-public-server.md.

Start cc-control with an admin token.

cd cc-control
go run ./cmd/cc-control \
  -addr :18080 \
  -ui-dir ../cc-web \
  -admin-token admin-dev-token \
  -ui-token "" \
  -agent-token "" \
  -audit-path ./audit.jsonl \
  -offline-after-sec 30

Create tokens via web

Open http://127.0.0.1:18080/admin to manage tokens.

2.1 Create Tenant token (admin)

Fill admin token (for example admin-dev-token).
Set token type = tenant.
Leave tenant id empty to auto-create a new tenant.
Click Generate Token.
Save the generated token (tenant token) and tenant (tenant id).

2.2 Tenant generates UI + Agent tokens

In Tenant Tokens, paste the tenant token from 2.1.
Set ui role = owner (or viewer/operator as needed).
Optional: fill tenant id (must match the tenant token).
Click Generate UI + Agent.
Save the generated UI token and agent token.

2.3 Optional management

Click List Tokens to view issued tokens (supports tenant filter).
Click Revoke to revoke a token by token_id.

Create token via CLI.

3.1 Tenant token (admin)

# Admin: create tenant token
curl -X POST http://127.0.0.1:18080/admin/tokens \
  -H "Authorization: Bearer admin-dev-token" \
  -H "Content-Type: application/json" \
  -d '{"type":"tenant"}'

Example Tenant token response:

{
  "created_at_ms": 1770964695390,
  "role": "",
  "tenant_id": "<tenant-a-id>",
  "token": "<tenant-a-tenant-token>",
  "token_id": "<tenant-a-tenant-token-id>",
  "type": "tenant"
}

3.2 Tenant UI + Agent tokens

# Tenant: create UI + Agent tokens (owner role)
curl -X POST http://127.0.0.1:18080/tenant/tokens \
  -H "Authorization: Bearer <tenant-a-tenant-token>" \
  -H "Content-Type: application/json" \
  -d '{"role":"owner"}'

Example Tenant token response:

{
  "tenant_id": "<tenant-a-id>",
  "ui": {
    "token": "<tenant-a-ui-token>",
    "token_id": "<tenant-a-ui-token-id>",
    "role": "owner"
  },
  "agent": {
    "token": "<tenant-a-agent-token>",
    "token_id": "<tenant-a-agent-token-id>"
  }
}

ui.token: use this as the UI login token for Tenant.
agent.token: use this as -agent-token when starting Tenant A cc-agent.
Token is returned in plaintext only once; if leaked, revoke and re-issue immediately.

Start one cc-agent for Tenant A.

cd cc-agent
go run ./cmd/cc-agent \
  -control-url ws://127.0.0.1:18080/ws/agent \
  -agent-token <tenant-a-agent-token> \
  -server-id srv-local \
  -allow-root /path/to/repo \
  -claude-path /path/to/ai-cli

Example executable values for -claude-path:

/path/to/opencode
/path/to/codex
/path/to/gemini

Open browser UI:

http://127.0.0.1:18080

Open http://127.0.0.1:18080/admin (optional) to access the admin dashboard:

Overview tab: server/session/token/tenant counts at a glance.
Servers tab: cross-tenant server list with search and online/offline status.
Sessions tab: cross-tenant session list with search, status filter, and Stop button.
Tokens tab: create tenant tokens, list/revoke/export issued tokens.
Tenant page (/tenant): generate UI + Agent tokens with the tenant token.

Or login with the Tenant A UI token returned by /tenant/tokens (curl flow above).

Unified Session ID

系统现在只维护一套 session_id。该 ID 可用于：

作为 REST/WS 的会话主键；
作为 Claude CLI 的统一 conversation ID；
在同一路径（cwd）下重建 PTY/Chat 会话；
在 Web/App 界面里进行跨模式切换（复用同一 session_id）。

补充说明：

控制面会为同一个逻辑 session_id 维护按模式划分的运行实例槽位（instance_id）；Chat 和 PTY 各自最多保留一个实例槽位，不会随着反复切换无限追加。
PTY 启动时，若本机已存在 ~/.claude/session-env/<session_id>，agent 会自动优先使用 claude --resume <session_id> 接入已有 Claude conversation，而不是盲目再用 --session-id 创建。
若当前逻辑会话还没有真实的 Claude conversation（例如 PTY 创建后一句话都没说，就切到 Chat 再切回 PTY），系统会继续使用 --session-id，避免误用 --resume 触发 no conversation found。

创建会话时可选传入 session_id（UUID）。不传则由服务端自动生成；若已存在则返回冲突错误。

Token Model (Latest)

Recommended: use -admin-token to create a tenant token, then use POST /tenant/tokens to issue UI + Agent tokens.
Tenant token is only for /tenant/tokens, not for UI/WS.
UI token roles: viewer / operator / owner.
Legacy compatibility: -ui-token and -agent-token are still accepted and seeded into a default tenant.
Tokens are in-memory by default; restart clears them unless you reseed.
Use -token-db ./tokens.db (or TOKEN_DB) to persist tokens across restarts.

Deployment Modes

Direct HTTP (ws://): fast testing in trusted networks.
Nginx + TLS (Let's Encrypt): recommended for production with domain.
Nginx + self-signed TLS (wss://<ip>): no domain but encrypted transport.

Full guide: docs/deploy-public-server.md

Upgrade Note (Breaking Allowed)

If you migrate from legacy -ui-token/-agent-token to admin-token mode, switch cc-control to -admin-token first.
Then issue fresh UI/Agent tokens via POST /admin/tokens and restart agents with the new agent token.
During cutover, servers may appear empty until agents reconnect with new token.
For self-signed TLS, agent must add -tls-skip-verify.

Chat Mode Quick Start

除了传统的终端（PTY）模式，项目还支持 聊天室模式——类似微信一问一答的交互方式。后台守护一个 worker 子进程负责处理输入输出，前端以气泡 UI 展示对话。

1. 构建 echo worker（测试用）

cc-chat-echo 是一个最简的 chat worker，收到什么就原样加 [echo] 前缀返回，用来验证整条链路是否正常。

cd cc-agent
go build -o /tmp/cc-chat-echo ./cmd/cc-chat-echo

2. 启动 cc-agent 并指定 chat worker

在原有启动命令上加 -chat-worker 参数：

2.1 测试 Chat Worker（Echo）

go run ./cmd/cc-agent \
  -control-url ws://127.0.0.1:18080/ws/agent \
  -agent-token <your-agent-token> \
  -server-id srv-local \
  -allow-root /path/to/repo \
  -claude-path /path/to/ai-cli \
  -chat-worker /tmp/cc-chat-echo

2.2 测试 Claude Worker（无头模式）

go build -o /tmp/cc-chat-claude ./cmd/cc-chat-claude
go run ./cmd/cc-agent \
  -control-url ws://127.0.0.1:18080/ws/agent \
  -agent-token <your-agent-token> \
  -server-id srv-local \
  -allow-root /path/to/repo \
  -claude-path /path/to/ai-cli \
  -chat-worker /tmp/cc-chat-claude

注意：测试 Claude 时，Claude CLI 路径必须配置正确（例如 CC_CLAUDE_CMD=/path/to/claude 或确保 claude 在 PATH），否则 worker 无法启动。

示例（可选）：限制可用工具并指定模型

export CC_CLAUDE_CMD=/path/to/claude
export CC_CLAUDE_ALLOWED_TOOLS="Bash(git:*) Read Edit"
export CC_CLAUDE_MODEL=sonnet

3. 打开统一 Workspace

浏览器访问 http://127.0.0.1:18080/，输入 UI Token 后：

在左侧选择一个在线 Server。
如需直接进入 Chat 视图，可访问 http://127.0.0.1:18080/?view=chat。
填写 cwd（工作目录），点击 Create 创建会话。
如果当前视图是 Chat，可在右侧输入框输入消息，按 Enter 发送。
echo worker 会回复 [echo] 你的消息。

/chat 仍保留为兼容路径，但现在会自动跳转到统一 workspace 的 Chat 视图。

3.1 命令行主动推送提醒（通知到 Web/iOS/Windows）

当后台任务完成后，可以直接从命令行向 cc-control 发送通知：

curl -X POST http://127.0.0.1:18080/api/notifications \
  -H "Authorization: Bearer <your-ui-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Nightly Build",
    "message": "build + tests finished",
    "level": "success",
    "source": "ci"
  }'

如果你在自动化脚本里只持有 tenant token，可改用：

curl -X POST http://127.0.0.1:18080/tenant/notifications \
  -H "Authorization: Bearer <tenant-token>" \
  -H "Content-Type: application/json" \
  -d '{"message":"backup finished","level":"info","source":"cron"}'

说明：

通知会通过 WebSocket 主动推送到该 tenant 下的在线客户端。
控制面会缓存最近一批通知，客户端重连后会自动回放，降低断线漏提醒概率。
详细字段见 API 参考中 /api/notifications 与 /tenant/notifications。

4. 替换为真实 worker

echo worker 仅用于测试。正式使用时，将 -chat-worker 指向你自己的程序即可。worker 协议是 NDJSON：

stdin（每行一个 JSON）：{"message_id":"uuid","content":"用户消息"}
stdout（每行一个 JSON）：{"message_id":"uuid","content":"回复内容","meta":{"operations":["step 1","step 2"]}}
- meta 为可选字段，可回传中间步骤/工具调用摘要（Chat UI 会展示）。

只要你的程序遵循这个协议，就能无缝接入。

Current Capabilities

Server register + heartbeat online/offline
Session create/attach/resize/stop/delete
PTY streaming to UI/App and input roundtrip
Chat mode: request/response chat sessions with pluggable worker process
Optional prompt detection (-enable-prompt-detection, default off)
Approve/Reject action routing (y/n, Enter/Esc patterns)
JSONL audit log (cc-control/audit.jsonl)
Token issue/list/revoke admin API with tenant isolation
Admin dashboard with cross-tenant server/session monitoring

Security Baseline (MVP)

Agent-side cwd whitelist (-allow-root)
Runtime executable path control (-claude-path)
Env allowlist/prefix (-env-allow-keys, -env-allow-prefix)
Token-based tenant isolation with role checks
Basic per-token rate limiting in control plane

Docs

文档索引 — 入门 / 开发 / 部署 / 测试 / 合规
架构说明
API 参考
公网部署
快速上手 · 使用场景 · 隐私政策
测试：如何跑 E2E · Web E2E 设计

agent-control