Skip to content
Back to search

argon

Git for MongoDB — branch, time-travel, and undo your data. Built for AI agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/argon-lab/argon with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/argon-lab/argon'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/argon-lab--argon/badge.svg)](/listings/argon-lab--argon)

HTML

<a href="/listings/argon-lab--argon"><img src="/api/listings/argon-lab--argon/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 284 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Argon — MongoDB sandboxes for AI agents
  2. <p align="center">
  3. <a href="https://argonlabs.tech">
  4. <img src=".github/assets/hero.png" alt="Argon — MongoDB sandboxes for AI agents. Git for MongoDB underneath: branch, diff, merge, undo." width="100%">
  5. </a>
  6. </p>
  7. [![Build Status](https://github.com/argon-lab/argon/actions/workflows/ci.yml/badge.svg)](https://github.com/argon-lab/argon/actions/workflows/ci.yml)
  8. [![Go Report](https://goreportcard.com/badge/github.com/argon-lab/argon)](https://goreportcard.com/report/github.com/argon-lab/argon)
  9. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  10. [![Homebrew](https://img.shields.io/badge/Homebrew-argonctl-orange?logo=homebrew)](https://github.com/argon-lab/homebrew-tap)
  11. [![npm](https://img.shields.io/npm/v/argonctl?logo=npm&label=npm)](https://www.npmjs.com/package/argonctl)
  12. [![PyPI](https://img.shields.io/pypi/v/argon-agents?logo=pypi&label=argon--agents)](https://pypi.org/project/argon-agents/)
  13. [![mcp.market](https://mcp.market/badge/argon-lab-argon.svg)](https://mcp.market/server/argon-lab-argon)
  14. **Give every agent run its own real MongoDB database, forked from your data.
  15. Review what it changed, merge what you want, discard the rest. Git for MongoDB
  16. underneath: branch, diff, merge, time travel and undo. Any driver, real mongod.**
  17. Three ideas, thirty seconds:
  18. 1. **A sandbox is a real MongoDB database** — forked from a branch or a pinned
  19. dataset, checked out and given a TTL in one command. pymongo, mongoose,
  20. mongosh, indexes, aggregation, transactions: all real.
  21. 2. **What the agent wrote is a diff** — supported document writes become
  22. history while capture is healthy, so a run can be reviewed, merged as a data
  23. pull request, undone or thrown away. Your source data is untouched until you
  24. merge.
  25. 3. **Underneath, it is Git for MongoDB** — a branch is a pointer created with a
  26. metadata write; checkout separately materializes the data. Diff, merge, undo
  27. and pins work within the configured retention and capture guarantees. The
  28. commands are [side by side with Git](#git-for-mongodb) below.
  29. ## Install
  30. For npm, use Node.js 24 LTS with npm 11.16 or newer. The package-scoped
  31. approval allows the installer to download Argon's binary on npm 12.
  32. ```bash
  33. brew install argon-lab/tap/argonctl # macOS or Linux, builds from source
  34. npm install -g argonctl --allow-scripts=argonctl # cross-platform
  35. # MongoDB must run as a replica set (one-node is fine):
  36. docker run -d --name argon-mongo -p 127.0.0.1:27017:27017 mongo:7 --replSet rs0
  37. docker exec argon-mongo mongosh --quiet --eval 'rs.initiate({_id:"rs0",members:[{_id:0,host:"localhost:27017"}]})'
  38. argon doctor
  39. ```
  40. Use a current supported MongoDB patch release in production. Source builds use
  41. Go 1.26.11 or newer, as declared in `go.mod`. Use a patched toolchain: on the
  42. Go 1.27 line that means 1.27.4 or newer, which carry the same standard-library fixes.
  43. ## The flow
  44. ```
  45. your data ──sandbox──▶ mongodb://… ← the agent, any driver
  46. │
  47. argon diff ──────┤ what the run changed
  48. ▼ ▼
  49. merge (a data PR) or discard / undo
  50. ```
  51. ```bash
  52. # 0 · Bring your data in once, from a database nobody is writing to — or: argon projects create myapp
  53. # (a database that is in use: see "A database that is in use" below)
  54. argon import database --uri mongodb://localhost:27017 --database myapp --project myapp --source-quiesced
  55. # 1 · In terminal A, a sandbox: fork + checkout + TTL + capture in one command.
  56. # Prints its name and a connection string, then keeps capturing until Ctrl-C
  57. argon sandbox create -p myapp --ttl 1h --watch --actor agent:run-1
  58. # In terminal B, point the agent at the printed URI. Then:
  59. # 2 · Review, then adopt the run — a data pull request
  60. argon diff -p myapp -b <sandbox>
  61. argon merge preview -p myapp -b <sandbox>
  62. argon merge apply <plan-id>
  63. # …or throw the run away
  64. argon sandbox discard -p myapp -b <sandbox>
  65. ```
  66. Through the MCP server or `argon console`, capture and expiry are managed for
  67. you: nothing stays in the foreground, and expired sandboxes are swept every
  68. minute. `--watch` needs 2.3.0 or newer; on older versions run
  69. `argon watch -p myapp -b <sandbox> --actor agent:run-1` after creating the sandbox.
  70. Long-lived branches work the same way with `argon branches create` and
  71. `argon checkout`, and `argon restore reset` rewinds a branch to an earlier time.
  72. ### A database that is in use
  73. Online import, the `argon source` commands, and write-back are experimental
  74. and off by default. They have known open issues. Set
  75. `ARGON_EXPERIMENTAL_SOURCE=1` to enable them after reading
  76. [the operations guide](docs/OPERATIONS.md#following-a-source-database).
  77. Releases after 2.5.0 can import a replica-set database without stopping its
  78. writers, keep the project's `main` following it, and write a reviewed plan
  79. back to it:
  80. ```bash
  81. export ARGON_EXPERIMENTAL_SOURCE=1
  82. export ARGON_SOURCE_URI="mongodb://…" # read per command, never stored
  83. argon import preview --database myapp --online
  84. argon import database --database myapp --project myapp --online
  85. argon source follow -p myapp # main tracks the source; leave it running
  86. argon sandbox create -p myapp --ttl 1h --watch --actor agent:run-1
  87. argon merge preview -p myapp -b <sandbox>
  88. argon merge apply <plan-id> --write-back # one transaction on the source
  89. ```
  90. The import copies ordinary collections at one cluster time, which it prints.
  91. Add `--dry-run` to the import command to check the source and its change stream
  92. and see the estimated copy without writing anything.
  93. Following ignores changes to views. `--write-back`
  94. checks every document against the plan's before-image and aborts the
  95. transaction if one has changed. Write-back and `--enable-source-images`
  96. require importing with a user allowed to run `replSetGetConfig`, such as one
  97. with the `clusterMonitor` role. Use `argon source status` to see which identity
  98. check applies. The MCP server and REST API do not offer write-back. Argon
  99. never drops, renames or rewrites a source database. See
  100. [the operations guide](docs/OPERATIONS.md#following-a-source-database).
  101. If a plan stays `writing_back`, check the affected documents on the source,
  102. let following catch up, and run `argon merge preview` again for the sandbox.
  103. Each project can run one follower or resync at a time. `argon source status`
  104. shows the lease owner's host, process ID and last heartbeat. Run
  105. `argon source follow --auto-resync` to complete an unfinished resync or
  106. repair a gap in the source stream before continuing to follow.
  107. If an older Argon process checked out a followed `main`, status reports
  108. it as degraded. Upgrade the older processes, stop writes to the checkout,
  109. release it with `argon release -p myapp -b main`, then run
  110. `argon source resync -p myapp`.
  111. When requested, `source follow --enable-source-images` alters existing
  112. source collections after the saved position is followable. An error after
  113. the change lists the affected collections.
  114. Prefer clicking? `argon console` serves a local web console (UI + REST API),
  115. supervises capture, reaps expired sandboxes every minute, and opens your browser.
  116. The console's MIT-licensed source is in [web/](web/README.md); see the
  117. [rebuild instructions](CONTRIBUTING.md#console-source-and-reproducible-assets).
  118. For a complete managed workflow, run [the two-agent pinned dataset example](examples/pinned_agents.py).
  119. ## For AI agents
  120. ```bash
  121. claude mcp add argon -- argon mcp # 13 tools: sandbox, diff, merge, undo, pins
  122. # Install the published Python SDK and LangGraph adapter.
  123. python3 -m pip install 'argon-agents[langgraph]==0.2.0'
  124. ```
  125. Start `argon console --no-browser` in another terminal, then:
  126. ```python
  127. from argon_agents import ArgonClient, ArgonCheckpointSaver
  128. argon = ArgonClient("http://127.0.0.1:1818")
  129. argon.get_or_create_project("myapp")
  130. saver = ArgonCheckpointSaver.from_sandbox(argon, "myapp")
  131. # Compile and run your LangGraph graph with checkpointer=saver, then review:
  132. plan = argon.merge_preview("myapp", saver.sandbox.branch)
  133. print(plan)
  134. # After reviewing this exact plan, apply it explicitly:
  135. # argon.merge_apply(plan["id"])
  136. # Or reject the run: saver.discard()
  137. argon.create_pin("myapp", "eval-v1") # pin the dataset once
  138. run = argon.sandbox_from_pin("myapp", "eval-v1") # identical state, every eval run
  139. ```
  140. `saver.merge()` is a convenience call that previews and applies immediately;
  141. use the separate calls above when approval is required. Pins protect captured
  142. document state while they exist; keep independent backups.
  143. To keep a person in the loop, withhold tools from the MCP server:
  144. `argon mcp --disable-tools argon_merge_apply` leaves applying a merge plan to
  145. `argon merge apply <plan-id>`, and `argon mcp --read-only` offers only the
  146. tools that inspect state.
  147. The full agent workflow: [docs/AGENTS.md](docs/AGENTS.md).
  148. ## Git for MongoDB
  149. Underneath the sandbox, Argon does for MongoDB documents what Git does for
  150. files. Side by side:
  151. | In Git | In Argon | What it does to your data |
  152. |---|---|---|
  153. | `git branch` | `argon branches create` | adds a pointer into shared history; no documents are copied |
  154. | `git worktree add` | `argon sandbox create` | gives a new branch its own working copy: a real MongoDB database, with a TTL |
  155. | `git diff` | `argon diff` | lists the documents a branch would add, change or remove |
  156. | `git merge` | `argon merge preview`, then `argon merge apply` | saves the change as a plan to review, then applies exactly that plan |
  157. | `git checkout <commit>` | `argon time-travel query` | reads the data as it was at an earlier position in retained history |
  158. | `git revert` | `argon undo` | reverses earlier writes with a new change; history is not rewritten |
  159. | `git tag` | `argon pin create` | names one fixed state and protects its history while the pin exists |
  160. Where it differs from Git: there is no commit step, because a running capture
  161. process records each document change. A merge goes from a branch into its
  162. parent and compares whole documents. Checking out a branch copies its data, so
  163. it takes time and storage that depend on the dataset. Documents are versioned;
  164. indexes and collection options are not. History older than the retention
  165. window can be reclaimed unless a pin protects it.
  166. ## What you get
  167. | | Command | In one line |
  168. |---|---|---|
  169. | **Sandboxes** | `argon sandbox create --ttl 1h` | fork + checkout + TTL in one step — disposable agent workspaces |
  170. | **Dataset pins** | `argon pin create` / `pin sandbox` | named captured states protected from GC and resets while the pin exists |
  171. | **Data PRs** | `argon merge preview/apply` | three-way merges as reviewable plans; conflicts never silent |
  172. | **Undo** | `argon undo --actor <a>` | revert a range or actor label; append-only, conflict-aware |
  173. | **Real databases** | `argon checkout` / `argon proxy` | any driver, real mongod; proxy serves stable `mongodb://host/<project>~<branch>` URIs |
  174. | **Write capture** | `argon watch` | exact change-stream images → history, one actor label per branch |
  175. | **Branching** | `argon branches create` | a metadata write — instant, zero copy |
  176. | **Time travel** | `argon time-travel query` | query captured document states at retained LSNs; restore/pin also accept timestamps |
  177. | **Restore** | `argon restore preview/reset/branch` | rewind a released branch or fork retained history |
  178. | **Web console** | `argon console` | local UI + REST API in one command |
  179. Data history covers document inserts, updates, replacements and deletes. Collection
  180. drop/rename produces degraded capture; indexes and collection options are not
  181. versioned. Native writes are asynchronous; control operations drain capture.
  182. Stop writers before release. Existing pins protect their referenced states, while GC can expire audit
  183. and undo history. See [operations](docs/OPERATIONS.md) for recovery and credentials.
  184. Two things to know before handing a sandbox to an agent. A collection the agent
  185. creates is captured exactly while capture is running, or when it is next
  186. synchronized within MongoDB's snapshot history (five minutes by default); the
  187. one exception is a document that is updated and then changed again inside one
  188. transaction on a collection created moments earlier. Before 2.3.1 such a collection needed
  189. `argon collections prepare` first. And a sandbox is a full physical copy with
  190. capture ready, so creating one takes longer as the data grows: the
  191. [benchmarks](https://github.com/argon-lab/benchmarks) measure it as
  192. `sandbox_capture_ready_ms`.
  193. Storage retention uses snapshots + retention-window GC to keep state plus a
  194. window of history, not every write forever. Details and the consistency
  195. model, stated honestly: [ARCHITECTURE.md](docs/ARCHITECTURE.md).
  196. ## Documentation
  197. | | |
  198. |---|---|
  199. | [Quick start](docs/QUICK_START.md) | install → first merge, step by step |
  200. | [CLI reference](docs/CLI.md) | every command |
  201. | [Agents](docs/AGENTS.md) | sandboxes, pins, MCP, REST API, argon-agents, proxy |
  202. | [Architecture](docs/ARCHITECTURE.md) | how it works and what it guarantees |
  203. | [Operations](docs/OPERATIONS.md) | deployment, chunk stores (S3/FS), GC, v1→v2 migration |
  204. | [Performance](docs/PERFORMANCE.md) | every number lives in the [reproducible benchmarks](https://github.com/argon-lab/benchmarks) — none here, by policy |
  205. ## Community
  206. [Issues](https://github.com/argon-lab/argon/issues) ·
  207. [Discussions](https://github.com/argon-lab/argon/discussions) ·
  208. [Contributing](CONTRIBUTING.md) ·
  209. [argonlabs.tech](https://argonlabs.tech) · [Blog](https://argonlabs.tech/blog)
  210. ## Contributors
  211. Thank you to everyone who has made Argon better.
  212. <a href="https://argonlabs.tech/about#contributors">
  213. <img src="https://argonlabs.tech/contributors.svg" alt="Argon contributors" height="64">
  214. </a>
  215. What each person shipped, and the release it shipped in, is listed at
  216. [argonlabs.tech/about#contributors](https://argonlabs.tech/about#contributors).
  217. Every release also names its new contributors in the
  218. [release notes](https://github.com/argon-lab/argon/releases).
  219. New here? Start with a
  220. [good first issue](https://github.com/argon-lab/argon/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
  221. and the [first-contribution guide](CONTRIBUTING.md#your-first-contribution).
  222. ---
  223. <div align="center">
  224. **Give your MongoDB a time machine. Branch without fear.** ⭐
  225. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.