argon

Argon — Git for MongoDB

Branch, time-travel, merge and undo your MongoDB. Any driver, real mongod, versioned history underneath. Built for AI agents.

Three ideas, thirty seconds:

1. A branch is a pointer, not a copy — created with a metadata write. Checkout separately materializes the data.
2. checkout turns a branch into a real MongoDB database — pymongo, mongoose, mongosh, indexes, aggregation, transactions: all real, and supported document writes become history while capture is healthy.
3. Review and recover changes — diff, merge, undo and pin states within the configured retention and capture guarantees.

Install

For npm, use Node.js 24 LTS with npm 11.16 or newer. The package-scoped approval allows the installer to download Argon's binary on npm 12.

brew install argon-lab/tap/argonctl      # macOS
npm install -g argonctl --allow-scripts=argonctl # cross-platform

# MongoDB must run as a replica set (one-node is fine):
docker run -d --name argon-mongo -p 127.0.0.1:27017:27017 mongo:7 --replSet rs0
docker exec argon-mongo mongosh --quiet --eval 'rs.initiate({_id:"rs0",members:[{_id:0,host:"localhost:27017"}]})'
argon doctor

Use a current supported MongoDB patch release in production. Source builds use Go 1.26.9 or newer, as declared in go.mod. Use a patched toolchain: Go 1.27.0–1.27.1 also contain the October 2026 standard-library vulnerabilities.

The flow

main ──branch──▶ experiment ──checkout──▶ mongodb://…  ← any driver
                                              │
                     ┌── argon diff ──────────┤  document history
                     ▼                        ▼
        merge (a data PR)          or   undo / discard / rewind

# 0 · Stop source writers and DDL for the import — or: argon projects create myapp
argon import database --uri mongodb://localhost:27017 --database myapp --project myapp --source-quiesced

# 1 · Branch — instant, no copy
argon branches create experiment -p myapp

# 2 · In terminal A, capture writes with a branch actor label
argon checkout -p myapp -b experiment      # prints a connection string
argon watch    -p myapp -b experiment --actor agent:experiment

# In terminal B, write through the printed URI. Then:

# 3 · Review and merge back — a data pull request
argon diff          -p myapp -b experiment
argon merge preview -p myapp -b experiment
argon merge apply <plan-id>

# …or rewind instead of merging
argon restore reset -p myapp -b main --time 2026-07-07T09:00:00Z --backup pre-incident

Prefer clicking? argon console serves a local web console (UI + REST API), supervises capture, reaps expired sandboxes every minute, and opens your browser. The console's MIT-licensed source is in web/; see the rebuild instructions. For a complete managed workflow, run the two-agent pinned dataset example.

What you get

	Command	In one line
Branching	argon branches create	a metadata write — instant, zero copy
Real databases	argon checkout / argon proxy	any driver, real mongod; proxy serves stable mongodb://host/<project>~<branch> URIs
Write capture	argon watch	exact change-stream images → history, one actor label per branch
Time travel	argon time-travel query	query captured document states at retained LSNs; restore/pin also accept timestamps
Undo	argon undo --actor <a>	revert a range or actor label; append-only, conflict-aware
Restore	argon restore preview/reset/branch	rewind a released branch or fork retained history
Data PRs	argon merge preview/apply	three-way merges as reviewable plans; conflicts never silent
Sandboxes	argon sandbox create --ttl 1h	fork + checkout + TTL in one step — disposable agent workspaces
Dataset pins	argon pin create / pin sandbox	named captured states protected from GC and resets while the pin exists
Web console	argon console	local UI + REST API in one command

Data history covers document inserts, updates, replacements and deletes. Collection drop/rename produces degraded capture; indexes and collection options are not versioned. Native writes are asynchronous; control operations drain capture. Stop writers before release. Existing pins protect their referenced states, while GC can expire audit and undo history. See operations for recovery and credentials.

Storage retention uses snapshots + retention-window GC to keep state plus a window of history, not every write forever. Details and the consistency model, stated honestly: ARCHITECTURE.md.

For AI agents

claude mcp add argon -- argon mcp        # 13 tools: sandbox, diff, merge, undo, pins
# Install the published Python SDK and LangGraph adapter.
python3 -m pip install 'argon-agents[langgraph]==0.2.0'

Start argon console --no-browser in another terminal, then:

from argon_agents import ArgonClient, ArgonCheckpointSaver

argon = ArgonClient("http://127.0.0.1:1818")
argon.get_or_create_project("myapp")
saver = ArgonCheckpointSaver.from_sandbox(argon, "myapp")
# Compile and run your LangGraph graph with checkpointer=saver, then review:
plan = argon.merge_preview("myapp", saver.sandbox.branch)
print(plan)
# After reviewing this exact plan, apply it explicitly:
# argon.merge_apply(plan["id"])
# Or reject the run: saver.discard()

argon.create_pin("myapp", "eval-v1")                        # pin the dataset once
run = argon.sandbox_from_pin("myapp", "eval-v1")            # identical state, every eval run

saver.merge() is a convenience call that previews and applies immediately; use the separate calls above when approval is required. Pins protect captured document state while they exist; keep independent backups.

The full agent workflow: docs/AGENTS.md.

Documentation

Quick start	install → first merge, step by step
CLI reference	every command
Agents	sandboxes, pins, MCP, REST API, argon-agents, proxy
Architecture	how it works and what it guarantees
Operations	deployment, chunk stores (S3/FS), GC, v1→v2 migration
Performance	every number lives in the reproducible benchmarks — none here, by policy

Community

Issues · Discussions · Contributing · argonlabs.tech · Blog

---