Providers

CubeSandbox Provider

GitHub Edit page

CubeSandbox Provider

Read when:

  • choosing provider: cubesandbox;
  • running commands in a CubeSandbox deployment through its E2B-compatible API;
  • configuring Cube API, CubeProxy, templates, or data-plane access;
  • changing internal/providers/cubesandbox.

CubeSandbox is an E2B-compatible MicroVM sandbox platform. Crabbox treats it as a delegated-run provider: CubeSandbox owns sandbox lifecycle, file upload, and command execution, while Crabbox owns local config, repo claims, archive sync, guardrails, timing summaries, and normalized list/status output.

#When To Use

Use CubeSandbox when commands should run inside a CubeSandbox KVM MicroVM and you do not need a normal SSH lease. The provider works with self-hosted CubeSandbox deployments and the standard Cube API / CubeProxy layout.

Use an SSH-lease provider such as aws, hetzner, or ssh when the workflow requires crabbox ssh, VNC, code-server, GitHub Actions runner hydration, or host-managed SSH access.

Multipart archive uploads finish using their borrowed source before returning. HTTP failures remain primary; source failures after an early success response are reported with token redaction. Cancellation stops HTTP/pipe work but may wait for an in-flight source read; the upload does not close the caller-owned source.

#Prerequisites

  • A reachable Cube API endpoint, usually http://<cubeapi-host>:3000.
  • A ready CubeSandbox template ID, for example from CUBE_TEMPLATE_ID.
  • CubeProxy data-plane routing. If DNS for 49983-<sandbox>.<domain> is not available from the Crabbox host, configure CUBE_PROXY_NODE_IP.

#Commands

export CUBE_API_URL=http://cubeapi.example.internal:3000
export CUBE_TEMPLATE_ID=<template-id>
export CUBE_PROXY_NODE_IP=cubeproxy.example.internal
export CUBE_PROXY_PORT_HTTP=80
export CUBE_PROXY_SCHEME=http
export CUBE_SANDBOX_DOMAIN=cube.app

crabbox run --provider cubesandbox -- go test ./...
crabbox run --provider cubesandbox --id blue-lobster --shell 'pnpm install && pnpm test'
crabbox warmup --provider cubesandbox --slug cube-smoke
crabbox status --provider cubesandbox --id cube-smoke --wait
crabbox stop --provider cubesandbox cube-smoke

run without --id creates a sandbox from the configured template, archive syncs the checkout into the sandbox workdir, runs the command through envd's Connect process API, and deletes the sandbox unless --keep or failure-retention options keep it. warmup creates a retained sandbox; stop it explicitly.

Commands share Crabbox's argv-versus-shell intent handling. Quoted profile arguments remain literal, including separators and assignment-shaped executable names. Single-string inferred programs and explicit --shell source execute in envd's existing /bin/bash -l -c shell; explicitly empty shell source is valid. Literal argv uses exec in that shell, so the workload replaces it rather than running a shell suffix or exit trap afterward. No additional shell is inserted. Use --shell for shell-only builtins or functions rather than literal argv.

#Auth

export CUBE_API_KEY=...

CRABBOX_CUBESANDBOX_API_KEY also works and wins over CUBE_API_KEY. For E2B-compatible environments, E2B_API_KEY is accepted as a fallback. The key is sent as Authorization: Bearer <token> to the Cube API and is never registered as a command-line flag.

Many self-hosted CubeSandbox deployments accept unauthenticated local API traffic or any non-empty E2B-compatible key. Leave the key unset only on trusted networks where the Cube API is intentionally unauthenticated.

#Config

provider: cubesandbox
target: linux
cubeSandbox:
  apiUrl: http://cubeapi.example.internal:3000
  template: <template-id>
  domain: cube.app
  workdir: crabbox
  user: root
  proxyNodeIp: cubeproxy.example.internal
  proxyPortHttp: 80
  proxyScheme: http

Put apiUrl, domain, and CubeProxy routing values in trusted user config, environment variables, or explicit flags. Crabbox rejects these destinations from repository-local config because the Cube API selects the envd route, which receives the sandbox access token, workspace archive, command, and forwarded environment.

All nine configuration bindings share one typed declaration. The API key stays environment-only. File strings ignore empty values, and file proxy ports apply only when positive. Environment proxy ports retain signed-integer parsing and first-nonempty alias precedence; malformed values fail without applying later fields. Explicit flags retain their existing empty-string and signed-port behavior. Endpoint provenance and repository destination rejection remain core policy, separate from these bindings.

