Agent tools

GET /public/sandboxes/:sandboxId/exec-access returns sandboxUrl, sandboxRpcUrl, token, and expiresAt. The token is scoped to one sandbox and lasts about ten minutes. It requires MACHINE_UPDATE because it grants command execution and filesystem mutation.

Use sandboxUrl for sandboxd HTTP operations and sandboxRpcUrl for gRPC ExecStream and terminal operations. Send Authorization: Bearer <token>. Never persist or log this token. Request a new one when it expires. Use GET /terminal-url or the CLI shell command for a browser terminal.

The first-party session client calls getAccess and refreshes the credential. The ComputeSDK provider does the same for runCommand and filesystem methods.

1const access = await api.getExecAccess(sandboxId);23const response = await fetch(4  access.sandboxUrl + "/files/stat?path=/workspace",5  { headers: { Authorization: "Bearer " + access.token } },6);78console.log(await response.json());

Commands run through sandboxd's authenticated gRPC service. The stream emits stdout, stderr, and a final exit event. Set a timeout, working directory, and environment explicitly in agent code, and treat command output as untrusted data.

The session client exposes run(command). The ComputeSDK provider exposes compute.sandbox.runCommand(sandbox, command, options). A background command returns after the execution is accepted instead of waiting for an exit event.

The public control API does not proxy command bytes. It only mints the scoped data-plane credential, which keeps high-volume runtime traffic away from the control plane.

1const result = await sandbox.run("python agent.py", {2  workingDirectory: "/workspace",3  timeoutMs: 120000,4  environment: { RUN_ID: runId },5  onStdout: chunk => process.stdout.write(chunk),6  onStderr: chunk => process.stderr.write(chunk),7});89if (result.exitCode !== 0) {10  throw new Error("agent failed with exit code " + result.exitCode);11}

sandboxd exposes read, write, directory listing, mkdir, stat, exists, and remove operations below the sandbox file root. Paths are checked for traversal and symlink escapes. Removing a missing path is idempotent, while removing the file root is rejected.

The first-party session client exposes readText, writeText, makeDirectory, listDirectory, stat, exists, and remove. The ComputeSDK provider maps readFile, writeFile, mkdir, readdir, exists, and remove to the same data plane.

The CLI adds rename plus streaming upload and download. Use a volume or snapshot when data must outlive the sandbox runtime.

1await sandbox.files.makeDirectory("/workspace/results");2await sandbox.files.writeText(3  "/workspace/results/status.json",4  JSON.stringify({ ok: true }),5);67const file = await sandbox.files.readText("/workspace/results/status.json");8const entries = await sandbox.files.listDirectory("/workspace/results");9console.log(file, entries);

The session client exposes screenshot, move, click, scroll, type, and key actions. These calls use the same short-lived sandbox token as commands and files. Use a template that includes the desktop agent when GUI automation is needed.

Desktop actions use native Wayland endpoints through sandboxd. X11 and Xwayland are not required. Screenshots are returned as a Buffer in Node.js.

Desktop automation is available on the first-party session client. For portable ComputeSDK code, combine the standard provider with the session client when the workflow also needs display actions.

1const png = await sandbox.desktop.screenshot();2await sandbox.desktop.move(340, 210);3await sandbox.desktop.click({ x: 340, y: 210 });4await sandbox.desktop.type("hello");5await sandbox.desktop.key("ENTER");

The MCP endpoint is https://api.zei.sh/api/v1/mcp. It uses Streamable HTTP. MCP clients send Authorization: Bearer with either a zeish_live_ API key or an OAuth access token.

Headless clients can use an API key directly. Interactive connectors use OAuth Authorization Code with PKCE and dynamic client registration. OAuth metadata is available at /api/v1/.well-known/oauth-authorization-server. The flow supports S256 and refresh tokens.

The organization tool set covers sandbox create, list, get, data-plane access, terminal URLs, SSH-key sync, previews, logs, events, lifecycle, deletion, snapshots, templates, volumes, networks, secrets, SSH keys, and whoami. Superadmins also get user, organization, node, sandbox, usage, billing, suspension, and credit tools. Call tools/list to inspect the live schema.

1{2  "mcpServers": {3    "zeish": {4      "url": "https://api.zei.sh/api/v1/mcp",5      "headers": {6        "Authorization": "Bearer zeish_live_..."7      }8    }9  }10}