Run agent-written code on an isolated boxd machine against an Argon MongoDB sandbox, using a database user made for one run. Output, failure paths and limits.
Argon Labs11 min read
Current capability notes: checkout materializes a physical database; native actor attribution is per branch/run; undo needs complete images and retained history. CLI sandboxes require watch and scheduled sweep. Read the capability matrix.
Agent-written code that runs in a code sandbox still needs a database, and the connection string you hand it decides what it can damage. An earlier article argued that such an agent needs two sandboxes: a code sandbox for what it runs, and a data sandbox for what it writes. It ended with the two points that decide whether the pair works, network reach and credentials, and it showed no code for either.
Argon's repository now has an example that does both. Agent-written code runs on an isolated boxd machine and writes to an Argon MongoDB sandbox through a database user that exists for one run. The host then prints what the code changed and discards the sandbox, or merges it when you ask. Michiel Voortman, a co-founder of boxd, wrote the example, and we reviewed and merged it in pull request 101.
This article goes through the three decisions in it that are worth copying with any code sandbox: which database credential the agent's code gets, when its network closes, and what you review before anything reaches the main branch. It also shows what a run prints, what happens when a run fails, and what the example does not cover.
What we ran, and what we did not #
Michiel ran the example on boxd machines with Argon 2.3.3 and MongoDB 7.0. His runs, his inspection of a kept machine and the README's port check are recorded in the pull request. We have not run the example on boxd.
On November 17, 2026 we ran its data half. We used host.py and agent.py from the repository unchanged, Argon 2.4.0 installed from npm, and MongoDB 7.0.48 as a one-node replica set with a keyfile and authentication, started with the README's commands. A local container stood in for the boxd machine: a small replacement for the boxd SDK sent the commands that host.py issues to that container. Every transcript below is from that run.
So the output below shows what Argon and MongoDB do. It is not evidence about boxd's isolation, private network or egress allowlist. For those we describe what boxd's documentation says, checked the same day, and what Michiel reports.
Two machines on one private network #
data machine (host) agent machine (isolated)
mongod with auth, argon console, host.py ──▶ agent.py
1. Argon sandbox + restricted user 2. writes through PyMongo
3. diff, then discard (or --apply) ◀── network: argon-example only
MongoDB, the Argon console and host.py run on one boxd machine, the data machine. For each run, host.py creates a second machine for the agent's code and deletes it when the run ends.
According to boxd's documentation, each machine is a microVM under KVM with a kernel, network stack and disk of its own. A machine created as isolated is kept out of the account's default network and can reach only non-isolated machines that are on a named network with it. The example puts both machines on one network, argon-example. By that description, the agent machine reaches MongoDB at <data-machine>.boxd:27017 and no other machine in the account.
That takes care of network reach, the first of the two points: both sandboxes sit where they can reach each other privately. Whether anything else can reach MongoDB is something to check, not assume, because docker run -p 27017:27017 listens on every interface of the data machine. The README has the check. It pings MongoDB from a machine on the network and from one outside it, and Michiel reports that on his machines only the first got an answer.
The credential: a MongoDB user made for one run #
When Argon creates a sandbox it returns a connection string, and the obvious move is to pass that string to the agent. Here it is next to the engine's own, with the passwords removed:
engine's MONGODB_URI: mongodb://argon:<password>@localhost:27017/?replicaSet=rs0&authSource=admin
sandbox connection string: mongodb://argon:<password>@localhost:27017/argon_br_6afc997c23961213ce8ef421?replicaSet=rs0&authSource=admin
The sandbox connection string is the engine's credential with the sandbox's database name added. That is fine for a script you trust. For code you do not trust, it is the engine's access to the whole deployment. Argon's operations guide says to provision restricted users for agents that should not share it.
We passed it to the example's agent.py anyway, to see what would happen. agent.py begins by trying to read the main branch's database, and it stops if the read succeeds:
agent.py exited 1:
the sandbox user can read the main branch
So host.py creates a MongoDB user for each run, with one role on one database (shortened):
user, password = "argon-agent-" + run_id, secrets.token_urlsafe(24)
agent_uri = "mongodb://{}:{}@{}/{}?authSource=admin&directConnection=true".format(
urllib.parse.quote_plus(user),
urllib.parse.quote_plus(password),
args.mongo_host,
sandbox_db,
)
admin = MongoClient(os.environ["MONGODB_URI"])
admin.admin.command(
"createUser",
user,
pwd=password,
roles=[{"role": "readWrite", "db": sandbox_db}],
)
We ran the same checks with both credentials, from the container that stood in for the agent machine:
| Check | Connection string from Argon | User made for the run |
|---|---|---|
| MongoDB role | root onadmin |
readWrite on the sandbox database |
| Count tickets in the sandbox | 3 | 3 |
| Count tickets in the main branch | 3 | Refused: Unauthorized (code 13) |
| Insert into or update the main branch | Not attempted | Refused: Unauthorized (code 13) |
| List databases | Every database, main and admin included | The sandbox only |
Read admin.system.users |
Allowed | Refused: Unauthorized (code 13) |
The Argon column says root because the README starts MongoDB with a single admin user and Argon runs as that user. A narrower engine user would shrink that column. The engine still has to reach every branch database it manages, main included, so its credential always covers more than one sandbox.
The new user's connection string is not put on a command line or in a file. host.py writes it to the standard input of the one command that starts agent.py, and the shell reads it into an environment variable for that process:
command = [
"bash",
"-c",
"read -r ARGON_SANDBOX_URI && export ARGON_SANDBOX_URI"
f" && exec {AGENT_DIR}/bin/python {AGENT_DIR}/agent.py",
]
with boxd.machines.stream_exec(
machine_id, command=command, env={"ARGON_MAIN_DB": main_db}
) as stream:
stream.write(sandbox_uri + "\n")
stream.write_eof()
When the run ends, host.py drops the user in a finally block, also when the agent failed. After that the same connection string no longer authenticates: in our run MongoDB answered AuthenticationFailed (code 18). After every run, usersInfo listed only the admin user.
The network closes before the credential arrives #
This is how host.py prepares the machine (shortened):
PACKAGE_HOSTS = ("pypi.org", "files.pythonhosted.org")
spec = (
Machine.spec()
.isolated()
.network(args.network)
.egress(*PACKAGE_HOSTS)
.label("app", "argon-example")
)
machine = boxd.machines.create(
args.name or "argon-agent-" + run_id, spec=spec, ssh=False
)
run_checked(
boxd,
machine.id,
f"python3 -m venv {AGENT_DIR} && {AGENT_DIR}/bin/pip install -q pymongo",
timeout=300,
)
boxd.machines.set_egress_allow(machine.id, ["none"])
boxd.machines.files.upload(
machine.id, f"{AGENT_DIR}/agent.py", (HERE / "agent.py").read_bytes()
)
output = run_agent(boxd, machine.id, agent_uri, database_of(main_uri))
The order matters more than any single line. While the machine installs PyMongo it may reach PyPI and nothing else on the internet, and at that moment it holds no credential and none of the agent's code. Then host.py sets the egress allowlist to none. boxd documents that entry as switching the allowlist on with no destinations in it, and says the allowlist cannot be changed from inside the machine. Only then does host.py upload agent.py and hand over the connection string.
From that point the agent's code has a database connection and no outbound route to the internet. SSH is off as well, and host.py drives the machine through boxd's API. Michiel reports in the pull request that a kept machine could not resolve pypi.org while it could resolve the data machine, and that no file on it held the connection string.
What the agent's code does, and what the host sees #
agent.py stands in for code an agent would write, so the example needs no model and no LLM account. After the check above, it closes a ticket that already has a resolution, escalates a high-priority ticket, and writes a note to a collection it creates:
closed = db.tickets.update_many(
{"status": "open", "resolution": {"$exists": True}},
{"$set": {"status": "closed"}},
)
escalated = db.tickets.update_many(
{"status": "open", "priority": "high"},
{"$set": {"status": "escalated"}},
)
db.triage_notes.insert_one(
{
"_id": "triage-1",
"closed": closed.modified_count,
"escalated": escalated.modified_count,
}
)
A default run of host.py prints the diff and discards the sandbox. This is our run, from the agent's own output onward:
agent: {"database": "argon_br_6afc996423961213ce8ef3a1", "closed": 1, "escalated": 1}
change: {"collection": "tickets", "document_id": "T-1", "document": {"_id": "T-1", "priority": "low", "resolution": "duplicate", "status": "closed"}, "document_key": "T-1", "before": {"_id": "T-1", "priority": "low", "resolution": "duplicate", "status": "open"}}
change: {"collection": "tickets", "document_id": "T-2", "document": {"_id": "T-2", "priority": "high", "status": "escalated"}, "document_key": "T-2", "before": {"_id": "T-2", "priority": "high", "status": "open"}}
change: {"collection": "triage_notes", "document_id": "triage-1", "document": {"_id": "triage-1", "closed": 1, "escalated": 1}, "document_key": "triage-1"}
discarded the sandbox; run again with --apply to merge
Each change carries the document as the agent left it and, for an update, the document before. The reviewer reads "status": "open" becoming "status": "closed" instead of trusting the agent's summary. The third change is a document in a collection the agent created. From Argon 2.3.1 such a collection is captured exactly, with no preparation step. After this run the main branch still held three open tickets and no triage_notes collection.
With --apply, host.py saves a merge plan, stops if the plan has conflicts, and applies that plan:
applying merge plan 6afc996923961213ce8ef3be
Afterwards the main branch held T-1 closed, T-2 escalated, T-3 open and one triage note.
--apply is a scripted merge: no person stands between the preview and the apply. Each run also starts a new project, machine and sandbox, so --apply merges the diff of its own run. This agent is deterministic, so that diff has the same three changes you read in the default run. A real agent can differ between runs. For one, keep the sandbox, save a merge plan, read it, and apply that plan by its ID. The reviewed merge tutorial does this through MCP, and the features page shows the two CLI commands.
When a run goes wrong #
We ran three failure cases. In each, by the time host.py stopped it had made the call that deletes the machine and had dropped the MongoDB user, and the main branch was unchanged.
The agent cannot reach MongoDB
We pointed --mongo-host at a name that does not resolve. agent.py gave up after its ten-second server selection timeout, and host.py exited with status 1 and the agent's traceback (shortened):
RuntimeError: agent.py exited 1:
Traceback (most recent call last):
...
pymongo.errors.ServerSelectionTimeoutError: nowhere.invalid:27017: [Errno -2] Name or service not known (configured timeouts: socketTimeoutMS: 20000.0ms, connectTimeoutMS: 20000.0ms), Timeout: 10.0s, ...
The agent's code writes nothing
We replaced agent.py with a script that counts the open tickets and writes nothing. Its output arrived, and then host.py stopped while printing the diff (shortened):
agent: {"database": "argon_br_6afc997723961213ce8ef3e0", "open": 3, "written": 0}
Traceback (most recent call last):
...
for change in diff["changes"]:
TypeError: 'NoneType' object is not iterable
Argon's REST API answers "changes": null for an empty diff, and host.py expects a list. That is a bug in the example that our review missed, not a property of the design. It is open as issue 105, which is a small first contribution if you want one.
The agent's code drops a collection
readWrite lets code drop collections in its own sandbox. We added db.tickets.drop() to agent.py. The review stopped:
RuntimeError: GET /projects/boxd-triage-1e8f7eae/branches/agent/diff: {"error":"drop on tickets is not captured; branch history is incomplete"}
Argon marked the sandbox's capture as degraded and gave the same answer to a merge preview. It does not offer a partial diff when part of the history is missing. The main branch still held its three open tickets. The way out is to discard the sandbox:
argon sandbox discard -p boxd-triage-1e8f7eae -b agent
Discarded; storage reclaimed.
We found one rough edge on the way. Until that sandbox is discarded, the REST call that lists the project's sandboxes fails with the same error, so the console cannot list them. That is issue 106.
What a failed run leaves behind
In all three cases host.py stopped before it could discard the Argon sandbox. Where the diff could still be read, Argon listed the leftover sandbox with an expiry one hour after its creation. A running console, API or MCP server removes a sandbox once it is past its TTL. We checked that in the same deployment with a sandbox given a one-minute TTL: it was still listed 80 seconds after creation and was gone, its database included, at the next check 20 seconds later. Nothing sweeps if no such process is running. You can also discard a leftover sandbox yourself with the command above.
Limits #
- The boxd half is not ours to vouch for. Its isolation, network partition and egress allowlist are described here from boxd's documentation and its author's runs. We have not tested them. The same documentation says an isolated machine keeps its public HTTPS domain. The example sets nothing for inbound requests to the agent machine, and we have not looked at what that exposes.
- A sandbox is a full copy. Creating one materializes a physical MongoDB database, so its time and storage grow with your data. Three tickets say nothing about that. The openbenchmark suite measures readiness as
sandbox_capture_ready_ms. - The user limits where the code writes, not what it does there. Inside its sandbox the code can delete every document or drop a collection, and a drop ends the review.
- A TTL schedules cleanup and stops nothing. It does not stop the agent's machine or revoke a MongoDB credential.
host.pydoes both itself. host.py's checks are written for this agent. After--applyit asserts the three changes shown above, and it fails on an empty diff. Replace those checks when you replaceagent.py.- The data machine is trusted. The boxd API key and the engine's
MONGODB_URIstay on it. Whoever controls that machine controls both sandboxes. - boxd bills for the machines. Its private networks also do not cross regions, so
--regionhas to be the data machine's region. The README ends with the clean-up commands.
Run it #
The example's README has every command: the two machines, MongoDB with authentication, the port check, both runs and the clean-up. You need a boxd account and its CLI, and Argon 2.3.1 or newer. boxd's documentation has a shorter walkthrough of the same example.
If you use a different code sandbox, the half of host.py that talks to Argon and MongoDB carries over as it is: it uses Argon's REST API and PyMongo. The half that creates the machine, closes its network and runs the code is written against boxd's SDK, and we have not ported it. Whichever you use, the three decisions stay the same: a database user that exists for one run and one sandbox, a network that closes before the credential arrives, and a diff that a person reads before a merge.
To try the data half alone first, the local quickstart needs only MongoDB and the Argon CLI.
Frequently asked questions #
- How do I give sandboxed agent code access to MongoDB?
- Create a data sandbox for the run, create a MongoDB user that can read and write only that sandbox's database, and pass that user's connection string to the code sandbox over a private network. Drop the user when the run ends.
- Why not pass the agent the connection string Argon returns for the sandbox?
- It carries the engine's own MongoDB credentials with the sandbox's database name added. In the example's setup that user is root, so code holding it can read the main branch and every other database. A user made for the run, with readWrite on the sandbox database only, was refused when it tried.
- What can the agent's MongoDB user do?
- Read and write the sandbox's database, including dropping its collections. It cannot read or write the main branch or list other databases. If it drops a collection, Argon reports incomplete history, refuses to show a diff, and the sandbox has to be discarded.
- Does the example need a model or an LLM API key?
- No. agent.py is a fixed script that stands in for agent-written code. You need a boxd account and API key, MongoDB 7 or newer as a replica set, and Argon 2.3.1 or newer.
- Was this example run on boxd?
- By its author, Michiel Voortman of boxd, whose runs are recorded in the pull request. We ran the Argon and MongoDB half with a local container in place of the boxd machine, so our output is not evidence about boxd's isolation.
- Can I use another code sandbox instead of boxd?
- The half of host.py that talks to Argon and MongoDB uses Argon's REST API and PyMongo, and does not depend on boxd. The half that creates the machine, closes its network and runs the code uses boxd's SDK and would have to be rewritten. The code sandbox also has to reach your MongoDB deployment over a network you control.
Continue reading #
- Code Sandboxes Isolate What Agents Run. What Isolates What They Write?
- Zero Conflicts, Wrong Price: Validate MongoDB Agent Catalog Changes
- A Reproducible MongoDB MCP Tutorial: From Sandbox to Reviewed Merge
Argon is open source and MIT-licensed.