MongoDB sandboxes for AI agents
Give each run a separate database. Your agent reads and writes with an ordinary MongoDB driver, and you review the changes before merging them into the parent branch.
These examples connect to your own local deployment. First Start locally with MongoDB and the Argon CLI. To see an illustrated review workflow, Explore walkthrough.
MCP
Claude and Cursor
The client starts argon mcp as a local process. It manages capture and sandbox expiry while it runs; a separate console process is optional.
After the local MongoDB setup, create a project once from a terminal:
export MONGODB_URI='mongodb://localhost:27017/?replicaSet=rs0'
argon projects create agent-labClaude Code
claude mcp add --transport stdio \
--env MONGODB_URI='mongodb://localhost:27017/?replicaSet=rs0' \
argon -- argon mcpRun /mcp in Claude Code to check the connection. Claude Code setup reference
Cursor
Add this server to .cursor/mcp.json in your project. Merge the argon entry into any existing mcpServers object.
{
"mcpServers": {
"argon": {
"type": "stdio",
"command": "argon",
"args": ["mcp"],
"env": {
"MONGODB_URI": "mongodb://localhost:27017/?replicaSet=rs0"
}
}
}
}Enable the server in Cursor's MCP settings. If the app cannot find argon, use the full executable path printed by command -v argon. Cursor setup reference
Check the connection
Ask: “List the branches in the agent-lab project, then create a 30-minute sandbox. Show me its branch name.” You should see main and a new sandbox. The tools include argon_sandbox_create, argon_diff and argon_merge_preview.
Give the agent the sandbox connection for data writes. Each tool declares whether it only reads and whether it can destroy data, so clients that ask before destructive calls ask before a merge, an undo or a discard.
Keep the merge decision with a person
By default the agent can apply a merge plan it prepared itself. You can withhold that tool, so it is neither listed nor callable, and apply the plan you reviewed from a terminal.
claude mcp add --transport stdio \
--env MONGODB_URI='mongodb://localhost:27017/?replicaSet=rs0' \
argon -- argon mcp --disable-tools argon_merge_apply
# after reading the plan the agent prepared
argon merge apply <plan-id>--disable-tools takes a comma-separated list. argon mcp --read-only offers only the branch list, diff and pin list tools. In Cursor, add the same flags to args.
On a project whose main follows a database you already run, an ordinary merge into main is refused, whoever asks for it. The agent can still open sandboxes, diff and prepare a plan. Writing that plan to the database is a person's CLI step, argon merge apply <plan-id> --write-back --approve <digest>, and is not offered over MCP, REST or the console. It has been tested on MongoDB 7.0 replica sets only: not on Atlas, with access control, across multi-member elections or on sharded sources.
Python
A sandbox for your agent run
The Python client calls your local API on port 1818. Keep the console running before trying this example.
Use Python 3.10+. This installs SDK 0.2.0 from PyPI.
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install "argon-agents==0.2.0"Save this as agent_run.py and run python agent_run.py. Each run creates a fresh sandbox.
import json
from argon_agents import ArgonClient
argon = ArgonClient("http://127.0.0.1:1818")
argon.get_or_create_project("agent-lab")
run = argon.create_sandbox("agent-lab", ttl_minutes=30)
db = run.pymongo_database()
db.create_collection(
"orders", changeStreamPreAndPostImages={"enabled": True}
)
db.orders.insert_one({"_id": "order-1", "price": 49})
db.orders.update_one({"_id": "order-1"}, {"$set": {"price": 44}})
print("Branch:", run.branch)
print(json.dumps(run.diff(), indent=2))
plan = argon.merge_preview("agent-lab", run.branch)
print("Review this plan:", plan["id"])
# Inspect the plan in the console before applying it.Expected: a branch name, an orders diff containing price 44, and a merge plan ID. The proposal does not change the parent branch unless you apply a reviewed merge. After 30 minutes the sandbox is eligible for cleanup on a successful sweep. Manage the agent process and its MongoDB credentials separately. See the local TTL experiment for what happens when the service stops or restarts.
Use it with LangGraph
Add the LangGraph extra to the same virtual environment:
python3 -m pip install "argon-agents[langgraph]==0.2.0"In an existing LangGraph application, replace its checkpointer when you compile the graph:
from argon_agents import ArgonClient, ArgonCheckpointSaver
argon = ArgonClient("http://127.0.0.1:1818")
argon.get_or_create_project("agent-memory")
saver = ArgonCheckpointSaver.from_sandbox(
argon, "agent-memory", ttl_minutes=30
)
graph = builder.compile(checkpointer=saver)
# Invoke your graph with a configurable thread_id as usual.The graph's checkpoints now live on that sandbox. LangGraph rewinds steps within a thread; Argon can fork the whole checkpoint store for another run. Read the adapter reference
REST API
Use your own language
HTTP manages projects and sandboxes; the returned MongoDB connection handles data reads and writes. Start the local console first.
Create this example project once:
curl --fail-with-body -sS http://127.0.0.1:1818/api/v1/projects \
-H 'Content-Type: application/json' \
-d '{"name":"rest-agent"}'Then create a sandbox for a run:
curl --fail-with-body -sS \
http://127.0.0.1:1818/api/v1/projects/rest-agent/sandboxes \
-H 'Content-Type: application/json' \
-d '{"ttl_minutes":30,"actor":"agent:rest-example"}'Expected: JSON with branch, connection_string and expires_at. Pass that connection string to your MongoDB driver. If the project already exists, skip the first request.
For a protected deployment, add -H "Authorization: Bearer $ARGON_API_TOKEN" to your requests.
Local by default
The console and API listen on 127.0.0.1 and, without a token, answer only requests addressed to localhost or a loopback address; list other hostnames in ARGON_ALLOWED_HOSTS. The wire proxy also listens on loopback unless you pass --allow-remote, and it does not authenticate clients. Set ARGON_API_TOKEN and use MongoDB authentication before exposing either one. Security policy and reporting.
Use a separate branch per agent run. See the operating limits for capture, retention and access controls.