`agensai install`

Pair the local CLI with a dashboard-provisioned orchestrator. Generate the orchestrator key on your device, store it at ~/.agensai/orchestrator.key (mode 0600), and auto-write MCP config for your IDEs.

Usage

npx @agensai/cli install <token>

The token is a one-time pairing token (32 bytes, 5-minute TTL, single-use) generated by the dashboard during orchestrator setup.

Flags

Flag	Default	Behavior
`--home <path>`	`~/.agensai`	Override the home directory.
`--dashboard-url <url>`	`https://app.agensai.xyz`	Override the dashboard endpoint. Useful for self-hosted dashboards.
`--skip-mcp-config`	`false`	Skip auto-writing IDE MCP config.
`--json`	`false`	Emit JSON result to stdout.
`--quiet`	`false`	Suppress progress text on stderr.

What it does

Pair. Sends { token, ephemeralPublicKey } to the dashboard's pairing endpoint. The dashboard validates the token and returns the metadata it provisioned for this orchestrator: ENS name, chain id, the smart-account address derived from your local key.
Generate the orchestrator key locally. A fresh ECDSA private key is generated in CLI memory. The dashboard never sees this key. Only the derived smart-account address goes back, used for the kill-switch grant + ENS records.
Store the key. Written to ~/.agensai/orchestrator.key with mode 0600. Plaintext, same pattern as ~/.jaw/keystore.json. The pointer orchestrator.json carries ENS + SA address + chain id.
Auto-config IDEs. Detects Claude Desktop, Cursor, and Claude Code on the host. Writes the appropriate MCP server config blocks. See MCP setup for what gets written.
Print result. ENS, SA address, chain id, paths.

Output

Default output:

Installed.
  Orchestrator   adrian-orc.agensai.eth
  Address        0x60009f89Ee82B174d26Cb2684F41A3556579fd5c
  Chain          Base (8453)
  Key            ~/.agensai/orchestrator.key (mode 0600)
  MCP            wrote configs for Claude Desktop, Cursor, Claude Code
 
Open your IDE and ask: "Show my agents."

JSON output (--json):

{
  "ens": "adrian-orc.agensai.eth",
  "mainEns": "adrian-main.agensai.eth",
  "saAddress": "0x60009f89Ee82B174d26Cb2684F41A3556579fd5c",
  "chainId": 8453,
  "keyPath": "/Users/you/.agensai/orchestrator.key",
  "mcpConfigured": ["claude-desktop", "cursor", "claude-code"]
}

Exit codes

Code	Meaning
`0`	Success.
`1`	Generic failure: bad token, network error, dashboard rejection. Stderr explains.
`3`	Existing install detected at `--home`. Run `agensai disconnect --purge` first.

Re-installing

If you re-run install against a home directory that already has an orchestrator pointer, the CLI refuses (exit code 3). To replace an existing install:

agensai disconnect --purge
agensai install <fresh-token>

The fresh token must come from a fresh dashboard ceremony; expired/used tokens are rejected.

Security

The orchestrator key is born on your device and never transits the dashboard. Only the SA address goes back.
The pairing token is single-use and short-lived (5 minutes). Replays are rejected.
The key is stored in plaintext mode 0600, same threat profile as JAW CLI's ~/.jaw/keystore.json. Protected by file-system permissions; readable by processes running as your user. See Security for the threat model.