Provider flags:

--cubesandbox-api-url
--cubesandbox-domain
--cubesandbox-template
--cubesandbox-workdir
--cubesandbox-user
--cubesandbox-proxy-node-ip
--cubesandbox-proxy-port-http
--cubesandbox-proxy-scheme

Environment overrides:

CRABBOX_CUBESANDBOX_API_KEY / CUBE_API_KEY / E2B_API_KEY
CRABBOX_CUBESANDBOX_API_URL / CUBE_API_URL / E2B_API_URL
CRABBOX_CUBESANDBOX_DOMAIN / CUBE_SANDBOX_DOMAIN
CRABBOX_CUBESANDBOX_TEMPLATE / CUBE_TEMPLATE_ID
CRABBOX_CUBESANDBOX_WORKDIR
CRABBOX_CUBESANDBOX_USER
CRABBOX_CUBESANDBOX_PROXY_NODE_IP / CUBE_PROXY_NODE_IP
CRABBOX_CUBESANDBOX_PROXY_PORT_HTTP / CUBE_PROXY_PORT_HTTP
CRABBOX_CUBESANDBOX_PROXY_SCHEME / CUBE_PROXY_SCHEME

Defaults: API URL http://127.0.0.1:3000, sandbox domain cube.app, workdir /root/crabbox, process user root, proxy port 80, and proxy scheme derived from the proxy port (http unless port is 443). A template is required for new sandboxes.

When proxyNodeIp is set, Crabbox connects to <proxyScheme>://<proxyNodeIp>:<proxyPortHttp> and preserves the envd virtual sandbox host header (49983-<sandbox>.<domain>). Leave proxyNodeIp empty when that virtual host already resolves from the Crabbox host.

#Capabilities

  • Target: Linux only.
  • SSH: no.
  • Crabbox sync: no normal SSH/rsync; archive sync is delegated through envd file upload.
  • Generic run: yes, through /bin/bash -l -c in the CubeSandbox envd process API.
  • Warmup: yes, retained sandbox from a template.
  • Stop/delete: yes, for Crabbox-claimed sandboxes.
  • Desktop/browser/code: no.
  • Coordinator: no (direct from CLI only).

#Run completion and cleanup

Run results and timing are finalized after cleanup. A failed automatic deletion returns a failure and a retained recovery session; claims are removed only after authorized cleanup succeeds. An existing command failure keeps its exit code if cleanup or timing output also fails. --keep-on-failure applies to connection and workspace preparation failures after acquisition, as well as command failures. Reused sandboxes are never automatically deleted.

An abnormal process-end event preserves its reported nonzero exit code and diagnostic, including negative codes reported for directly signaled processes. An abnormal zero becomes failure code 1. Transport errors remain separate from observed process exits and preserve cancellation/timeout causes. CubeSandbox's existing immediate return on an abnormal end is unchanged; this does not certify that a later stream trailer or sandbox deletion succeeded.

The envd Connect wire codec is shared with E2B; this abnormal-end policy and CubeProxy routing remain CubeSandbox-owned.

The compatible control plane also shares sandbox record types, returned-ID validation, and cursor pagination with E2B. Authentication, creation payloads, response-error decoding, and envd endpoint routing stay in each adapter.

#Gotchas

  • --class and --type are rejected; choose the template and CubeSandbox node capacity outside Crabbox.
  • --checksum is rejected because sync is archive-based.
  • The provider requires a template ID for create/warmup/run-without-id.
  • HTTP Cube API URLs are supported for self-hosted deployments. Do not send real API keys over untrusted HTTP networks.
  • Reuse, status, and stop require a local claim bound to the exact Cube API endpoint, sandbox ID, provider, and canonical remote lease metadata. Labels alone never authorize a mutable or destructive operation.
  • To adopt a labelled legacy or externally restored sandbox, use its exact CubeSandbox sandbox ID with run --id <sandbox-id> --reclaim or stop --id <sandbox-id> --reclaim. Conflicting claims fail closed.
  • Sandbox reads and connections must return the exact requested native sandbox ID. A missing or different ID is rejected before adoption or execution; normal failure cleanup remains bound to the originally acquired sandbox.

Related docs: