`agensai serve`

Start the daemon. Loads the orchestrator key, claims a single-active-device lockfile, and runs an MCP server over stdio for your IDE.

agensai mcp is an alias.

Usage

agensai serve
# or
agensai mcp

You usually don't run this manually. Your IDE invokes it via the MCP config that install wrote.

Flags

Flag	Default	Behavior
`--home <path>`	`~/.agensai`	Override the home directory.
`--rpc-port <n>`	(none)	Bind a local TCP RPC layer on the given port, in addition to stdio. Useful for non-MCP clients.
`--no-rpc`	(default)	Stdio only, no TCP.
`--quiet`	`false`	Suppress startup banner on stderr.

Single active device

ERC-4337 nonces are per-account. Two daemons holding the same orchestrator key would collide on UserOps. To prevent this, serve claims a lockfile at ~/.agensai/serve.lock containing { hostname, pid, startedAt, cliVersion }.

If a second daemon tries to start while a first is running, it exits with code 8 and a message naming the active host + pid.

To switch active device, stop the current daemon (agensai disconnect) before starting another.

agensai status surfaces the active device's hostname so you can see at a glance which device is currently authoritative.

What the MCP server exposes

9 tools. Reads (no signing): list_agents, get_agent, read_contract, resolve. Writes: create_agent, transfer, execute, revoke, policy_add. See MCP tools for the full surface.

The IDE communicates over stdio. Tool inputs are validated by Zod schemas before any signing happens.

Logs

serve writes structured progress lines to stderr:

agensai serve starting
  orchestrator   adrian-orc.agensai.eth
  SA address     0x60009f89Ee82B174d26Cb2684F41A3556579fd5c
  chain          8453
  lockfile       /Users/you/.agensai/serve.lock
  CLI version    0.2.0
ready.

Run with --quiet to suppress everything except errors.

Shutdown

The daemon traps SIGINT, SIGTERM, and uncaughtException. On shutdown:

The lockfile is released.
In-flight signing operations finish if possible.
The process exits.

If the daemon crashes without releasing the lockfile, the next serve invocation detects a stale lock (pid not alive on the same host) and reclaims it. See agensai status to verify.

Exit codes

Code	Meaning
`0`	Clean shutdown.
`1`	No orchestrator installed. Run `agensai install <token>` first.
`2`	Orchestrator pointer exists but the keychain has no key. Re-run `install`.
`8`	Lockfile is held by another live daemon. Stop it first.