One sandbox harness for Sudo, the graph assistant, and the assistants you build

Rafael
•

Every AI assistant in Curiosity Studio runs on the same harness. By harness I mean everything in an assistant except the model: the place its commands run, the files it can see, the limits on what a command may do, how its work survives between calls, and how a change it makes reaches anyone. Sudo, the admin assistant, was the first thing built on it. The graph assistant, the review conversation and the test runner are Sudo again, with a different sandbox and a different prompt. And the assistants a workspace builds for its own people use the same harness through one C# interface.

This post is about that arrangement: what the shared part is, what each variation of Sudo changes, and what teams have built on it. HubSpot's engineering team wrote recently about Aviator, the framework their internal agents are built on, and reading it made me want to write down ours.

What the harness is

One harness, many assistants. Four assistants on top, each a prompt, tools and skills. Their sandboxes are declared as mounts and commands, and all of them run on the same harness.

An assistant in Studio is a prompt, a set of AI tools and a set of skills. The interesting tools are sandboxes: a tool that does not call one method but runs a bash script, with Python available, over a filesystem built for that assistant. The interpreter is Computerwelt, our C# port of a sandboxed bash and a minimal Python, running in the server process. It starts no process, touches no host disk, and has no network.

The harness is what every one of those sandboxes gets without asking for it:

What the harness gives What it means in practice
bash and Python, in process about 120 commands: grep, rg, sed, awk, jq, yq, sort, diff, python and the rest
one virtual filesystem a path under no mount does not exist; there is no root to write to
limits clamped to the workspace an AI tool's script runs 60 seconds by default and 300 at most, and prints 256 KB by default and 4 MB at most
one session per chat the working directory and the scratch files are there on the next call, and after a restart
reads as the person chatting a query, a search or a file built from the graph shows only what that person may open

What an assistant's author writes is the other half: the mounts (which folders exist and what is in them), the commands that a file cannot be, and a handful of switches for the graph query engine, live documents, a browser and artifacts. Everything in that half is specific to one assistant. Everything in the harness is shared, so a fix to the harness reaches every assistant at once, and a command two assistants share is one implementation: the graph assistant's graph and query are the same command classes Sudo's shell runs, so the two answer the same question the same way.

Sudo, the first and largest

Sudo is the admin assistant. His sandbox is the workspace shell, and its main folder, /workspace, is the workspace configuration as files: one file per endpoint, AI tool, agent, scheduled task, index and schema, exactly as the definitions export writes them. Around it sit the front end's source, a reference workspace, the product's own C# surface as /sdk, live runtime state as /proc, and about thirty workspace commands on top of bash. The earlier posts cover how that shell replaced seventy-four tools and why nothing he writes applies until a person approves it. Here is what it looks like from the inside. The sessions in this post are shortened, and the records in them are made up.

An engineer writes to the admin that they cannot see a non-conformance report their colleague can. The admin asks Sudo why:

sudo@workspace:~$ graph search "NCR-24-0193" -t NonConformance -n 1
5mP2cQkR8vZtWn3aLd7Hxe	NonConformance	{"NcrId":"NCR-24-0193","Title":"Crack at the weld seam of a gearbox housing",...}

sudo@workspace:~$ access j.meyer 5mP2cQkR8vZtWn3aLd7Hxe
user:     8HqWb2nKcV4sTe9mRz1Lpo  Jana Meyer
node:     5mP2cQkR8vZtWn3aLd7Hxe  NonConformance
type:     NonConformance has no node-type rule
owners:   Quality Plant 2 (access group) 3XyTq8mBe2LwVn5sKd9Rfa
verdict:  not visible
why:      owned only by Quality Plant 2, and this user is in none of its groups (member of Quality Plant 1)

Nothing changed, and nothing could have: access reads. The answer is a fact about the workspace's access groups, and the admin decides what to do with it.

The same admin then asks for the overdue corrective actions on the quality dashboard to show their supplier. Sudo reads the schema, edits the endpoint, and builds it before he says anything:

sudo@workspace:~$ type CorrectiveAction
[schema: Curiosity.Schemas.Key("CapaId")]
public class CorrectiveAction
{
    public string CapaId { get; set; }

    public Time DueDate { get; set; }

    public string Status { get; set; }

    public string Title { get; set; }
}

sudo@workspace:~$ build
FAIL  code/endpoints/quality/capa-overdue.cs
        (38,41): error CS1061: 'CorrectiveAction' does not contain a definition for 'SupplierName'
0 of 1 file builds.

