Sandboxes

A sandbox gives an agent a working directory, files, real shell commands and optional interactive terminals. It can clone a repository, install a tool, edit code or keep an agent server running. station-sandbox manages that environment on a particular worker; it does not emulate Unix or automatically move a running process to another machine.

Choose the boundary before running code

Install and configure tools on the host for the host adapter, or build them into the tools image for the container adapter. Container startup fails when its engine or required policy is unavailable; Station never silently switches to host execution. A container shares the host kernel. Public tenants also need the authorization, private-worker and egress controls in the execution reference.

Create a workspace and run a command

This operator-side example requires a prebuilt image and a reviewed seccomp policy. The image digest is a placeholder. Start with no external network access, then configure an enforced network policy if the workload needs downloads or model APIs.

import { ContainerSandboxAdapter } from "station-sandbox/container"; const sandboxes = new ContainerSandboxAdapter({  rootDir: "/data/sandbox-metadata",  image: "registry.example/tools@sha256:YOUR_VERIFIED_DIGEST",  seccompProfile: "/etc/station/seccomp.json",  network: "none",  cpus: 1, memoryMb: 1024, pidsLimit: 128,});await sandboxes.ready();const workspace = await sandboxes.create();const run = await sandboxes.exec(workspace.id, {  command: "node --version && pwd",  timeoutMs: 10_000,});// exec returns a run handle. Read command() until status is terminal.const current = await sandboxes.command(workspace.id, run.id);console.log(current.status, current.stdout);

Commands have bounded runtime and output. Inspect status, exitCode and truncated; receiving a run ID does not mean the command succeeded. Retain the workspace ID in trusted application state so later requests reach the same worker and workspace.

Use the right surface for the work

Open Sandboxes → worker → workspace in the dashboard. Closing the browser tab does not stop a service. Force-closing a terminal, cancelling a command or hitting a command timeout can stop the entire container to contain descendants, interrupting sibling services. Restart affected services explicitly afterward.

const service = await sandboxes.startService(workspace.id, {  name: "agent-gateway",  command: "node server.js", // Foreground: do not append & or daemonize.  restart: { policy: "on-failure", maxRestarts: 5, delayMs: 1000 },});// Inspect attempts and output through service()/the Services page.// Stop deliberately with stopService(workspace.id, service.id).

Install tools and work with Git

Use the image for reproducible shared tools and a workspace-local install for project dependencies. In the container adapter, HOME is /home/node, the default working directory is /home/node/workspace, and npm's user prefix is /home/node/.local. That prefix is on the command path. Installs under this home persist; changes to temporary files do not.

# Inside a sandbox with Git and permitted outbound network access:git clone --depth 1 https://github.com/OWNER/REPOSITORY.git appcd app# Review its install scripts before running them.npm ci# Edit files in the dashboard or terminal.git diffgit status --short # For a custom CLI, pin an approved package version:npm install --global YOUR_CLI@EXACT_VERSION

A GitHub App credential can authorize one repository without giving the agent your personal account. Mint a short-lived installation token outside the sandbox, grant only the required repository permissions, and deliver it through protected runtime configuration or a credential helper. Do not embed tokens in clone URLs or command text. A local commit needs no remote permission; pushing and opening a pull request require the corresponding grants.

Networking inside the workspace

Processes in one sandbox can talk over 127.0.0.1: an agent can call its own test server or local API. Separate sandboxes have separate network namespaces. Station does not automatically create Compose-style service discovery, publish arbitrary ports, or proxy every sandbox service. Cross-workspace networking and external ingress require an operator-provided design.

network: "none" still permits sandbox-local loopback. Bridge networking enables outbound access, but does not itself restrict access to private networks, metadata endpoints or other tenants. The networkRestricted setting describes an independently enforced policy; it does not install a firewall.

What survives a restart?

Do not point two live controllers at the same metadata root. Local ownership locks are not distributed failover. Disk quotas, backups, host availability and monitoring remain deployment responsibilities.