@sleep2agi/agent-network

Agent Network (anet)

Run a local network of AI agents from one CLI.

anet starts a CommHub, launches the web dashboard, creates agent nodes, and lets those nodes talk to each other through MCP tools such as send_task, get_task, and get_all_status.

What It Is

Agent Network is a local-first multi-agent runtime:

• CommHub: MCP + REST + SSE hub for task routing, auth, networks, and status.
• Agent nodes: long-running AI workers backed by Claude Code, Claude Agent SDK, Codex SDK, or Grok Build ACP.
• Dashboard: browser UI for topology, chat, tasks, node health, and server telemetry.
• CLI: anet, the single entry point for setup, auth, node lifecycle, and demos.

The default path runs entirely on your machine. LAN sharing is opt-in.

Requirements

• Node.js >= 22.13.0
• npm >= 10
• Bun >= 1.2.0 (anet hub start lazy-runs the Bun-based CommHub server)
• macOS or Linux

Install Bun if needed:

curl -fsSL https://bun.sh/install | bash

Install

Stable:

npm install -g @sleep2agi/agent-network
anet -v

Preview channel:

npm install -g @sleep2agi/agent-network@preview
anet -v

Npm dist-tags move independently. Query the registry instead of relying on a version table embedded in this source tree:

npm view @sleep2agi/agent-network dist-tags --json
npm view @sleep2agi/agent-node dist-tags --json
npm view @sleep2agi/commhub-server dist-tags --json

The Grok co-presence text below describes candidate source only until a reviewed package is explicitly published to preview.

5-Minute Quick Start

Open three terminals.

1. Start CommHub

anet hub start

Default local URL:

http://127.0.0.1:9200

By default the hub binds to localhost. Use --host 0.0.0.0 only when you intentionally want LAN clients to connect.

2. Start Dashboard

anet hub dashboard

Open:

http://localhost:3000

3. Log In, Create A Node, Start It

anet login --username admin --password anethub
anet node create my-bot
anet node start my-bot

anet node create walks you through:

• Runtime: claude-code-cli, claude-agent-sdk, codex-sdk, codex-app-server, grok-build-acp, the experimental preview-only grok-build-cli, or preview opencode-cli.
• Provider preset: runtime-specific options, including Anthropic/OpenAI API-key presets for opencode-cli (other Anthropic-compatible providers remain available through claude-agent-sdk).
• API key and model settings.

When the node starts successfully, look for:

SSE connected

Then use the Dashboard chat panel to send my-bot a message.

Multi-Agent Collaboration

Create a second node:

anet node create reviewer
anet node start reviewer

Ask my-bot:

Ask reviewer to review this plan and summarize the risks.

The first agent can discover peers with get_all_status, delegate work with send_task, poll with get_task, and integrate the reply. The dashboard Tasks and Messages views show the chain.

LAN Hub

On the hub machine:

anet hub start --host 0.0.0.0

On another machine:

npm install -g @sleep2agi/agent-network
anet init --hub http://<HUB-LAN-IP>:9200
anet login --username admin --password anethub
anet node create remote-bot
anet node start remote-bot

Do not expose the hub directly to the public internet without a reverse proxy, HTTPS, firewall rules, and reviewed auth settings.

Runtimes

Runtime	Use When	Notes
claude-code-cli	You want Claude Code CLI sessions and channel support	Uses Claude Code process; supports stable COMMHUB_RESUME_ID in recent previews
claude-agent-sdk	You want Anthropic-compatible API providers	Good default for provider presets
codex-sdk	You want Codex-backed nodes	Useful as a backup runtime when Claude quota is constrained
codex-app-server	You want a Codex TUI/app-server bridge	Preview bridge with a bound Codex thread
grok-build-acp	You want Grok Build through grok agent stdio	Requires Grok Build CLI auth; stable for receive/reply, session persistence, and explicit send_task delegation
grok-build-cli	You want one human-visible, text-only Grok TUI shared with trusted network tasks	Experimental preview only. Fixed [todo_write] tool profile; Linux and an exact Grok CLI build are required; approval ownership is not fully hardened
opencode-cli	You want OpenCode ACP with an Anthropic/OpenAI API preset or a keyless OpenCode model	Preview only. Requires exact opencode-ai@1.18.1 and the paired preview packages; safe mode is text-only and uses fresh private runtime roots

OpenCode ACP — Preview

Install the exact release pair and vetted OpenCode pin, then create a node:

npm install -g @sleep2agi/agent-network@preview @sleep2agi/agent-node@preview opencode-ai@1.18.1
anet node create opencode-demo --runtime opencode-cli
anet node start opencode-demo

All three are deliberate global prerequisites for this preview. The OpenCode launch path does not auto-run npx from a project-controlled PATH. It accepts only canonical npm package entrypoints with exact metadata and rejects an otherwise convincing same-version package inside the current project or an enclosing monorepo workspace.

