Super Agent CEO

What is super-agent-ceo?

super-agent-ceo is a CLI that turns any machine — a laptop, a server, a CI runner — into a node your organization's AI agents can drive remotely. Once connected, your agents can execute tasks on the node through a secure NATS messaging channel, scoped to your organization. The /super-agent console in the dashboard gives you a live view of all connected nodes, their status, active runs, and controls.

Installation

Install with a single command:

curl -sSL https://install.agent.ceo/super-agent-ceo | sh

Or run via Docker:

docker run --rm -it ghcr.io/genbrainai/super-agent-ceo:latest \
  login --api-key ace_YOUR_KEY_HERE

After installation, verify it works:

super-agent-ceo --version

Login

Authenticate with your organization-scoped API key:

super-agent-ceo login --api-key ace_YOUR_KEY_HERE

API keys starting with ace_ are available from the Settings → API Keys page in your agent.ceo dashboard. Each key is scoped to a single organization — a member of org A cannot access org B's nodes.

Logging in to your Claude subscription

The org API key above authenticates the node. It says nothing about how the node's inference is billed. To bill prompts to your Claude subscription instead of metered ANTHROPIC_API_KEY rates (roughly 10x), log the node's claude CLI in separately:

super-agent-ceo login claude

This runs claude setup-token, which prints an authorization URL, waits for you to authorize in a browser, and accepts the code you paste back.

Where the credential lands is platform-specific, and this trips people up when they go looking for it:

• Linux — ~/.claude/.credentials.json (the command tightens it to 0600).
• macOS — the login keychain. The credentials file never appears there, so its absence is not evidence of a failed login.

super-agent-ceo login claude reports which store it actually found rather than assuming.

Logging in is not sufficient on its own. ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN outrank a logged-in subscription inside the claude CLI, and they are stripped from operand runs only by connect --subscription (see Driving a node from your own terminal below). Without that flag a stale key in your shell silently wins — including a zero-balance one, which fails every prompt with Credit balance is too low while login itself reported success. So the pair is:

super-agent-ceo login claude          # authorize the subscription
super-agent-ceo connect --subscription  # the flag is what actually bills it

Headless and backend nodes

connect --subscription can drive the subscription login for you, but only when a TTY is available. On a server, in a container, or in CI there is no TTY: it warns and does nothing, leaving the node running with no subscription credential. Authorize such a node one of two ways:

• Run super-agent-ceo login claude once interactively on that host, before starting the service; or
• Set CLAUDE_CODE_OAUTH_TOKEN in the node's environment — the token claude setup-token prints is a first-class subscription credential, and a node authenticated purely that way is correctly recognised as logged in.

Connect

Register your machine as a node in your organization:

super-agent-ceo connect --name my-laptop

• --name — a human-readable label shown in the console (e.g., build-box, my-laptop)
• --agent-id — optional. Pins a specific sa_* agent id; by default one is minted fresh for you. It must start with sa_ — the platform reserves other prefixes and the CLI will refuse anything else.
• --mode — local for a laptop (the default) or backend for a server
• --role — role label shown in the dashboard (default super-agent)

The node appears in the /super-agent console within seconds. By default, nodes are locked down: filesystem access is sandboxed, bash is disabled, and operator prompts are refused. Opt in explicitly with flags at connect time.

Driving a node from your own terminal

To watch a node work and answer its prompts inline, connect with --terminal:

super-agent-ceo connect --name my-mac --terminal --subscription

--terminal reflects the operand's interactive I/O to the terminal running connect. You see output live and answer inline prompts — /login, permission requests — directly. Without it, a turn produces nothing observable until it returns over NATS, so a node that is working looks dead. Prompt text is passed to the runner as a positional argument, never through a shell, so it cannot inject.

--subscription bills inference to your Claude subscription instead of metered API credentials. It drives a subscription login when none is found and a TTY is available, then strips both environment credential channels the claude CLI honours — ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN — from operand runs, because either one outranks a logged-in subscription and stripping only one would let the other win.

Two things worth knowing before you rely on it:

• A deliberately configured credential still outranks it. --subscription clears env-leaked credentials, not an intentional on-disk one. An apiKeyHelper or a key in settings.json will beat the subscription — remove those from the node's config if you want the subscription to win. connect warns at startup when it detects an apiKeyHelper or a non-default ANTHROPIC_BASE_URL, so a precedence surprise surfaces then rather than in your bill.
• In a headless context with no credentials it warns and does nothing, leaving the env vars in place rather than breaking inference.

The startup banner prints the auth it resolved, and says plainly when you are logged in but not on a subscription — that is the difference between billing your plan and billing metered credits, which otherwise surfaces much later as a per-prompt Credit balance is too low that reads like a node fault.

Commands reference

Connect flags

Troubleshooting

Connection refused

If super-agent-ceo connect fails with "connection refused":

1. Check that your machine can reach wss://nats.agent.ceo on port 443
2. Verify your API key is valid and not expired: super-agent-ceo login --api-key ace_...
3. Check if a firewall or proxy is blocking outbound WebSocket connections
4. Confirm what the stored key actually is with super-agent-ceo key show — it reports the org, scopes and bound node without bringing the node online

Certificate errors

TLS certificate errors typically mean:

1. Your system clock is out of sync — run ntpdate pool.ntp.org or equivalent
2. A corporate proxy is intercepting TLS — add your proxy's CA certificate to the system trust store
3. You're running an outdated OS with expired root certificates — update your CA bundle (apt update && apt install -y ca-certificates on Debian/Ubuntu)

Every prompt fails with "Credit balance is too low"

This usually means the node is billing metered API credentials rather than your Claude subscription — and it can happen on a node that logged in successfully, because a login is not what selects the billing channel:

1. Confirm the node is actually authorized: super-agent-ceo login claude. On macOS the credential lives in the login keychain, so a missing ~/.claude/.credentials.json does not mean you are logged out.
2. Reconnect with super-agent-ceo connect --subscription. Without this flag, ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN in the node's environment outrank the subscription — a stale or zero-balance key beats a brand-new login.
3. Check the startup banner. It prints the auth it resolved and says plainly when you are logged in but not on a subscription.
4. If it still loses, look for a deliberately configured credential --subscription does not clear: an apiKeyHelper or a key in the node's settings.json. connect warns at startup when it sees an apiKeyHelper or a non-default ANTHROPIC_BASE_URL.

Node shows as offline in the console

If a node was connected but shows offline (grey) in the dashboard:

1. The CLI process may have exited — check if super-agent-ceo is still running
2. Network interruptions cause the node to go stale after 90 seconds of no heartbeat
3. Restart with super-agent-ceo connect --name <name> to reconnect