sudo@workspace:~$ graph sample CorrectiveAction | sed -n 2p | cut -f1 | xargs graph edges
#edge	count	targets (first 10)
RaisedAgainstSupplier	1	6Tb1rWq8Zk3mNc5Xv2Lpa9
ForNonConformance	2	9Pq3mZx7Lk2cVb8nRt4Wsd, 5mP2cQkR8vZtWn3aLd7Hxe

sudo@workspace:~$ sed -i 's/capa.SupplierName/SupplierOf(capa)/' /workspace/code/endpoints/quality/capa-overdue.cs
sudo@workspace:~$ cat >> /workspace/code/endpoints/quality/capa-overdue.cs <<'CS'

string SupplierOf(ReadOnlyNode capa) => Q().StartAt(capa.UID).Out(N.Supplier.Type, E.RaisedAgainstSupplier)
                                         .AsEnumerable().Select(s => s.GetString(N.Supplier.Name)).FirstOrDefault();
CS
sudo@workspace:~$ build
ok    code/endpoints/quality/capa-overdue.cs
1 of 1 file builds.

sudo@workspace:~$ commit -m "Show the supplier on overdue corrective actions"
M  code/endpoints/quality/capa-overdue.cs

1 file is waiting for the admin to review and approve.
Nothing has been applied to the workspace. Tell them what you changed and why, and stop there - they will approve it in the chat.

The supplier is not a field on the corrective action. It is an edge, and the compiler told him so before anyone else saw the change. build compiles the changed file against the scope it will run in, and commit refuses a file that does not build. What reached the admin is a diff in the chat with an Approve button. If another admin had edited that endpoint in the meantime, commit would have refused with CONFLICT and asked him to pull the other change first.

The variations

Once Sudo existed, the next assistants were cheaper to build than the first, because most of what they needed was already there. Each variation is Sudo's identity with a different sandbox, a different prompt, or a different place in the workflow.

Variation Where it runs Its sandbox What it may change
Sudo beside the admin pages the workspace shell the configuration, through an approved commit
Graph assistant the Graph page graph-explorer: the view, the schema, the query docs nothing; it draws on the graph view
Reviewer a conversation the workspace starts the workspace shell, with review approves, rejects or escalates another conversation's commit
Tester Manage, Operate, Tests the workspace shell, read only, with the browser if allowed nothing; it hands in pass, fail or skip
Task board conversations one per card the workspace shell, on its own branch the configuration, through the approval level the board sets

The graph assistant

The Graph page shows the workspace's data as nodes and edges. The assistant beside it is Sudo with one sandbox, graph-explorer, next to the tools for reading skills and asking the user a question. The sandbox is an ordinary implementation of the same ISandbox interface a workspace uses for its own assistants. Its mounts are four folders:

public SandboxMount[] Mounts => new[]
{
    SandboxMount.Live  ("/view",   "the user's graph view, as it is now: nodes.tsv, selected.tsv and edges.tsv", ReadViewAsync),
    SandboxMount.Live  ("/schema", "node-types.tsv and edge-types.tsv with counts, nodes/<Type>.cs, connections/<Type>.tsv", ReadSchemaAsync),
    SandboxMount.Cached("/docs",   "query-language.md, query-methods.txt, and the query API as C#", ReadDocsAsync),
    SandboxMount.Scratch("/work",  "scratch space for intermediate results, UID lists and python scripts"),
};

/view is what the person has on screen, re-read before every script, so "these" in a question means selected.tsv. /schema/connections/ says which edge types lead from a type to which other types, which is what a traversal is written from. The commands are graph and query, the same ones Sudo's shell runs, plus path and push, which draw on the page:

sudo@graph:/work$ cat /view/selected.tsv
#uid	type	label
7Rk2pLmQ9vXc4Tn8bWe1Ja	Supplier	Halvorsen Castings
2Wd9sNq4kTz7Lm3xRc8Vbp	Part	Gearbox housing, rear

sudo@graph:/work$ path 7Rk2pLmQ9vXc4Tn8bWe1Ja 2Wd9sNq4kTz7Lm3xRc8Vbp --push
7Rk2pLmQ9vXc4Tn8bWe1Ja	Supplier	Halvorsen Castings
9Pq3mZx7Lk2cVb8nRt4Wsd	NonConformance	NCR-24-0177 Porosity in casting
4Hn8vKc2Qw7xLp5mTz9Bre	Part	Housing casting, rear
2Wd9sNq4kTz7Lm3xRc8Vbp	Part	Gearbox housing, rear
pushed the 4 nodes to the graph view

