A Disposable MongoDB Sandbox for Every AI Agent

Give each AI agent a MongoDB sandbox with Argon. Learn branch-per-agent isolation, dataset pins, TTL cleanup, and the capture requirements for undo.

By Argon Labs9 min readUpdated
AI AgentsMCPMongoDB

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.

A MongoDB sandbox gives each agent a separate database for experiments. The agent can modify its branch while you review which changes to apply to its parent. Checkout takes time and storage as it materializes the data. Scope the agent’s credentials to its sandbox database.

That is the branch-per-agent pattern, and Argon is built to make it a one-liner.

The branch-per-agent loop

  1. Fork a branch. Create a sandbox off production (or off a pinned dataset), optionally with a time-to-live. REST/MCP manage expiry while running; standalone CLI use requires a scheduled sweep. To start from a replica-set database that is in use, import it with argon import database --online and keep main current with argon source follow (from Argon 2.7.0; tested on MongoDB 7.0 replica sets only, not on Atlas or with access control).
  2. Let the agent work. Hand it the branch’s connection string. It reads and writes with any MongoDB driver — no code changes, no awareness that it is in a branch.
  3. Review the diff. Compare the branch with its parent to find changed document keys, then inspect the proposed values in the stored merge plan before applying it.
  4. Merge or discard. Merge the good work back as a reviewed data PR — or throw the whole branch away. A merge is an explicit write to the parent; your application must decide who may approve it. The parent is a branch inside Argon. When main follows a database you run, an ordinary merge into it is refused, and the reviewed plan is written to that database with argon merge apply --write-back --approve <digest> instead (from Argon 2.8.0; from the CLI only, not over MCP or REST; tested on MongoDB 7.0 replica sets only, not on Atlas or with access control).

Because a fully captured, retained write range can be reverted, you also get a safety net after the fact: if something slips through, you can undo one branch actor’s captured changes. Separate agents need separate branches; undo can refuse a range when required history or images are incomplete.

Wiring it up

Start with the local setup. The MCP example also needs the project initialization on the agents page. Argon exposes the loop through these interfaces:

Over MCP (Claude Code, Cursor, any MCP client)

claude mcp add --transport stdio --env MONGODB_URI='mongodb://localhost:27017/?replicaSet=rs0' argon -- argon mcp

The agent gets 13 control tools over stdio, including sandbox creation, diff, merge, undo, snapshots, and pins. It uses a MongoDB driver with the returned connection for data reads and writes. See the MCP tool boundaries for the available interfaces.

From the CLI or CI

# Existing docs-review project; create a new agent-review sandbox
argon sandbox create -p docs-review --from main --name agent-review --ttl 1h
# Keep capture running before the agent writes
argon watch -p docs-review -b agent-review
# In a scheduled job, clean up expired CLI sandboxes
argon sandbox sweep -p docs-review

From Python (LangGraph, Mem0)

python3 -m pip install "argon-agents[langgraph]==0.3.0"

Install in a Python virtual environment; this uses the matching PyPI release. The package supplies a LangGraph checkpointer and a Mem0 sandbox factory. Before Argon 2.3.1, prepare exact images on new collections before updates; from 2.3.1 capture reads them back while it is running.

Review MongoDB documents before merging

A reviewed merge here means reviewing changes to database documents. It is separate from a GitHub or GitLab code pull request. Give two agents separate branches from the same retained pin, compare their proposed changes, and inspect the merge plan before applying it. A conflicting edit needs a resolution decision; creating a sandbox does not approve its writes. Follow the two-agent review example to inspect a conflict and the resulting document values. The runnable MCP tutorial retrieves a stored merge plan for content review and checks the parent after either applying or discarding the proposal.

Sandbox TTL versus MongoDB document TTL

MongoDB TTL indexes delete expired documents from a collection in the background. They do not replace a job that discards an entire MongoDB sandbox, and expiration does not guarantee immediate deletion.

Argon sandbox TTL makes a branch eligible for cleanup. In Argon 2.1.3, the REST and MCP servers run a sweep once per minute while running. The first pass is after that interval, including after a restart. An expired sandbox can therefore remain present until a successful pass. These are cleanup timings, not an access deadline.

With standalone CLI commands, schedule argon sandbox sweep for the project and inspect both reaped and skipped in its JSON output. A TTL value alone does not run the cleanup process. A branch with dependent children can be skipped; deletion errors can also delay cleanup. Finish any review or export before expiry, or remove the TTL with argon sandbox keep before the cleanup pass if you need to retain the branch.

