Perplexity SPACE sandbox setup

These choices solve related tasks with different operating responsibilities. The recommendations are editorial; they are not a security or performance ranking.

SPACE architecture · Docker security · E2B docs · Modal Sandbox · our CubeSandbox guide.

Docker in SPACE's local installation hosts parts of the deployment; it is not a replacement for the guest Firecracker boundary. A worktree only separates repository files and is not a code-execution sandbox. Compare network access, mounted paths, credentials, resource caps, retention and cleanup under your threat model before choosing.

The local installation guide targets an apt-based Linux x86_64 host with KVM. It requires accessible /dev/kvm and /dev/net/tun, loop devices, btrfs and a local Docker daemon allowing privileged containers. A VM must expose these devices and nested virtualization. The local guide does not run directly on macOS; it does not establish native Windows support. Treat WSL or any unlisted host as unverified for this recipe.

This is an operator setup using Bash, Git, curl, tar, OpenSSL, Python 3.8+ and ssh-keygen, plus elevated package setup. The helper installs tools such as Kind, kubectl, Helm and Tilt. Inspect scripts and provision a dedicated host before granting those privileges. Do not paste the setup into your daily laptop merely to try a news item.

Follow the official guide in order:

1. Get the repository and record the chosen revision.
2. Run its host checks, then install and verify the documented prerequisites and Firecracker artifacts.
3. Configure and bootstrap the local Kind deployment; wait for the services and published seed:latest template.
4. Configure the API and data-plane access, authenticate, and export SPACE_API_URL, SPACE_DATA_PLANE_URL and SPACE_API_TOKEN in the intended shell.
5. Only then continue to the first-sandbox example below.

The reference local deployment uses development passwords/signing keys and must stay private. Its preflight does not prove all privileged Docker, loop-device and btrfs operations work. Installation and verification.

The repository is Apache-2.0 licensed. That does not include free compute, storage, network transfer or operations. The versioning document names 0.8.0 as a public baseline and describes later stabilization; the checked GitHub Releases API returned no release entries. Do not treat a Cargo version or roadmap as a published stable release. Versioning contract.

The documented default runtime selector is fc, for Firecracker. The runtime catalog lists installable Firecracker/kernel combinations; that does not establish a supported Docker runtime or that every listed combination boots every workload. Guest applications must exist in the chosen Linux template; SPACE's Rust implementation is not a restriction that only Rust jobs can run. First-sandbox fields · Runtime catalog.

A sandbox has its own writable filesystem and VM. Host services still require privileges. Management requests use a bearer token; command attachment uses a different, session-scoped token. Do not put management credentials into agent prompts or guest environment values. Architecture and authorization.

Do not assume default-deny outbound networking. The documented Kind namespace rules allow public IPv4 egress and cluster DNS while separating sandbox pods from the control plane. Inspect the effective template/tenant policy and any operator additions before accepting untrusted code. Operator egress profiles are additive and saved with the sandbox; changing the profile configuration does not retroactively tighten existing saved policies. Network architecture · Egress profiles.

For an application pilot, explicitly allow only required destinations, keep production credentials outside the guest, restrict input/output paths and verify intended denials using harmless requests you control. Those checks remain to be performed; this guide has not demonstrated containment or audited the host.

After the official setup and authentication, the documented repository example uses Python's standard library. It creates a sandbox and runs a known greeting; it is not a command to execute arbitrary agent output.

python3 examples/first_sandbox.py

Use the repository root and the same configured shell. Save the private run-directory path printed by the script. Its state.json keeps returned IDs, mutation request bodies and idempotency keys, without saving bearer tokens. First-sandbox walkthrough.

Check each transition:

1. Creation: record sandbox and operation IDs. An accepted HTTP request is not a running guest.
2. Readiness: require successful operation completion, a running sandbox and a reachable process endpoint.
3. Execution: create a command session and attach; attachment starts the process.
4. Result: decode stdout/stderr and require process_exited with exit code 0, without error or incomplete/resync frames. The example should print the greeting and successful completion.
5. Inspection: inspect the sandbox and operation; the running-process list is not completed-command history.

The command stream is not durable log storage. Reconnecting with Last-Event-ID produces resync_required, not a replay. Save output as it arrives. If the stream breaks, do not infer success from a closed connection or repeat effects blindly. Output and inspection.

At sandbox creation, explicitly choose resources.vcpu, resources.memory_mib and resources.disk_mib appropriate to the task. Omitted values remain null in the response while deployment defaults apply; null does not mean unlimited or zero. A command's timeout is a separate server-side deadline; omitting it supplies no command deadline. The first example also has a client stream-read timeout. Request field definitions.

Choose an existing guest working directory, pass arguments as an array and use an explicit shell only when necessary. A host path is not automatically a guest path. An agent should receive only the input files, command permissions and output destination required for the bounded task.

Files in a writable guest filesystem can outlive one command. Pausing retains resident memory; suspending snapshots state and releases active VM resources. The documented six-hour idle suspension is not a maximum lifetime or deletion policy. Explicitly decide what to retain, export and delete. Lifecycle semantics.

Our suggested acceptance record is: revision/template, effective resources, command and deadline, sandbox/operation/session IDs, observed output and exit code, retained artifacts and cleanup result. Keep sensitive files and tokens out of published logs. For detailed file and disk behavior, use the guest I/O reference.

Use the exact directory printed by your run. This placeholder must be replaced:

export RUN_DIR=/tmp/space-first-sandbox-REPLACE_ME
python3 examples/first_sandbox.py inspect "$RUN_DIR"

If the run failed or timed out, keep its state and reconcile the original operation. Starting the example again makes a new request. A timeout does not prove the earlier mutation failed. Keep the original idempotency key and request body when the documented recovery calls for a retry. Safe recovery.

When you intend to remove that sandbox:

python3 examples/first_sandbox.py delete "$RUN_DIR"

The helper asks for confirmation and waits for deletion's operation before removing tracked transcripts. A 404 or interrupted wait is not evidence of successful deletion. The run directory and state record remain; remove those later according to your retention needs. Cleanup behavior.

Common failures: missing KVM/devices require host repair, not another create; absent templates require finishing setup; readiness failures require inspecting the operation; token errors require the right token and origin; stream loss requires checking state before repeating the command. Troubleshooting.

SPACE's ECW is a compatibility layer maintained by SPACE, not proof of full interchangeability with every E2B SDK. The documented tested baseline is e2b 2.21.1 and e2b-code-interpreter 2.6.2 for Python; other releases and the JavaScript SDK are not covered by those repository compatibility tests. ECW also needs its own host routing, credentials and configuration. ECW contract.

If you already use E2B, first inventory the SDK version and calls you actually depend on, then compare that subset with ECW. Keep network policy and retry semantics in the comparison, not just method names. We did not perform that migration or compare latency, security strength or operating cost.