File Operations & Transfer

Filesystem operations run through the sandbox runtime API. SDKs hide runtime auth, Connect RPC headers, and upload/download route differences.

Write And Read Files

Node

await sandbox.files.write("/root/workspace/hello.txt", "hello\n");
const text = await sandbox.files.read("/root/workspace/hello.txt");
console.log(text);

Python

sandbox.files.write("/root/workspace/hello.txt", "hello\n")
text = sandbox.files.read("/root/workspace/hello.txt")
print(text)

Go

files, _ := sbx.Files()
_, _ = files.Write(ctx, "/root/workspace/hello.txt", []byte("hello\n"))
body, _ := files.Read(ctx, "/root/workspace/hello.txt", nil)

Work With Directories

await sandbox.files.makeDir("/root/workspace/app");
await sandbox.files.write("/root/workspace/app/index.html", "<h1>Hello</h1>");
const entries = await sandbox.files.list("/root/workspace/app");
console.log(entries);

Upload Local Files

For fast iteration, read local files in your application and write them into the sandbox:

const html = await fs.promises.readFile("./index.html", "utf8");
await sandbox.files.write("/root/workspace/frontend/index.html", html);

For reusable source and dependency setup, upload local files during template build with Template.copy(...) instead of uploading into every new sandbox.

Runtime Upload And Download Routes

Use SDK helpers where possible. When debugging raw runtime traffic, the common routes are:

Route	Purpose
GET {envdUrl}/file?path=<path>	Read raw file bytes.
POST {envdUrl}/file?path=<path>	Write raw file bytes.
GET {envdUrl}/files/content?path=<path>	Read file content as a structured response.
POST {envdUrl}/files	Upload multipart content.
POST {envdUrl}/files/batch	Write multiple files.
POST {envdUrl}/files/compose	Compose output from multiple source files.

All routes require X-Access-Token: <envdAccessToken>.

Watch Directory

Directory watchers are exposed through the runtime filesystem surface when enabled in the target SDK/runtime. Use watchers when an agent writes output files and the orchestrator needs to react.

const watcher = await sandbox.files.watchDir("/root/workspace/output", {
  recursive: true,
});

for await (const event of watcher) {
  console.log(event.type, event.path);
}

Watcher availability

The runtime API includes watcher routes. SDK method names and streaming semantics may differ by SDK version, so verify the installed SDK before relying on long-lived watchers in production.

Path And Persistence Rules

Rule	Why it matters
Prefer absolute paths	Avoid ambiguity around template workdir.
Use mounted paths for durable files	Persistence is controlled by volumeMounts[].path, not by workdir.
Treat ephemeral as sandbox-lifetime storage	Files disappear when the sandbox is deleted.
Keep artifacts out of logs	Generated files may contain secrets or user data.

Storage Behavior

Storage type	Persistence behavior
ephemeral	Sandbox lifetime only.
nfs	Shared NFS path.
block	PVC-backed volume.
object	Synced to object-backed storage, depending on runtime sync policy.

For object-backed storage, wait for the runtime sync/flush behavior your template documents before deleting the sandbox.