sudo@graph:/work$ graph edges 7Rk2pLmQ9vXc4Tn8bWe1Ja | grep NonConformance
SupplierOfNonConformance	43	9Pq3mZx7Lk2cVb8nRt4Wsd, 6Tb1rWq8Zk3mNc5Xv2Lpa9, ...

The person sees the four nodes appear on their graph, and the answer in the chat says which non-conformance links the supplier to the part, and that the supplier has 42 others. Nothing in this sandbox can change the workspace: the configuration, the commit loop and the front end are not mounted at all. When the person asks for a change, the prompt sends them to Sudo in the admin assistant.

The sandbox's source file is about 450 lines: the four mounts and the path and push commands. The rest of the assistant is a prompt. The interpreter, the session, the limits, graph and query came with the harness.

The reviewer and the tester

The reviewer exists for the admin who wants a second reading before a change applies. Each conversation has an approval level, and the default is Ask for approval: a commit waits for a person. At Approve for me, a commit starts a second conversation of Sudo's whose only new command is review:

sudo@workspace:~$ review show
commit 3f9a2c41 "Show the supplier on overdue corrective actions" (Workspace), staged 2026-11-19 14:02:11Z

  Modified  code/endpoints/quality/capa-overdue.cs  (endpoint)
...

sudo@workspace:~$ review escalate -m "Changes what the quality dashboard shows to every engineer; the admin should see it"

It can approve, reject with what to fix, or escalate to the administrator. It is a separate conversation on purpose: the reader of the diff did not write it, and has only the diff and the workspace to go on.

The tester is the same idea pointed at behavior. A Sudo test is a prompt an admin writes in plain language ("open the quality dashboard as an engineer at plant 1 and check that no plant 2 report appears"). A read-only conversation of Sudo's carries it out, with the workspace browser when the test allows it, and hands in the verdict with test-result pass|fail|skip, a note, and the output it rests on.

Building your own

The interface the graph assistant implements is public. An AI tool whose code returns an ISandbox becomes a sandbox tool, with the same editor, access modes, versioning and export as any other AI tool. Two members are required, Description and Mounts; the rest have defaults. Part 4 of the Computerwelt series walks through the interface member by member. Here is what teams have built with it.

A workbench over a workflow

A quality team handles non-conformance reports: a part fails an inspection, the report moves through review, a material review board decides what happens to the part, and a corrective action follows. Their assistant has a sandbox called ncr-workbench. Every record the person may see is a JSON file under /records, one folder per type, with an _index.tsv per folder for grep and awk. The workflow is a command:

$ awk -F'\t' '$4=="MRB review" && $6>30' /records/ncrs/_index.tsv | wc -l
7

