Agent Chat
fuzzball agent is a conversation with the Fuzzball agent in your terminal. You
ask it something, it answers, and the exchange is kept on the cluster as a
session rather than in your shell’s scrollback — so you can leave, come
back, and pick the same conversation up, here or in the web interface.
$ fuzzball agentThat starts a new session and names it for you, from the date and time.
resume picks up a session you already have, by name or by id:
$ fuzzball agent resume debuggingA name that matches nothing is an error rather than a new session, so a typo cannot start an empty conversation that looks like the one you meant. To give a session a name you choose, start it and rename it:
$ fuzzball agent
$ fuzzball agent list
ID | NAME | MODEL | PERMISSIONS | UPDATED
7f3c1a90-2d64-4c18-9e55-2a1b3c4d5e6f | chat 2026-09-15 14:02:11.482 | gpt-4o | read-only | 2026-09-15 02:02:11PM
$ fuzzball agent rename 7f3c1a90-2d64-4c18-9e55-2a1b3c4d5e6f debuggingThe generated name carries milliseconds, so it is not worth typing — list the session and rename it by id, which is accepted anywhere a name is.
Sessions are private to you: nobody else can list or read yours, not even with the id.
Type to talk to the agent. Lines beginning with / are commands to the CLI
rather than messages to the agent:
| Command | What it does |
|---|---|
/session | This session’s settings and token usage |
/tools | The tools the agent may use right now |
/model NAME | Answer with a different model, from the next turn |
/allow TIER | Grant a permission: write, exec or destructive |
/revoke TIER | Remove a permission: write, exec or destructive |
/context KIND/ID | Send a workflow, node or volume with your next message |
/export | Print the transcript, including tool results |
/clear | Clear the screen |
/quit | Leave; the session stays on the cluster |
/help prints the same list. /exit is accepted as well as /quit. Anything
else starting with / is refused rather than sent to the agent.
Input is read a line at a time, so you can pipe a script of messages and
commands into fuzzball agent; the session ends when the input does. A line
over 1 MiB is not sent: the CLI says so and reads on, rather than send part of
it.
Each turn ends with the tokens it used and, when the cluster reports it, the
session’s running total. On an interactive terminal, the bottom row also shows
the session, its model, its permissions and its running total; piped input or
output gets no status line, and neither does Windows or a terminal whose TERM
is dumb, such as an Emacs shell buffer.
The figures are the cluster’s, shown as it sends them. The totals are the
session’s, so they include turns from before you opened it and from other
clients, such as the web interface; the bottom row picks those up when your
next turn finishes or a command re-reads the session. /session shows the
total with its prompt and completion counts and the number of finished turns,
and fuzzball agent show prints the raw counters. A failed or interrupted
turn is not counted as a turn, but its tokens are added to the total – after a
disconnect, a few seconds after it ends.
“(incomplete)” means the cluster could not confirm some turn’s exact usage, so the figures beside it may be short. The totals read “not reported” until the cluster sends some: on a session with nothing counted yet, and always on a cluster older than v4.5.0, which keeps no session totals.
The agent’s reply is printed with terminal control characters shown rather than acted on, so an answer cannot clear your screen, move the cursor, or rewrite a question you are part-way through answering. A model that emits ANSI colour codes will have them shown as text instead of coloured.
/clearclears your screen, not the conversation. The transcript is append-only and shared with the web interface, so there is no in-session way to make the agent forget something. To be rid of a conversation, delete the session.
The agent reaches Fuzzball through tools, and tools are grouped into four
tiers. A session starts at read only: the agent can look things up, and
cannot change anything.
| Tier | Examples |
|---|---|
read | Read the docs, list workflows, describe a node |
write | Create or update something without running compute |
exec | Run cluster compute |
destructive | Cancel or delete something |
Grant tiers at launch, or part-way through:
$ fuzzball agent --allow-write --allow-exec$ fuzzball agent resume debugging
> /allow exec
> /revoke write- A tier that is not granted is not offered. The agent is not told those
tools exist.
/toolsshows what it can actually reach. destructivealways asks, andyis not enough. Granting the tier lets the agent propose a destructive call; every one still stops and waits for you to typeyesor the tool’s name./allowand/revokechange one permission and nothing else. A session can be open in the browser and in another terminal at once. Each command re-reads the session, says so if the permission is already as you asked, and otherwise tells the cluster to change only the tier you named, so a permission granted or revoked from the other client in the meantime is left as it is; if the permissions come back changed in some other way, the CLI shows them and warns, and leaves them. The--allow-*flags onresumework the same way and only ever add.- Granting a tier does not turn on auto-approval.
/revokealso turns off auto-approval for that tier, and if a session holds an auto-approval for a tier it has not been granted,/allowand--allow-*clear it first, so calls in the tier you just allowed still ask.
A cluster older than your CLI cannot change a single permission, and would read
the request as a replacement for all of them. Against such a cluster, /allow,
/revoke and --allow-* on resume refuse rather than send it; start a new
session with the --allow-* flags you want, or upgrade the cluster.
One limit remains during an upgrade to 4.5: while replicas on both versions are
running, a change can reach an older one, which applies it as a replacement of
every permission – so a /revoke write, for example, can leave write granted
and auto-approved. After every /allow, /revoke and --allow-*, the CLI
compares the permissions it gets back with what the change should have left,
and if they differ it shows them and warns that another client changed them
meanwhile or an older replica applied a replacement. A /revoke that leaves the
tier it named granted or auto-approved is an error, said loudly. The CLI does
not change the permissions again on its own.
The --model, --allow-* and --context flags are read from the command line
only. Like other flags they would otherwise be read from FUZZBALL_*
environment variables, and a variable set once would grant a permission, send a
resource, or choose the model a conversation goes to, in every session started
or resumed after it.
When a call needs approval, the CLI shows you the whole thing – the Fuzzfile, the command, the target – not a summary, and waits. Refusing ends that call, and the agent is told so, so it can suggest something else. If the call is decided without you – answered in the web interface or another terminal – the prompt is withdrawn and the rest of the reply follows. An approval does not time out: the call waits until someone answers it or the turn ends. If the turn ends first – the cluster restarting, say – the CLI says so and withdraws the prompt, and the call does not run. If the cluster says an answer you typed is no longer pending, the CLI says so and withdraws the prompt. If an answer may not have reached the cluster at all, a terminal is asked again and a script’s answer is sent again, a bounded number of times.
A write or exec call is answered y or n. A destructive call is
approved only by typing yes or the tool’s name, in any case; the prompt says
which, y does not approve it, and n refuses it.
On a terminal, an answer counts only if you type it after its prompt appears –
at least half a second after – so a second y, or one typed while the agent
was still working, cannot approve a call you have not seen; the CLI says it
ignored it and asks again. The half second starts again from any line that does
not answer, so a y inside a pasted block of text does not count. A line typed
at a prompt that is not an answer is not sent to the agent, and the CLI says so.
On Linux and macOS, anything typed but not yet entered when a prompt appears is
discarded, so a y begun for an earlier prompt cannot be finished as an answer
to this one; on Windows the half second is the guard. ctrl-D at a prompt is a
no. Input piped in from a script answers prompts in order; a line that is not an
answer is taken as no, and is kept as the script’s next message. A script must
answer a destructive call with yes or the tool’s name: a y is taken as no,
so a script that pipes y to approve destructive calls has to change. After a
prompt is withdrawn, the answers meant for it – y, yes, n, no, or the
withdrawn call’s tool name – are not sent to the agent if they come within
three seconds of the withdrawal, until the first other line. One typed later
than that is a reply to the agent, and is sent.
At the next call’s prompt they are skipped if they were sent before it appeared
(piped) or typed as it appeared.
Some tools return text written outside Fuzzball’s control plane, which can carry instructions aimed at the agent. Their output is always untrusted:
- job logs and their digests, object contents, and the output of a command run in a container
- waiting on a workflow (
workflow_wait), which returns its error and the tails of its job logs - catalog entries
- the records of persistent endpoints, and a workflow’s endpoints, which carry their workflows’ annotations
- a workflow’s description, events and scheduling explanation
(
workflow_describe,workflow_events,workflow_why), which quote its jobs’ commands, its specification, and names, paths and errors from its definition or a catalog entry
A few other tools are trusted unless a result carries such text: listing workflows (a workflow’s error), listing or showing volumes (a volume’s description), creating or updating an endpoint (its annotations), listing or showing nodes (a hold’s reason, a device plugin’s error), and a failed catalog start or object upload. A tool the cluster has not classified counts as untrusted too.
Reading untrusted output taints the turn: from then on, every write, exec
and destructive call in that turn asks for your approval, even in a tier the
session auto-approves. Taint lasts for one turn; the next message starts clean.
fuzzball agent list-tools and /tools mark the tools whose output may be
untrusted, so you can see which reads may taint a turn.
--context sends a workflow, node or volume to the agent with your first
message, so you can ask about it without describing it:
$ fuzzball agent --context workflow/7f3c1a90-2d64-4c18-9e55-2a1b3c4d5e6f
> why did this fail?/context does the same part-way through, for the next message. The forms are
workflow/ID, node/ID (the node id fuzzball node list shows), volume/ID
and volume/PROVISIONER/NAME. A volume ID can be written in any common UUID
form – with or without hyphens, in braces, or as urn:uuid: – and is sent in
the hyphenated form. Repeat --context for more than one; a message carries at
most four.
The CLI fetches the resource from the cluster the session is on, with the credentials it connected with – switching context in another terminal does not change that. It sends only values that cannot carry words: the ids the cluster assigns, statuses, counts, sizes, booleans and times. A long list, such as a large node’s cores, is sent as its length. For a workflow, that is its status, its timestamps, its owner’s id, and each stage’s id, kind, status and timestamps. Every text field is left out – names, error messages, descriptions, stage details and the workflow’s specification – because anyone who can create the resource writes them, and they would arrive as part of your own message, which is never tainted (see Untrusted content). The agent reads them with its own tools when it needs to, and those reads go through the same rules as any other. The resource becomes part of your message, so it is in the transcript and a session resumed in the browser shows it. A resource over 64 KiB is refused; ask the agent to look up the part you need instead.
For a workflow whose second stage failed, the agent receives a block like this, with the stage ids it needs to look the details up:
{
"createTime": "2026-11-12T09:14:03Z",
"endTime": "2026-11-12T09:20:41Z",
"note": "Text fields (names, errors, descriptions, details) are left out of this summary, since anyone who can create the resource writes them. Read them with workflow_describe, node_show or volume_info if you need them.",
"startTime": "2026-11-12T09:14:05Z",
"status": {
"stages": [
{
"createTime": "2026-11-12T09:14:04Z",
"endTime": "2026-11-12T09:15:04Z",
"id": "5e1f0a2b-3c4d-4e5f-8a6b-7c8d9e0f1a2b",
"kind": "STAGE_KIND_JOB",
"startTime": "2026-11-12T09:14:07Z",
"status": "finished"
},
{
"createTime": "2026-11-12T09:14:04Z",
"endTime": "2026-11-12T09:20:40Z",
"id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"kind": "STAGE_KIND_JOB",
"startTime": "2026-11-12T09:15:05Z",
"status": "errored"
}
]
},
"userId": "3c9d2e4f-8a1b-4c5d-9e6f-7a8b9c0d1e2f",
"workflowStatus": "errored"
}
The stage names and the error message are not in it; asked “why did this
fail?”, the agent reads them with workflow_describe.
Context from a workflow definition by name (definition/NAME) is not supported
yet and is refused.
The agent answers using a model registered on the cluster. With no --model, a
session uses its own recorded model, and failing that the cluster’s default. If
no model is available, the turn ends with a message saying how to register one.
$ fuzzball agent --model fast--model applies when resuming a session as well as when starting one, taking
effect from the next turn. /model NAME does the same mid-conversation; the
transcript records which model produced which answer.
$ fuzzball agent list
$ fuzzball agent show debugging
$ fuzzball agent rename debugging auth-outage
$ fuzzball agent delete debugging
$ fuzzball agent export debugging
$ fuzzball agent list-tools debugging--page-size on list is the server batch size per request, not a cap on what
you see — the listing fetches every page regardless. To bound a long listing
use --max-pages; a capped result says so on stderr.
list-tools shows the tools a session may currently use, which depends on the
tiers it has been granted, with whether each call asks first and whether its
output may count as untrusted.
export writes the transcript as Markdown by default, covering the whole
conversation however long it ran. Every body – what you typed, what the
agent answered, a tool result – is written inside a code fence longer than any
run of backticks it contains, so nothing inside the conversation can forge the
structure around it: an answer containing ## You followed by a sentence you
never typed cannot turn into a user turn in the record. Each message carries
its time, each tool call its id and arguments, and each tool result the call it
answers and whether it ran on the session’s settings, on your approval, or
was stopped. An
export that cannot fetch the whole transcript fails rather than writing part of
it. --output json and
--output yaml give something a program can consume. Use JSON for exact values:
YAML writes invisible format characters, such as a bidi override or a
zero-width joiner, as escape text instead:
$ fuzzball agent export debugging --output jsondelete removes the session and its transcript. Anything the agent created
while you talked to it – a workflow, a volume – is not touched.
Every field the cluster returns — a session name, a model name, a tool name,
the text of an error — is printed with its control characters escaped, so a
name containing an ESC or a carriage return shows as \x1b and \x0d rather
than acting on your terminal. Those fields are set through the API and only
ever length-checked, so a name could otherwise erase the line it is printed on
or forge a row in a table. The same holds for the tables and records every
fuzzball agent command prints.
--output json from the fuzzball agent commands that take it – list,
show, list-tools and export – escapes every control
character as \uXXXX: the C0 range, DEL, and the C1 range, which includes
U+009B, a single-character form of the escape that starts a terminal control
sequence. The escaped form decodes to exactly the original text. Note that
jq -r decodes these escapes back into live characters.
Characters that change how the text around them is shown without being
visible – bidirectional overrides such as U+202E, zero-width characters, and
the line separator U+2028 – are shown as escape text as well: in names, ids,
tool-call arguments, JSON (as \uXXXX, which decodes to the original) and YAML.
The agent’s replies keep zero-width characters, which emoji and some scripts
need, and escape only bidirectional embeddings, overrides and isolates, tag
characters, and the line and paragraph separators.
Nothing about the conversation runs on your machine beyond the terminal itself.
The agent runs in Orchestrate: it holds the transcript, calls the model, and
runs the tools. That is why a session started here is the same session in the
web interface, why the credential for a hosted model never reaches your laptop,
and why closing your terminal does not lose the session – it is on the
cluster, and fuzzball agent resume returns to it. A turn still answering
when you close the terminal stops there: the agent does not carry on
unattended, though work a tool already started on the cluster, such as a
submitted workflow, is not undone.