Guides

Persistent workspaces

Use encrypted volumes, copy workflows, snapshots, and cleanup policies for stateful sandboxes.

Persistent state is useful for agents, browser sessions, caches, databases, and long-running services. It is also where sensitive data accumulates. Choose the smallest state mechanism that fits the workflow, and make the retention policy explicit before the sandbox starts.

Pick a state mechanism

Need	Use	Security posture
One input file or result file	`mvmctl machine cp` or `mvmctl machine fs`	Narrowest boundary; preferred for generated-code tasks.
Read-only fixtures	`mvmctl run --mount ...:ro`	Host data is exposed but not writable by the guest.
Local dev edits	`mvmctl machine cp` or managed volume	Explicit copy or encrypted persistent state; no writable transient host share.
Stateful app data	managed encrypted volume	Encrypted at rest when locked; plaintext exists while unlocked.
Fast retry or recovery	snapshot or cold mode	Can contain memory, files, processes, prompts, and credentials.

Do not use a snapshot when a narrow output file is enough. Do not use a writable host share when a managed volume is enough.

Managed encrypted volume

Create a managed local volume:

mvmctl machine volume create agent-cache

Managed volumes are locked by default. Unlock before mounting:

mvmctl machine volume unlock agent-cache

Mount the unlocked volume into a running sandbox:

mvmctl machine volume mount agent-sandbox \
  --volume agent-cache \
  --guest /cache \
  --rw

List mounts:

mvmctl machine volume ls agent-sandbox

Unmount and lock when the workflow is done:

mvmctl machine volume unmount agent-sandbox /cache
mvmctl machine volume lock agent-cache

Security rules:

volume mount refuses a managed volume while it is locked;
volume unlock creates plaintext state that must be treated as sensitive;
volume lock reseals the volume and removes plaintext after use;
keep volume names scoped to the workflow or project;
do not mount the same writable volume into unrelated sandboxes unless sharing state is the intent.

Durable tenant volumes through mvmd

Use remote mode when mvmd owns the tenant, storage provider, encryption keys, quota, and attachment policy. Configure the authenticated client without putting the bearer token on the command line:

export MVM_GATEWAY_URL=https://mvmd.example.com
export MVM_TENANT_ID=tenant-acme
read -rsp "mvmd bearer token: " MVM_GATEWAY_TOKEN
export MVM_GATEWAY_TOKEN

The client refuses cleartext HTTP except for a loopback sidecar. Provider credentials never enter mvmctl; mvmd resolves them from the registered StorageBucket.

Create and list durable volumes:

mvmctl machine volume create database --size 20G --remote --bucket bucket-primary
mvmctl machine volume catalog --remote --json

The API allocates whole GiB, so smaller human-readable sizes round up to one GiB. Use the returned volume ID for attachment and checkpoint operations:

mvmctl machine volume mount worker-1 --volume vol-123 --guest /data --rw --remote
mvmctl machine volume checkpoint vol-123 before-upgrade --remote
mvmctl machine volume restore vol-123 snap-456 --target database-recovered --remote
mvmctl machine volume unmount worker-1 /data --remote
mvmctl machine volume delete vol-123 --remote

Remote restore always creates a new volume from a pinned, ready checkpoint; it does not overwrite the source volume. Delete is refused while a volume remains attached or retains checkpoints. Attachment conflicts, quota failures, authorization failures, provider outages, and integrity refusals are returned as errors rather than falling back to the local registry.

Host-backed mounts

Ad-hoc host-backed mounts are useful when an existing encrypted host directory is the source of truth:

mvmctl machine volume mount agent-sandbox \
  --volume project-data \
  --host /absolute/path/to/data \
  --guest /data

Use --rw only for trusted workflows:

mvmctl machine volume mount agent-sandbox \
  --volume project-data \
  --host /absolute/path/to/data \
  --guest /data \
  --rw

The host directory must live on encrypted backing storage. If encryption cannot be verified, the command should fail closed.

Copy instead of mount

For model-generated code, third-party scripts, and code interpreter workloads, prefer copy-in/copy-out:

mvmctl machine cp ./input.json agent-sandbox:/work/input.json
mvmctl machine exec agent-sandbox -- python /work/task.py
mvmctl machine cp --max-bytes 16777216 agent-sandbox:/work/output.json ./output.json

Copy workflows reduce host exposure. Treat copied guest output as untrusted input when it returns to the host.

Snapshots versus volumes

Volumes preserve selected filesystem state. Snapshots preserve machine state.

Capability	Volume	Snapshot or cold state
Files only	Yes	Yes
Process memory	No	Yes
Running process state	No	Backend-specific
Easier to inspect	Yes	No
Smaller retention surface	Usually	Usually not
Can contain secrets	Yes	Yes

Use a volume when you need durable files. Use cold mode or snapshots when you need to resume a whole machine state.

Agent workspace pattern

For a coding agent:

Create a named sandbox with a short TTL.
Copy the task input into /work.
Mount a managed volume at /workspace only if the agent needs durable state.
Keep network closed until the task has an approved egress need.
Copy out bounded results.
Stop, cold-pause, or destroy based on the retention decision.
Lock volumes and record receipt/audit identifiers.

Example:

mvmctl machine volume create coding-agent-work
mvmctl machine volume unlock coding-agent-work
mvmctl machine run --flake ./agent-image --name coding-agent -d
mvmctl machine volume mount coding-agent --volume coding-agent-work --guest /workspace --rw
mvmctl machine cp ./task.json coding-agent:/work/task.json
mvmctl machine exec coding-agent -- python /work/run_task.py
mvmctl machine cp --max-bytes 16777216 coding-agent:/work/result.json ./result.json
mvmctl machine volume unmount coding-agent /workspace
mvmctl machine stop coding-agent
mvmctl machine volume lock coding-agent-work

Cleanup checklist

Before marking a stateful sandbox done:

stop compute with mvmctl machine stop when it no longer needs to run;
lock every managed volume;
remove mounts that are no longer needed;
delete snapshots that no longer have a recovery purpose;
rotate credentials if generated code had access to them;
store receipt/audit identifiers with the job record;
review logs before attaching them to tickets, traces, or model context.

Stopping compute is not the same as erasing state. Volumes, logs, receipts, snapshots, caches, copied files, and generated artifacts may remain.