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, prefer a prepared official template or a pinned concrete tpl-.... Projects with template build access can also preinstall dependencies through the template build flow.

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 Rules

Rule	Why it matters
Prefer absolute paths	Avoid ambiguity around template 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	Best use
ephemeral	Sandbox lifetime only.	Temporary files and generated artifacts that can be discarded.