Fuzzball Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

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 agent

That 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 debugging

A 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 debugging

The 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.

During a conversation

Type to talk to the agent. Lines beginning with / are commands to the CLI rather than messages to the agent:

CommandWhat it does
/sessionThis session’s settings and token usage
/toolsThe tools the agent may use right now
/model NAMEAnswer with a different model, from the next turn
/allow TIERGrant a permission: write, exec or destructive
/revoke TIERRemove a permission: write, exec or destructive
/context KIND/IDSend a workflow, node or volume with your next message
/exportPrint the transcript, including tool results
/clearClear the screen
/quitLeave; 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.
/clear clears 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.

What the agent is allowed to do

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.

TierExamples
readRead the docs, list workflows, describe a node
writeCreate or update something without running compute
execRun cluster compute
destructiveCancel 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. /tools shows what it can actually reach.
  • destructive always asks, and y is not enough. Granting the tier lets the agent propose a destructive call; every one still stops and waits for you to type yes or the tool’s name.
  • /allow and /revoke change 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 on resume work the same way and only ever add.
  • Granting a tier does not turn on auto-approval. /revoke also turns off auto-approval for that tier, and if a session holds an auto-approval for a tier it has not been granted, /allow and --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.

Untrusted content

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.

Giving the agent a resource

--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.

Choosing a model

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.

Managing sessions

$ 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 json

delete removes the session and its transcript. Anything the agent created while you talked to it – a workflow, a volume – is not touched.

Why a name sometimes prints with \x1b in it

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.

Where the work happens

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.