SDK

SDK operations cookbook

Current Python and TypeScript SDK calls, secure defaults, target helpers, and CLI fallbacks for common sandbox operations.

Use this page when you want a practical SDK operation and need to know whether to call the SDK today, use the CLI directly, or treat the helper as target API.

The shipped SDK runtime surface is intentionally smaller than the product target. Current examples use Sandbox.create(...), commands.start(...), files.write(...), TTLs, resources, network declarations, record mode, live mode, and cleanup. Higher-level helpers such as commands.run(...), files.read(...), logs, ports, and snapshots are parity targets until the language SDK tests prove them.

Operation status

Operation	Python today	TypeScript today	Secure fallback today
Create sandbox recording	`mvm.Sandbox.create(...)`	`Sandbox.create(...)`	`mvmctl build compile` or `mvmctl run --mode plan`
Create live sandbox	`mvmctl run --mode live ./script.py`	`mvmctl run --mode live ./script.ts`	`mvmctl machine run`
Start command	`sandbox.commands.start([...])`	`sandbox.commands.start([...])`	`mvmctl machine proc start` or `mvmctl machine exec`
Capture command result	Target `commands.run(...)`	Target `commands.run(...)`	CLI command result and receipt paths
Write file	`sandbox.files.write(path, data)`	`sandbox.files.write(path, data)`	`mvmctl machine fs write`
Read/list/remove file	Target helpers	Target helpers	`mvmctl machine fs read`, `mvmctl machine fs ls`, `mvmctl machine fs rm`
Logs	Target helper	Target helper	`mvmctl machine logs`
Ports	Target helper	Target helper	port-forwarding CLI commands
Pause/resume	Target helper	Target helper	`mvmctl machine pause`, `mvmctl machine resume`
Checkpoint create/restore	Target helper	Target helper	`mvmctl machine checkpoint create --class vm-full`, `mvmctl machine checkpoint restore`
Stop cleanup	context manager or `kill()`	`using`/`Symbol.dispose` or `kill()`	`mvmctl machine stop`

import mvm

with mvm.Sandbox.create(
    "python-3.12",
    workload_id="agent-tool",
    ttl="30m",
    include=["src"],
    resources=mvm.resources(cpu_cores=1, memory_mb=512, rootfs_size_mb=1024),
    network=mvm.network(mode="none"),
) as sandbox:
    sandbox.files.write("/app/main.py", "print('hello from mvm')")
    sandbox.commands.start(
        ["python", "/app/main.py"],
        env={"MODE": "dev", "API_KEY": mvm.secret("api-key", type="bearer", hosts=["api.example.com"])},
    )

Security notes:

the Python script itself runs on the host in record, plan, and live modes;
secret references are recorded as references, not copied as raw values;
commands.start(...) starts work, but result capture is still a parity target;
the context manager records or performs cleanup through kill().

Run modes:

mvmctl build compile ./sandbox.py --out /tmp/sandbox-ir
mvmctl run --mode plan ./sandbox.py
mvmctl run --mode live ./sandbox.py

import { Sandbox, network, resources, secret } from "@runmvm/mvm";

using sandbox = Sandbox.create("node-22", {
  workloadId: "agent-tool",
  ttl: "30m",
  include: ["src"],
  resources: resources({ cpu_cores: 1, memory_mb: 512, rootfs_size_mb: 1024 }),
  network: network({ mode: "none" }),
});

sandbox.files.write("/app/main.js", "console.log('hello from mvm')");
sandbox.commands.start(["node", "/app/main.js"], {
  env: {
    MODE: "dev",
    API_KEY: secret("api-key", { type: "bearer", hosts: ["api.example.com"] }),
  },
});

Security notes:

the TypeScript module runs on the host in runtime SDK modes;
using calls the SDK cleanup path when the scope exits;
use static declarations instead of runtime scripts for untrusted deployable workload declarations;
live mode shells through the invoking mvmctl binary.

Run modes:

mvmctl build compile ./sandbox.ts --out /tmp/sandbox-ir
mvmctl run --mode plan ./sandbox.ts
mvmctl run --mode live ./sandbox.ts

Target result capture

The product target is a typed result helper:

Python
TypeScript

result = sandbox.commands.run(["python", "/app/main.py"], timeout_seconds=30)
print(result.exit_code)
print(result.stdout)
print(result.audit_id)

const result = await sandbox.commands.run(["node", "/app/main.js"], {
  timeoutSeconds: 30,
});
console.log(result.exitCode);
console.log(result.stdout);
console.log(result.auditId);

Until this helper is shipped in a language SDK, use the CLI path for result capture, receipts, and automation that needs exit status or bounded output.

Target file reads

The product target is a symmetric file API:

Python
TypeScript

sandbox.files.write("/work/input.json", b"{}")
data = sandbox.files.read("/work/output.json")
entries = sandbox.files.list("/work")
sandbox.files.remove("/work/output.json")

await sandbox.files.write("/work/input.json", new TextEncoder().encode("{}"));
const data = await sandbox.files.read("/work/output.json");
const entries = await sandbox.files.list("/work");
await sandbox.files.remove("/work/output.json");

Until read/list/remove helpers are shipped, use the CLI filesystem commands. Treat bytes returned from the guest as untrusted and possibly sensitive.

Target logs and ports

Logs and ports should keep policy visible:

Python
TypeScript

for event in sandbox.logs(follow=True, redact=True):
    print(event.message)

# Ingress is declared in Sandbox.create(..., network={"ports": [...]})
# before the signed plan is admitted.

for await (const event of sandbox.logs({ follow: true, redact: true })) {
  console.log(event.message);
}

// Ingress is declared in Sandbox.create(..., { network: { ports: [...] } })
// before the signed plan is admitted.

Until language helpers are shipped, declare ingress through machine run --port or the manifest. Bind host ports explicitly and avoid wildcard listeners unless the workflow requires them.

Target lifecycle and snapshots

Lifecycle helpers should expose the same state model as the CLI:

Python
TypeScript

snapshot = sandbox.snapshot(name="after-index")
sandbox.pause()
sandbox.resume(snapshot=snapshot.id)
sandbox.stop()
sandbox.destroy()

const snapshot = await sandbox.snapshot({ name: "after-index" });
await sandbox.pause();
await sandbox.resume({ snapshot: snapshot.id });
await sandbox.stop();
await sandbox.destroy();

Until those helpers are shipped, use:

mvmctl machine pause agent-sandbox
mvmctl machine resume agent-sandbox
mvmctl machine checkpoint create agent-sandbox --class vm-full
mvmctl machine checkpoint restore CHECKPOINT_ID
mvmctl machine stop agent-sandbox

Snapshots and cold state can contain memory, files, process state, and credentials. Retention and deletion policy should be explicit in automation.