Try expiry, shutdown, and restart locally

The TTL example uses synthetic data, a three-second CLI TTL, and a six-second MCP TTL (ttl_minutes: 0.1). It waits for real elapsed time without changing the clock or expiry records. Download both Python files into the same directory, install Argon 2.12.0 and Python 3.12+ with PyMongo, and point the example at a disposable local MongoDB replica set. The MCP tutorial prerequisites cover that setup.

curl -fSLO https://argonlabs.tech/examples/mcp_review.py
curl -fSLO https://argonlabs.tech/examples/mcp_ttl.py
export ARGON_TEST_MONGODB_URI='mongodb://localhost:27017/?replicaSet=rs0'
export ARGON_BIN=argon
python mcp_ttl.py --output-dir ttl-proof

Allow about two and a half minutes and use a fresh output directory. The script starts and stops only its own MCP child process, keeps MongoDB running, and removes its fixture databases at exit. It checks:

  1. CLI only: the expired branch and its test document remain until an explicit sweep removes the branch and physical database.
  2. MCP running: the six-second TTL expires before the first periodic pass; that pass then removes the sandbox.
  3. MCP stopped and restarted: the test document remains after expiry while the process is stopped, and shortly after restart. The restarted process removes the old sandbox on its next periodic pass.

The output directory contains real protocol messages, server logs, CLI results, and verification.json with measured timings. With the published Argon 2.1.3 binary and MongoDB 7.0.45, both managed removals were observed about 61 seconds after starting or restarting MCP. That observation is not a deletion deadline. This checks short TTL behavior; the one-hour example above is a configuration example, not a one-hour test result. Stop clients from writing before cleanup: TTL does not revoke their MongoDB credentials.

Update, November 20, 2026. From Argon 2.10.0, argon sandbox create --credential issues a MongoDB user that can read and write only the sandbox's database. Discarding the sandbox, or the sweep after its TTL, revokes that user, and a connection already open is refused on its next write. Until a sweep runs, an expired sandbox's credential still works.

Reproducible evals with pins

Evaluations are only meaningful if every run starts from the same data. A dataset pin is an immutable, named state of the database; each eval run forks a fresh branch from the pin, so the input is identical for that retained pin. Time travel is available within retained history. A position whose history garbage collection has already reclaimed returns an error instead of a partial answer. Pins protect the data they reference while the pin exists; keep backups and choose retention for your workload.

Why this matters now

Agents are moving from reading data to acting on it, and the database is where actions become permanent. Giving every agent its own branch turns an irreversible operation into a reviewable one — the same shift that pull requests brought to code. Production stops being the place agents experiment, and starts being the place their reviewed work lands when your application enforces that review decision.

Update, November 21, 2026. Since this post was written, Argon 2.10.0 tests importing, following and write-back against sources with access control and TLS, across primary elections on a three-member replica set, and with MongoDB 6.0 and 8.0, and 2.12.0 adds MongoDB Atlas, including the free tier; sharded sources are still untested. argon sandbox create --credential gives a sandbox its own MongoDB user, revoked when the sandbox is discarded or swept. From 2.11.0 a sandbox builds the source's secondary indexes, so its unique constraints hold as on the source. The rest of this post describes the release it names.

Frequently asked questions

Why can’t an AI agent just use the production database?
Because the blast radius is your whole business. An agent that misreads an instruction can delete or corrupt live data, and you often cannot tell what it changed until later. A branch gives the agent a real database to work in while production stays untouched.
How does an AI agent get its own database?
With Argon, the agent (or your orchestration code) calls a single command or MCP tool to create a sandbox branch. It gets back an ordinary MongoDB connection string and reads and writes normally — no special SDK.
What is an MCP server for MongoDB?
Model Context Protocol (MCP) is a standard way to expose tools to AI agents. Argon ships 13 MCP tools for sandboxes, branch connections, diffs, merge plans, undo, snapshots, and pins. Document reads and writes use the returned MongoDB connection through a driver; retained-history queries use Argon’s CLI or REST API.
How do I make agent evaluations reproducible?
Use dataset pins: named references to captured document states. Fork each run from the same retained pin to control its starting document state. Matching input does not make agent outputs deterministic or guarantee identical physical database files.