> ## Documentation Index > Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Workspace, executions, and product runs > Work with files, bounded executions, background processes, terminals, interpreters, agents, and retained output. Use the sandbox runtime primitives directly. Agents, interpreters, browser runs, and CI views are projections over the same executions, processes, files, ports, artifacts, operations, and events; they do not create a second orchestration path. ## Run a bounded command `exec` sends an argv array by default, streams stdout and stderr, waits for a terminal execution state, and exits non-zero when the remote command fails. ```bash theme={null} stackshift sandbox exec -- npm test -- --runInBand ``` The defaults are `/workspace`, OS user `sandbox`, closed stdin, captured stdout/stderr, and a 600-second remote timeout. Override only what the template and effective policy allow: ```bash theme={null} stackshift sandbox exec \ --cwd /workspace/packages/api \ --user sandbox \ --command-timeout 1200 \ -- go test ./... ``` Use `--shell` only when shell parsing is intentional. Quoting, expansion, pipes, and redirects then follow the template shell and must be treated as code execution. ```bash theme={null} stackshift sandbox exec --shell -- 'npm test && npm run build' ``` Use `--background` to return the execution resource immediately. Save its ID and inspect it through the API or SDK; background mode does not stream logs in the CLI. ```bash theme={null} stackshift --output json sandbox exec \ --background -- npm run dev ``` ## Open an interactive terminal ```bash theme={null} stackshift sandbox terminal \ --cwd /workspace \ --user sandbox \ --rows 40 \ --columns 120 ``` The CLI acquires a sandbox writer lease, creates the terminal, waits until it is running, requests a short-lived write ticket, and bridges the local terminal over the authenticated stream. A terminal ticket is scoped to one terminal and cannot replace the API token. If another writer holds the lease, do not force takeover blindly. Identify the active editor or terminal first; a forced lease transfer can make its next write fail. ## Work with files safely File APIs are rooted in approved mounts and reject path escapes and symlink traversal outside those roots. Mutating file actions require the current writer-lease token. Content writes may include an expected checksum; use it to reject a stale overwrite. Recommended editor flow: 1. Acquire the writer lease and retain its token only in memory. 2. Read the file and its checksum/version. 3. Submit the write with the lease token and expected checksum. 4. On a checksum conflict, reload and merge instead of overwriting. 5. Renew an active lease, then release it when editing ends. Large uploads and downloads use file-transfer resources and short-lived object-storage URLs. Complete an upload explicitly so the platform can verify its checksum and size. ## Processes and logs Use a process for a long-lived workload such as a development server. A process retains command metadata, state, readiness, timestamps, and offset-addressed stdout/stderr. Consumers must resume from `next_offset`, handle `truncated: true`, and stop only when the page is complete and the process is terminal. Signals, stdin writes, cancellation, and process wait are explicit API operations. Sleep stops running processes; resume restores declared filesystem state and starts a new runtime, not the old process memory. ## Interpreter contexts Interpreter contexts support Python, JavaScript, and TypeScript kernels with ordered run history. Create a context, submit code, inspect the run, and interrupt a stuck run without destroying the sandbox. Reset replaces kernel state. Rich HTML and SVG results are untrusted content. The dashboard sanitizes them and isolates previews. Files written to persistent storage can survive sleep or snapshots; in-memory variables cannot. ## Agents and retained output An agent run should record its initiating actor, execution/process IDs, approvals, events, and artifact IDs. Attach credentials through scoped secret bindings rather than command arguments or persisted environment files. In the **Agents** route, select a run to inspect its thread, current step, linked execution/process, event timeline, requested approval, and produced artifacts. An approval must state the proposed command/action, affected paths or resources, network/secret impact, requester, and expiry. Approve or deny that exact request; approval does not grant broader sandbox permissions or relax effective policy. Cancellation is a durable orchestration action. After cancelling a run, confirm the linked execution/process reaches a terminal state and review partial files/artifacts before starting another run. A failed agent view must link to the canonical sandbox operation or execution failure rather than replace it with a generic agent error. Retain deliverables as artifacts when they must outlive workspace cleanup. Artifact upload is a prepare/upload/complete flow; completion verifies the declared checksum and makes downloads available through current authorization and short-lived URLs. ## Follow live state The resumable event stream emits newline-delimited JSON in the CLI. Store the highest processed sequence and reconnect after it: ```bash theme={null} stackshift sandbox events --after-sequence 0 stackshift sandbox events --after-sequence ``` Events are a change feed, not a substitute for fetching the current resource after reconnect. Run browser work and expose private previews. Diagnose failed commands, leases, streams, and readiness.