The wizard supports Anthropic and OpenAI API-key presets. If the selected key is not exported, use the printed anet opencode auth-login command; OpenAI is forced to the upstream Manually enter API Key method. By default OpenCode runs only on Linux in an external random 0700 launch-scoped root whose workspace and fresh private HOME/XDG roots are removed together after exit. Local code tools and unattended question are disabled. Only explicit flags.opencodeUnsafeTools=true restores the project cwd for trusted tasks.

The default trusted base is /run/user/$uid. On a non-systemd host, pre-create an owner-only directory and set its absolute path in ANET_OPENCODE_SAFE_BASE; the base and every ancestor must not be group/other writable. The whole preview runtime (safe and unsafe) hard-fails when the base cannot be verified or the host is not Linux. Unsafe still uses the external writable root; it changes only cwd and local-tool policy. For exact 1.18.1, every workspace ancestor is scanned for opencode.jsonc, opencode.json, .opencode, AGENTS.md, CLAUDE.md, CONTEXT.md, .claude, .agents, and .git, then its identity and candidates are checked again after the version probe immediately before ACP spawn. OPENCODE_PURE and OPENCODE_DISABLE_PROJECT_CONFIG remain defense in depth, not the isolation boundary. Local OpenCode conversation history is not promised across process crashes; use Docker/VM when an OS security boundary is needed.

Grok Build ACP

grok-build-acp uses the local Grok Build CLI via Agent Client Protocol (ACP). Install and authenticate Grok first:

curl -fsSL https://x.ai/cli/install.sh | bash
grok

Create and start a node:

anet node create grok-demo --runtime grok-build-acp
anet node start grok-demo

Look for:

runtime: grok-build-acp
SSE connected

Stable support:

• Receive CommHub tasks through SSE.
• Run one Grok Build ACP turn per task.
• Persist grokSession into .anet/nodes/<name>/config.json.
• Resume the saved Grok session on the next task.
• Reply to the original sender through CommHub.
• Explicit delegation such as 给 A站助手 发任务: ... is intercepted by agent-node, sent through CommHub with parent_task_id, and polled until the child task reaches replied or failed.

Current boundary:

• Grok native MCP tool injection is not the stable path yet.
• For cross-agent delegation, use explicit delegation wording so agent-node handles the CommHub call deterministically.
• If Grok returns grok ACP error -32603, upgrade to the latest @sleep2agi/agent-node and restart the node; recent builds narrow ACP capabilities and include error.data diagnostics.

Details: docs/grok-build-runtime.md.

Grok Co-Presence TUI — Experimental Preview

Dangerous experimental feature: network tasks drive the same Grok TUI and share its conversation context. Approval ownership is not fully hardened. Use only with trusted tasks on a trusted network. This runtime is not supported for production and is not part of the latest release channel.

The co-presence candidate is currently pinned to Linux with procfs mounted at /proc (including /proc/self/fd) and the exact Grok CLI build reported as grok 0.2.93 (f00f96316d) (the stable installer may append [stable]). Install that build and log in as the same operating-system user that will run anet:

grok login
grok --version

Create the shared-TUI node and start its bridge in the first terminal:

anet node create grok-shared --runtime grok-build-cli
anet node start grok-shared

Attach an interactive terminal to the same TUI from a second terminal on the same machine and user account:

anet grok attach grok-shared

Press Ctrl-] to detach. While attached, a CommHub task sent to grok-shared is submitted to this same TUI, rendered in the visible session, and its completed answer is routed back to the originating task. This shared-session behavior is the reason untrusted tasks must not be connected.

This preview selects a runtime-owned TUI agent profile whose exact model-tool inventory is [todo_write]. Filesystem, shell, network, media, MCP, scheduler, and subagent tools are unavailable; custom tools/maxTurns are unsupported in co-presence. It is a text-only co-presence preview, not a coding profile.

The pinned 0.2.93 TUI resolves its session-local todo_write helper without human input. During an active network turn the preview admits only that exact no-request-ID lifecycle with decision=allow, at most once per turn; every other tool, identity, decision, overlap, mode transition, or unresolved completion remains closed. This deliberately narrow preview exception is not production approval-owner enforcement and is another reason to connect trusted tasks only.

anet node start capability-checks a compatible global agent-node if one exists. It requires the machine-readable ANET_CAPABILITY_GROK_COPRESENCE_V2 marker, so an older headless-only or V1 co-presence binary cannot shadow the fixed-profile preview. A global install is not required: when it is absent or incompatible, anet uses npx -y @sleep2agi/agent-node@preview to fetch and resolve the preview package, verifies its metadata/capability, then launches the resolved agent-node entrypoint directly. Direct launch lets anet node stop signal the real runtime instead of an installer wrapper. The fallback therefore needs npm registry access or an already populated npm cache on first start.

The preview E2E covers the CommHub inbox path. grok-build-cli currently refuses Feishu channels because that forked worker does not yet share the credential-isolated log boundary; run Feishu on a separate non-Grok node.

For the older process-per-turn Grok CLI lane, opt out of co-presence explicitly:

