QuoxCLIQuoxCLIAgentsTerminal

Driving an agent from the Quox CLI

Adam Cowles2026-10-11T09:00:00.000Z4 min read

A dark control-plane grid where a single cyan command line feeds a violet agent node, which splits into one path that returns and one that stops at a glowing amber approval gate, over near-black

An agent that can act is only safe if you can see what it did and stop it before it does. From the terminal, both of those are the same two commands.

This is the second piece in a short series on things you can actually do from the Quox command line. Last time we connected a mailbox. This time we drive an agent: attach to one, run one of its tools, and watch the governed path it runs through.

The scenario is a real one. You want the X agent to queue a post for your account, but you want every post seen by a human before it goes out, and you want a record of who ran what. That is three different concerns (acting, approving, accounting) and the CLI treats them as one short session.

Attach: borrow the agent's identity

Driving an agent starts by attaching to it. Attaching leases the agent's identity to your session for a window, so the tools you run are run as that agent, under its permissions, and recorded under its name. It is a badge you put on, not a second process you start. The lease is short by design and heartbeats itself until your session ends.

Attach to the agent

# attach this session to the X agent (its display name is HERALD)
$ quox agent attach xtwitter
attached as xtwitter  (lease active, ttl 900s)
lease keeper started: heartbeats every 5m until this session exits
# confirm which identity you are now acting as
$ quox agent attach-status xtwitter
agent_id   xtwitter
lease      active (expires in 14m 51s)

The lease is 15 minutes by default (--ttl changes it). You are not impersonating anyone: the attach is itself recorded, and detach hands the identity back.

Exec: run a tool, and watch it get witnessed

With the agent attached, exec runs one of its tools by name. The input is a JSON string, the same shape the agent would pass itself. Two things are worth watching here. A tool that only reads returns its result straight away. A tool that acts does not.

Run a read, then an action

# a read tool returns straight away (and is still witnessed)
$ quox agent exec xtwitter --tool twitter_verify_credentials --input '{}'
{ "ok": true, "screen_name": "Quox_AI", "verified": false }
# a tool that ACTS does not just happen: it files an approval
$ quox agent exec xtwitter --tool x_post --input '{"text":"We shipped the thing. Write-up on the blog."}'
status: awaiting_approval
inbox_item_id: 01M4P7Q2ZK   (approve it in your inbox; nothing posts until you do)

twitter_verify_credentials is a read, so it answers immediately. x_post acts, so it stops as an approval card and returns awaiting_approval. The tool never posts on its own.

That awaiting_approval is the whole point, not a limitation. The post is held as a card in your approval inbox with the exact text attached. Until you approve it, nothing reaches X. When you do approve it, the post goes out and the approval is recorded alongside the attempt. The same is true of sending an email, placing a call, or any other tool that changes the world outside Quox: the convenient command and the governed one are the same command, and the human stays in the loop without having to leave the terminal to get there.

The witnessing is not a log you have to trust. Every exec, and every approval, is wrapped in an evidence envelope on the AEE and WARD trail, so the account of what this agent did is something you can check rather than take on faith.

Keeping the lease, then letting go

The lease heartbeats itself while your session is alive, but a long run that sits idle through a build or a wait can outlast it. attach-heartbeat refreshes it on demand. When you are finished, detach releases the lease and removes the local attach kit, so the identity is not left borrowed.

Heartbeat, then detach

# refresh the lease before a long job that might outlast it
$ quox agent attach-heartbeat xtwitter
lease refreshed (expires in 15m)
# hand the identity back when you are done
$ quox agent detach xtwitter
detached from xtwitter; lease released

The shape of it

Four commands, one short session: attach to borrow the identity, exec to run a tool, approve the one action that leaves the building, detach to hand the badge back. You got the convenience of driving an agent straight from your shell, and you did not give up the approval or the audit trail to get it. That trade is the one most agent tooling asks you to make, and the point of doing it this way is that you do not have to make it.

The CLI reference lists the full quox command surface, including the rest of the quox agent group, and the agent roster shows which agents you can attach to and what each one is for. Next in the series we will drive a different corner of it. For now, that is one real thing you can do from the Quox command line, start to finish, without leaving the terminal.