Commands and files

The E2B SDK's sandbox.commands.* and sandbox.files.* calls work on Kibotos sandboxes as they do on E2B. This page covers the supported process and file endpoints, which user a request runs as, how paths resolve, and how process streams and directory watches behave.

Supported endpointsCopy Anchor Link

The process and file endpoints use the same wire format as E2B's envd: the Connect, gRPC, and gRPC-Web protocols, JSON and binary encodings, and gzip compression negotiation.

PTYs and ordinary commands both start with Start.

Running commandsCopy Anchor Link

The following example runs a command as root in /tmp and prints its output:

const result = await sandbox.commands.run('id -un && pwd', { user: 'root', cwd: '/tmp' });
console.log(result.stdout);

Without user and cwd, the command runs as the Template's user in that user's home directory. See User and working directory.

If the connection between the gateway and the node drops while the command runs, the output keeps arriving on the same stream. See Process streams.

User and working directoryCopy Anchor Link

Every process and file request runs as a user in the guest. You choose it with the SDK's user option, and process requests also take a cwd.

Choosing the userCopy Anchor Link

• Without a user, the user the Template declares is used.
• root means root.
• The gateway does not validate user names. The node rejects a user name the Template does not declare with invalid_argument, and the SDK receives that error unchanged.

Working directory and relative pathsCopy Anchor Link

• Without a cwd, the process starts in the home directory of its user.
• Relative file paths and cwd values resolve against the home directory of the user. ~ and ~/… also refer to that directory, as in E2B.
• ~name refers to another user's home and returns invalid_argument.
• If the Workspace's guest is older than v0.3.0, only absolute paths are accepted, and relative paths return 400. Restart the Workspace to enable relative paths.

The following example writes a file with a relative path and reads it back. If the Template declares the user user, both calls use /home/user/notes.txt:

await sandbox.files.write('notes.txt', 'hello');
console.log(await sandbox.files.read('notes.txt'));

How the user is sentCopy Anchor Link

The envd protocol passes the user that runs a request through HTTP basic auth:

• When you specify user, the SDK sends Authorization: Basic base64(username + ":").
• The gateway passes the user name unchanged to the native API: the user field of Start and file system requests, and the user query parameter of /v1/files.
• GET /files and POST /files also accept the username query parameter of the envd protocol. When both are present, basic auth wins.
• X-Access-Token remains the authentication credential. Basic auth expresses identity only.

Process streamsCopy Anchor Link

When the process stream between the gateway and the node drops, the gateway resumes it automatically. The SDK keeps receiving the same stream, with no lost or duplicated output. The gateway retries for at most 30 seconds.

The sandbox keeps only a bounded amount of recent output for each process; for the limits, see Resuming process streams. If the disconnect lasts long enough for the output to exceed them, the lost part cannot be recovered. The stream then ends with data_loss, instead of handing output with a gap to the SDK as if it were continuous.

Watching directoriesCopy Anchor Link

files.watchDir (WatchDir) watches a single directory, without its subdirectories:

• A watch ends when the directory is deleted or moved away, the sandbox is paused, or events cannot be delivered in time. onExit receives the corresponding error. For the reasons a watch ends, see Tracking a directory.
• allowNetworkMounts is ignored.

Two forms of watching are not available, and both are listed in Not supported:

• recursive: true returns unimplemented.
• CreateWatcher, GetWatcherEvents, and RemoveWatcher return unimplemented. They require the gateway to keep watch state across requests, and the gateway keeps no state.

NotesCopy Anchor Link

• On Kibotos, each request message to the process and file endpoints is limited to 4 MiB, measured after decompression for compressed messages. Larger messages return resource_exhausted and are not forwarded to the sandbox. E2B has no such limit, so split data larger than about 3 MiB across several sendStdin calls.
• files.write uploads at most 1 GiB per file; a larger upload returns 413 (resource_exhausted). Reads have no size limit: files.read reads a file of any size, and the gateway fails the read if the file changes while it is being read. Before v0.3.0, the gateway returns 413 for a file larger than 1 GiB.

Next stepsCopy Anchor Link

• Sandboxes and lifecycle: create, pause, resume, and expire sandboxes.
• Volumes: mount a standalone Volume in a sandbox.
• Commands and terminals: the native process API behind these endpoints.
• Files: the native file API, its limits, and its errors.