Skip to main content
Machine Files is experimental: its config and behavior may still change.
When an agent’s commands run on a machine (a container, a sandbox, a server over ssh), the files those programs read and write live on the machine. A machine mount shows a folder of the machine in the workspace, so a file the agent writes from Mirage’s shell is the file the machine’s programs read, and a file a program leaves behind is one the agent can open. With the machine’s /tmp mounted at /tmp:
Mirage’s cat writes /tmp/fix.py on the machine, and the machine’s python3 reads it there. Nothing is copied or synced: the file lives on the machine.

Set Up

Mount "@<machine>" at a path to show the folder that machine has at the same path. Here /tmp is the /tmp of machine sandbox:
workspace.yaml
Any folder works the same way: /home/user/project: "@sandbox" shows the project the machine holds there. For a folder at another path, see Mount Block. The name must be one under machines:. A typo such as /tmp: "@sandbx" stops the workspace from starting and lists the names it knows:
A workspace with a machine mounts /tmp and /dev/shm this way by itself, unless another mount claims them:

Mount Block

"@sandbox" is short for a machine mount block. Write the block out for what the short form cannot say: a folder at another path (root), some machines but not all (machines), or where a new file lands (default_machine). This shows machine sandbox’s /home/user/project at /project:
workspace.yaml
"@sandbox" at /tmp is the same as machines: [sandbox] with root: /tmp.

Where a Command Runs

A command whose paths all sit on one machine runs on the machine itself, in one go, and prints exactly what the machine’s own tools print. A command that also reaches the rest of the workspace runs in Mirage, which still reads and writes each machine file on its machine. With one machine, its /tmp mounted, and a ram mount at /data, whose files live in Mirage and not on the machine: A restricted or read-only mount, a coded file policy and a program the machine lacks keep a command in Mirage too. /dev is Mirage’s (/dev/null, /dev/stdin); only /dev/shm is the machine’s.

Several Machines

With several machines, the /tmp Mirage mounts by itself shows all of their /tmp files together. /tmp: "@gpu" shows machine gpu’s only. A name on two machines is refused as ambiguous unless the command’s program runs on one of them.

Behavior

  • Caching: none. Programs change these files behind Mirage’s back, so every read and listing asks the machine.
  • Snapshots: a snapshot keeps the mount’s config; the files stay on the machines.
  • Owners: stat and listings report the machine’s own owners and modes; chmod, chown and touch apply on the machine.
  • Tools: the machine needs GNU find (for -printf), cat, head, tail, dd and the coreutils sums; a stock Debian or Ubuntu image has them.
  • Daytona: its exec takes no input, so a write to its files is refused (Operation not supported), and a command that needs piped input stays with Mirage.
  • Serving: with mount_type: ssh, a path the machine holds itself is never served back to it; any other machine mount is served like any mount.

SDK Guides

Python

Every config field and the VFS.md.

TypeScript

Every config field and the VFS.md.