$ jq -r 'select(.Severity=="Critical") | .Supplier' /records/ncrs/*.json | sort | uniq -c | sort -rn | head -3
     5 SUP-0412
     3 SUP-0187
     2 SUP-0098

$ ncr similar NCR-24-0193
NCR-24-0177  0.82  same part, same supplier, same defect code  (earlier, CAPA-24-031 open)
NCR-23-0954  0.71  same defect code, same stage                (earlier, closed: rework)
...

$ ncr advance NCR-24-0193 --comment "Matches NCR-24-0177; linking the open corrective action" --capa CAPA-24-031
{"Ncr":"NCR-24-0193","Step":"Corrective action","By":"Jana Meyer",...}

Two decisions in that sandbox are worth copying. Files are for reading: anything written under /records or /work stays in the sandbox. The only way to change the workspace is a command whose name says so, ncr advance or ncr raise, and both call the same endpoints the application's own screens call, so the workflow rules are the screens' rules and the step is recorded under the person's name. And every read is made as that person: an engineer in one division has an empty folder where the other division's reports would be, and ncr advance on a report they cannot see answers "not found".

An authoring sandbox that proposes

Technical authors write S1000D data modules, the XML documents maintenance manuals are made of. Their editor has an assistant whose sandbox, s1000d, mounts the module the author has open:

$ cat /document/about.txt
DMC-XA-A-29-11-00-00A-720A-A  Hydraulic pump, remove and install, issue 004

$ cp /document/module.xml /work/ && sed -i 's/torque to 85 Nm/torque to 92 Nm/' /work/module.xml
$ check /work/module.xml
well-formed: yes
BREX:        1 error
  BREX-S1-00213  <quantity> needs a unit of measure attribute (line 214)

$ sed -i '214s/<quantity>/<quantity quantityUnitOfMeasure="N.m">/' /work/module.xml && check /work/module.xml
well-formed: yes
BREX:        ok
layout:      ok, 6 pages

$ publish /work/module.xml -m "Torque value updated per service bulletin, unit added"

The comment at the top of its source calls it "the admin assistant's way of working, applied to one S1000D module". /document/module.xml is the editor's text, unsaved edits included, re-read before every script. The assistant edits a copy, check runs the business rules, and publish does not publish: it stores a proposal, and the authoring screen opens it beside the editor as the page, the XML and the PDF, each compared with what is there. The author applies it as one undoable step or leaves it. It is Sudo's commit with a different reader, and the same sequence holds for every sandbox in this post that changes something:

sequenceDiagram participant P as Person participant A as Assistant participant S as Sandbox participant W as Workspace P->>A: asks for a change A->>S: edits its own copy of the live file A->>S: build, or check S-->>A: errors, or ok A->>S: commit, publish, or propose S->>W: stores a proposal and applies nothing W-->>P: shows the diff beside the conversation P->>W: approves, or leaves it

An investigation sandbox that computes

A service team investigates machine alarms from log bundles: about 2.4 million parsed events across all the bundles. A fixed tool for "how long was the gap before the alarm" is one question; the next investigation asks a different one. Their sandbox mounts each bundle as a tab-separated table under /logs, unpacked only when it is read, and the prompt says statistics are computed in Python, never estimated:

$ head -3 /logs/_index.tsv
#bundle	machine	from	to	events	incident
B-1187	M-14	2026-10-02T06:00	2026-10-02T09:00	18422	INC-311
B-1190	M-14	2026-10-09T05:30	2026-10-09T08:30	17960	INC-318

$ python - <<'EOF'
import datetime as dt
rows = [l.rstrip('\n').split('\t') for l in open('/logs/B-1187/events.tsv') if not l.startswith('#')]
ts = [dt.datetime.fromisoformat(r[0]) for r in rows if r[2] == 'stage-heater']
gaps = sorted(((b - a).total_seconds(), a) for a, b in zip(ts, ts[1:]))
print(len(ts), 'events; longest gap', gaps[-1][0], 's at', gaps[-1][1])
EOF
1204 events; longest gap 417.0 s at 2026-10-02 08:41:13

$ compare-bundles B-1187 B-1190 --code E-4471
B-1187  E-4471  x12  first 08:48:02  (6 min 49 s after the gap)
B-1190  E-4471  x9   first 07:12:40  (5 min 51 s after a 388 s gap)

The raw logs belong to an access group per site. A person outside it sees an empty /logs, and every command that reads events tells them they have no access, so the rule lives in the data and not in the prompt. The root-cause statement the team is writing is mounted the same way the data module is, and propose hands an edited copy to the engineer, who decides.

A corpus for questions nobody listed

The simplest pattern, and the most common one: records as files, search, consult and a read-only query as commands, /docs/README.md as the first thing the assistant reads, and no write at all. A team that reviews patent filings uses one over the filings, their pages, claims and forms, to answer questions such as "which filings in German have a claim count that differs from the English set". Nobody would write a tool for that question in advance. A few lines of jq and comm answer it.

What the shared harness taught us

A few rules came out of building the variations and watching teams build theirs. Most of them are in create-sandbox-tool, the skill Sudo reads when an admin asks him to write a sandbox, so the next one starts from them.

  • Mount a file before writing a command. Most first drafts add a command for something grep, jq or awk already do. A command earns its place when the answer is not a file: a workflow step, a check against business rules, a computation over data too large to print.
  • Give every write a command whose name says so. Files written in a sandbox stay in it. A change leaves through commit, publish, propose or ncr advance, and each of those goes through the same path a person's change would.
  • Hand back a copy. When the work is a document or a configuration, the assistant edits a copy and returns a diff, and a person applies it. Sudo, the authoring sandbox and the investigation sandbox all end that way.
  • Read as the person. Access is enforced where the data is read, so an assistant cannot show anyone what they could not open in the application. A rule that lives only in the prompt is one the model can fail to follow.
  • Leave out what the assistant should not see. A sandbox cannot reach a record type nobody mounted or listed for query. That is how the authoring sandbox keeps one author's unsaved session away from another author's assistant, and how most sandboxes keep the user list out.

The AI tools documentation covers how a tool is written, enabled and restricted, and part 4 of the Computerwelt series is the complete ISandbox reference with a worked example.

Read next

Articles on context graphs, enterprise search and industrial AI

Connected knowledge for AI systems