Branch a Live MongoDB Database and Write Reviewed Changes Back
Import a MongoDB database while it is being written, follow it, let an agent work in a sandbox, review the diff, and write the approved change back in one transaction. A full run on Argon 2.8.0, with its limits.
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.
Argon gives AI agents and developers MongoDB sandboxes: a copy of your data to work in, a diff to read, and a merge you approve. Until now the copy started from an import that needed your writers paused, and the approved merge landed in Argon, not in your database.
Two releases changed that. From Argon 2.7.0 you can import a MongoDB database while it is being written and keep following it. From Argon 2.8.0 you can write a reviewed change back to that database. This post runs the whole path on a database that never stops taking writes, shows what is refused, and lists the limits. It is for teams that already run MongoDB and want a safe place for an agent or a developer to try a change against current data.
running MongoDB ──online import──▶ main ──fork──▶ sandbox ──▶ diff ──▶ reviewed plan
▲ (follows the source) │
└──────────────── write-back, one transaction, with approval ──────────┘What we ran
- Argon 2.8.0, the binary that
npm install -g argonctl@2.8.0installs. - Two MongoDB 7.0.45 deployments, each a one-member replica set without access control, in containers on one laptop. One holds the source database
shop. The other holds Argon's metadata and its sandboxes. - The source has 50,000 orders and 200 customers. A thread plays the application for the whole run: it inserts a new order or updates an existing one, sleeps 5 ms, and repeats. It made 2,498 writes in all. We paused it twice, only to compare the source with a sandbox while the source stood still.
This is a walkthrough with a transcript, not a benchmark. The few timings below are single observations. Every command and its output is in the transcript, and the report has the script that produced it.
Step 1: import while the application writes
export ARGON_SOURCE_URI="mongodb://…" # used per command, never stored
argon import database --database shop --project shop --online --yes Documents Imported: 50.3K
Duration: 868.050209ms
Consistent: LSN 50348 is the source at cluster time Timestamp(1795093601, 130)
LSNs below 50348 are the copy in progress, not states the source was in.
main follows database 'shop'; keep it current with: argon source follow -p <project>The application made 144 writes while that command ran. A cursor reads different documents at different moments, so a plain copy of a database that is being written is not a state the database was ever in. The online import takes the source's cluster time, copies the collections, then replays the source's change stream until it has passed everything the copy read. What it publishes is the source at one cluster time, and it tells you which.
The source has to be a replica set. A sharded cluster behind mongos is refused. Indexes, validators and collection options are not copied.
Step 2: follow
argon source follow -p shop
argon source status -p shopProject shop: main follows database "shop"
Source: mongodb://argon-wbpost-source:27017/shop (replica set src0)
Identity: replica-set ID
Health: healthy (exact)
Checkpoint: The branch head is a verified exact source checkpoint.
Consistent: LSN 51545 is the source at Timestamp(1795093610, 45)
Last change: 2026-11-19T13:06:50Z (stored 8 ms after it happened)argon source follow is a process you keep running. It reads the source's change stream and applies it to main, a whole cluster time at a time, so a transaction is never half visible. If it stops, it resumes from its saved position. It reads the source and writes nothing to it.
With the application writing, the last change was stored 8 ms after it happened. On an idle source it is slower: when we paused the application, its newest write was stored 12.6 seconds later. The last change waits for the next entry in MongoDB's oplog, and an idle MongoDB writes one every ten seconds. The operations guide gives that wait as ten to twenty seconds.
Step 3: a sandbox from current data
argon sandbox create -p shop --name agent-1 --watch --actor agent-1Sandbox "agent-1" forked from main at LSN 51550.
Expires: 2026-11-19T14:07:04Z
Connection string:
mongodb://argon-wbpost-meta:27017/argon_br_6afef4784065642e523e46b5?replicaSet=rs0
Capturing writes (Ctrl-C to stop)...A sandbox is a real MongoDB database on Argon's deployment, not on the source. The agent gets its connection string and nothing else. It is a full physical copy, so it takes longer and uses more storage as the data grows.
We checked that a sandbox holds what the source holds. With the application paused, a sandbox forked from main had the same 50,608 orders and 200 customers as the source, with the same values in every document.
The bytes were not the same. In 50,547 of the 50,608 orders the fields were in a different order in the sandbox than on the source. This matters in step 5.
Step 4: the agent works, and you read the diff
Through the sandbox's connection string, our stand-in agent marked one order as refunded, inserted a refund order and deleted another order.
$ argon diff -p shop -b agent-1
Merging agent-1 → main
delete orders/order-000017
put orders/order-000042
put orders/order-000042-refund
3 change(s), 0 conflict(s)argon merge preview -p shop -b agent-1 -o json saves that as a plan and prints it in full: for each change the document as it will be written, the document as it was at review, and at the end a digest of the whole plan.
"id": "6afef478f3411167fd812ec4",
"followed_database": "shop",
"approval_digest": "3bcc31356109437f4a4f02ad1826aa05882e087f8ce2afe3accaf2f4294a3da8"The digest is bound to the plan's contents. It appears only in the CLI's JSON output, next to the images it covers, so the way to get it is to open the thing you are approving.
Step 5: write it back
$ argon merge apply 6afef478f3411167fd812ec4 --write-back --approve 3bcc31356109437f4a4f02ad1826aa05882e087f8ce2afe3accaf2f4294a3da8
Written to the source database: 3 change(s) in one transaction.
main shows them once following has read them from the source (argon source status).Inside that one transaction on the source, Argon:
- compares each document it is about to replace or delete, byte for byte, with the before-image saved in the plan;
- requires that each key it is about to insert is absent;
- after all writes and before commit, reads every document back and compares it byte for byte with the approved image, or confirms the deletion.
One mismatch rolls back the batch. main is not written by the write-back. It receives the change the way it receives every other change to the source, through following.
On the source afterwards, the order was refunded, the refund order existed and the deleted order was gone. At the end of the run the source held 51,060 orders: the 50,000 it started with, 1,060 the application inserted, one the plan inserted, less one the plan deleted. A new sandbox forked from main again had the same values as the source.
The replaced order came back with its fields reordered. Write-back writes the document as the sandbox held it, and step 3 showed that a sandbox does not keep the source's field order.
[field order of order-000042 on the source before: _id, status, customer, total_cents, items, placed_at, touches]
[field order of order-000042 on the source after: _id, touches, customer, items, placed_at, status, total_cents, refund_cents]The values are what was approved, and the approved image in the plan shows this order, so it is visible at review. It reached inside the items array too. Most applications never notice field order. Some do: MongoDB's equality match on a whole embedded document depends on it. Only documents a plan replaces are affected. We count this as a defect, and a fix is in progress.
What is refused
We tried five things that should not work. The first four came before the write-back above, and after them the three documents on the source were as they had been.
Write-back without an approval:
$ argon merge apply 6afef478f3411167fd812ec4 --write-back
Error: --write-back requires --approve with a 64-character lowercase hex digest; run argon merge list -p <project> --output json and pass that plan's approval_digest with --approve. For an older plan, preview again with this versionA digest that is not this plan's:
Error: approval digest does not match the saved plan; run argon merge list -p <project> --output json and pass that plan's approval_digest with --approve. For an older plan, preview again with this versionThe right digest, pointed at a different deployment:
Error: write-back failed: the connection leads to a different deployment than the one this project follows (mongodb://argon-wbpost-source:27017/shop)An ordinary merge into main, which would leave it holding documents its source does not:
Error: apply failed: merge apply refused: branch main follows the external database "shop" and only changes when that database does; write to a sandbox forked from it, inspect the lossless images with `argon merge list -p <project> --output json` and write the plan to the source with `argon merge apply <plan> --write-back --approve <digest>`, or stop following with `argon source detach`The same plan a second time:
Error: merge plan is applied, not pendingWhen someone else changed the document first
A review takes time, and production does not wait. In a second sandbox the agent cancelled two orders, and we previewed the plan. Then, directly on the source, we marked one of the two as shipped. Then we applied the plan with its correct digest.
Error: write-back failed: write-back aborted, nothing was written: document orders/order-000051 in the source database differs from the state this plan was reviewed against. Let following catch up and run preview againNeither order was written. The one nobody else had touched still said paid on the source, and the plan stayed pending. Once following had stored the concurrent edit, a fresh preview said what a reviewer needs to know:
$ argon merge preview -p shop -b agent-2
Merging agent-2 → main
put orders/order-000050
CONFLICT orders/order-000051 (both sides changed since the fork)
1 change(s), 1 conflict(s)What it took to switch write-back on
Write-back first shipped switched off, behind an experimental flag, and was switched on in 2.8.0 after its checks were tightened. The 2.8.0 changelog lists what changed. Two examples of what the byte-for-byte rule caught:
- A timestamp MongoDB rewrites. MongoDB replaces a top-level BSON timestamp of zero with the current time when a document is inserted or replaced. A document carrying one can never read back as approved, so such a plan is refused before anything is claimed.
- A document whose
_idis not first. MongoDB stores_idas the first field whatever order it was sent in. Plans now save their images with_idfirst, and an older plan with a field ahead of it has to be previewed again.
What Argon does to your source
Importing, following and resync read the source. The only writes Argon makes to it are write-back transactions and, if you ask for it by name, --enable-source-images. Argon stores which deployment and database a project follows, not how to log in: every command that reaches the source takes the connection string again and checks it against the replica-set ID recorded at import.
Reading and following need find and changeStream on the database. Write-back also needs readWrite, and the import has to be made by a user allowed to run replSetGetConfig, so that the replica-set ID is recorded.
Limits
- Tested on MongoDB 7.0 replica sets only. Write-back has not been tested on Atlas, on deployments with access control, through an election in a multi-member set, on sharded sources, or on other MongoDB versions. Our run used one-member replica sets without access control.
- Field order. A document replaced by a write-back gets the field order it had in the sandbox, as shown above.
- Two options are still experimental.
--auto-resyncand--enable-source-imagesare off by default and needARGON_EXPERIMENTAL_SOURCE=1. - Plans saved by 2.7.0 need a fresh preview before they can be written back.
- The CLI only. The REST API, the console and the MCP server do not offer write-back.
- One plan, one 16 MiB document. A larger change has to be split into smaller plans.
- A sandbox is a full copy, and a new sandbox starts from where following has got to, which on an idle source can be ten to twenty seconds behind.
- Undo is another write-back.
argon undodoes not apply to a branch that follows a source. - A known limitation in 2.8.0. If a collection on a followed branch used the deprecated BSON binary subtype 2 for both an empty
_idand one of four zero bytes, a read at an old position can omit a row after history written by 2.7.0 has been garbage-collected. The changelog has the repair.
The operations guide has the full contract, including what happens when the outcome of a commit is unknown.
Try it
npm install -g argonctl@2.8.0
export MONGODB_URI="mongodb://…" # Argon's own replica set
export ARGON_SOURCE_URI="mongodb://…" # used per command, never stored
argon import preview --database myapp --online
argon import database --database myapp --project myapp --online --yes
argon source follow -p myapp # keep main current from here on
argon sandbox create -p myapp --watch
argon merge preview -p myapp -b <sandbox> --output json
argon merge apply <plan-id> --write-back --approve <approval_digest>Start with a copy of production, or a staging database, and read the limits first. To repeat our run on your machine, the script is in the report.
Frequently asked questions
- Can Argon branch a MongoDB database that is in use?
- Yes, from Argon 2.7.0. argon import database --online imports a replica-set database while applications keep writing to it, and argon source follow keeps Argon's main branch current from the source's change stream. Sandboxes are forked from that branch. The source has to be a replica set; a sharded cluster behind mongos is refused and a standalone has no change stream.
- Does the application have to stop writing during the import?
- No. The import copies the collections and then replays the source's change stream until it has passed everything the copy read, and reports the cluster time at which the result equals the source. In our run an application thread made 144 writes during the import.
- How does Argon write a reviewed change back to the source database?
- From Argon 2.8.0, argon merge apply <plan> --write-back --approve <digest> writes a saved plan to the source in one transaction. Every replacement and delete is compared byte for byte with the before-image saved at review, every insert requires an absent key, and each written document is read back before commit. One mismatch aborts the whole batch.
- What happens if someone changes a document after the plan was reviewed?
- The write-back aborts and writes nothing. In our run a plan covered two orders, one of them was edited on the source after the review, and neither was written. A fresh preview after following caught up showed one change and one conflict.
- Does Argon write anything else to the source database?
- No. Importing and following only read. The only writes Argon makes to a source are write-back transactions and, if you ask for it by name, the experimental --enable-source-images option.
- What are the limits of write-back in Argon 2.8.0?
- It has been tested on MongoDB 7.0 replica sets only, not on Atlas, deployments with access control, multi-member elections or sharded sources. A document replaced by a write-back gets the field order it had in the sandbox, which can differ from the order it had on the source. Plans saved by 2.7.0 need a fresh preview. The REST API, the console and the MCP server do not offer write-back.