anet node create grok-turn --runtime grok-build-cli --grok-headless
anet node start grok-turn

anet grok attach intentionally refuses a headless node. The separate ACP runtime remains available as:

anet node create grok-acp --runtime grok-build-acp
anet node start grok-acp

grok-build-acp uses grok agent stdio; it is not the same execution path as grok-build-cli --grok-headless.

This preview does not claim completion of the formal native Leader/Policy Gateway runtime. Its Phase 0 protocol freeze, Phase 1A implementation gate, production-grade approval ownership, and latest release gate remain locked. See the Grok co-presence preview guide for the exact boundary.

Provider Presets

anet node create writes the correct provider environment into .anet/nodes/<name>/config.json.

Provider	Status	Notes
Anthropic	verified path	Native Anthropic Messages API
MiniMax	verified path	Anthropic-compatible endpoint
DeepSeek	verified path	Anthropic-compatible endpoint
GLM / Zhipu	verified path	Anthropic-compatible endpoint
Kimi / Moonshot	verified path	Anthropic-compatible endpoint
OpenRouter	available	Anthropic-compatible routing
Custom	available	Provide base URL, model, and token

Common Commands

# Hub and dashboard
anet hub start
anet hub dashboard

# Auth
anet register
anet login --username <user> --password <password>
anet logout
anet whoami
anet passwd

# Nodes
anet node create <name>
anet node start <name>
anet node start --all
anet node stop <name>
anet node resume <name>
anet node rename <old> <new> --force
anet node delete <name>
anet node ls
anet info <name>
anet logs <name>

# Grok co-presence (experimental preview; trusted tasks only)
anet node create grok-shared --runtime grok-build-cli
anet node start grok-shared
anet grok attach grok-shared

# Network status and repair
anet status
anet tasks [status]
anet doctor
anet doctor --fix

# Project and session helpers
anet init --hub <url>
anet init project
anet project up
anet project restart
anet project down
anet session ls

# Channels and upgrades
anet channel add telegram <name> --bot-token <tok> --allow <uid>
anet channel add feishu   <name> --app-id <id> --app-secret <secret> --allow <open-id>   # see docs/feishu-quickstart.md
anet channel ls
anet upgrade
anet upgrade --channel preview --dry-run

# Batch / demos
anet create --batch
anet batch list
anet batch stop <prefix>
anet demo sci-team

Configuration Files

~/.anet/config.json
  Global CLI profile: hub URL, user token, default network.

~/.anet/server/admin-utok.json
  Local bootstrap admin token for the hub.

{project}/.anet/nodes/<name>/config.json
  Per-node runtime, model, provider env, node token, channels, and session IDs.

Example node config:

{
  "node_id": "n_a1b2c3d4",
  "node_name": "my-bot",
  "alias": "my-bot",
  "hub": "http://127.0.0.1:9200",
  "network_id": "default",
  "token": "ntok_...",
  "runtime": "claude-agent-sdk",
  "model": "your-model",
  "channels": ["server:commhub"],
  "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"],
  "env": {
    "ANTHROPIC_BASE_URL": "https://example.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-..."
  },
  "flags": {
    "dangerouslySkipPermissions": true,
    "teammateMode": "in-process",
    "maxTurns": 50
  }
}

Do not commit .anet/ or provider API keys.

Security Notes

• The hub binds to 127.0.0.1 by default.
• LAN mode is explicit: anet hub start --host 0.0.0.0.
• Node tokens are network-scoped ntok_ tokens; user tokens are utok_.
• Keep API keys in local node config or env refs; never paste real keys into issues or docs.
• Treat tmux / terminal streaming features as local-admin tools.

What Is Stable vs Experimental

Stable day-to-day path:

• anet hub start / anet hub stop / anet hub status (v0.10.11+: SIGTERM → 3s grace → SIGKILL stop; status shows PID + port + /health version — no more manual lsof+kill)
• anet hub dashboard
• anet login
• anet node create/start/stop/delete/rename
• anet node start --all
• anet project up/restart/down
• Dashboard chat, task list, topology, and status views

Actively evolving:

• IM platform integration (Feishu / Slack / WhatsApp / WeCom)
• Telegram channel binding
• Advanced dashboard topology edges
• Batch orchestration and science-team demos
• Codex runtime expansion
• Grok Build ACP runtime
• Cross-version rename hot-reload

Documentation

• Docs site: https://anet.sh
• Getting started: https://anet.sh/guide/getting-started
• Preview guide: https://anet.sh/guide/preview/getting-started
• Issues: https://github.com/sleep2agi/agent-network/issues

Repository Layout

This package lives in the agent-network/ subdirectory of the monorepo:

agent-network/
  bin/cli.ts           anet CLI
  src/client.ts        SDK client
  src/node-server.ts   CommHub MCP server bridge used by claude-code-cli
  src/im/              IM integration contracts and future adapters

Related packages live next to it:

server/                @sleep2agi/commhub-server
agent-node/            @sleep2agi/agent-node
docs-site/             anet.sh documentation site

License

Apache-2.0