Share files across machines

A workspace can be mounted by any number of machines at the same time. There is no limit and nothing extra to configure; the only operation is the mount command itself, repeated on every machine that needs the workspace:

artifacts mount my-workspace /mnt/work

Every machine sees the same files, and a write on one machine is readable on the others within tens of milliseconds.

When you need this

• You read results while the agent is still working. The agent writes in its sandbox; the editor on your laptop, or a reviewer agent elsewhere, reads the same paths live.
• You fan one task out to many workers. N machines mount the same workspace and each writes its own subpath.
• Producers and consumers run on different machines. A long-running ingestion daemon writes while short-lived analyzers read.

If only one machine has the workspace mounted at a time, skip this page: mount, work, unmount, mount elsewhere later. The files carry over by default; nothing here needs configuring.

What each machine sees

• The directory tree is exact and immediate. Create, rename, or delete a file on host A, and a listing on host B reflects it right away. There is no window where two machines disagree about which files exist.
• File contents follow within tens of milliseconds. Each mount caches data it has read; when another machine changes a file, the next read returns the new bytes.
• Simultaneous writes to the same file don't merge. If two machines write the same file at the same moment, the result interleaves in 4 MB blocks instead of combining cleanly. Give each writer its own file (patterns below). Exact guarantees: Concurrent writes.
• File locks work across machines. flock held on host A blocks host B, the same way it blocks another process on the same machine. Details: File locks and coordination.

Patterns that stay collision-free

• One file per writer. Each writer claims its own path, e.g. outputs/agent-7/result.json. Nothing needs to coordinate because nothing collides.
• Read-only fan-out. One machine writes; every other machine mounts with --read-only. Reads never conflict.
• Write hidden, rename to publish. Write to outputs/.tmp.result.json, then mv it to outputs/result.json. The rename is atomic across machines, so a reader sees the old file or the new one, never half of either.

One thing to watch for

• A result made of several files can be seen half-published. Files land one by one, so a reader on another machine can list a directory after the first file arrived but before the last. If readers need all-or-nothing, write everything into a hidden directory first and rename it into place as the final step; Concurrent writes shows the recipe.