ScaleBox platform architecture

What you are using

ScaleBox provides isolated sandbox environments: each sandbox has defined CPU, memory, storage, networking, and optional features such as exposed ports, WebRTC, and configurable egress behavior. You work with sandboxes through templates, projects, and user-facing interfaces rather than underlying orchestration concepts. A control plane (REST API, persistence, scheduling, and billing) receives your requests, provisions sandboxes, and tracks their lifecycle and usage.

The important architectural point is that ScaleBox is built around one sandbox engine but exposes four user-facing paths: web console, HTTP API, CLI, and SDKs. The product tries to keep each path as end-to-end as possible so users do not have to switch surfaces in the middle of a workflow.

The control plane and your sandboxes

• Control plane — The ScaleBox backend exposes versioned HTTP routes (for example under /v1/...), authenticates requests (typically with an API key), and coordinates templates, projects, sandboxes, networking, archives, billing, and related operations. It is the authority for lifecycle and metadata.
• Sandbox runtime — Each running sandbox is a flexible workload environment. It can host the sandbox agent, user processes, notebook kernels, custom web services, TCP services, WebRTC endpoints, and other application-specific workloads defined by its template and runtime configuration.

All user-facing tools ultimately depend on the same control plane, but they may interact with a running sandbox in different ways depending on the workflow.

Web console (dashboard)

The console is the browser UI for your organization: sign-in, API keys, templates, sandbox list and detail, usage and billing views, and interactive flows that mirror what the API can do.

Best for: discovery, day-to-day operations without writing code, issuing and rotating API keys, and sharing context with teammates who prefer a GUI.

Relationship to the API: The console is a client of the same backend the API serves. Anything you can do in the UI has a corresponding API concept (sandboxes, templates, keys, etc.), documented under API Reference.

HTTP API

The REST API is the contract for automation and integrations. Use it from any language or tool that can send HTTPS requests with your API key (header such as X-API-Key). It covers control-plane operations directly, and it also proxies selected low-level sandbox operations such as file handling, terminal access, and command execution so API-first users can stay on one path as much as possible.

Best for: CI/CD, custom internal tools, services that create and manage sandboxes on demand, and integrations that want one stable backend path for most operations.

Relationship to other tools: The CLI and SDKs call these endpoints; they are not a separate product surface. For route-level detail, see API Reference.

CLI (scalebox-cli)

The CLI packages most public backend capabilities as commands: auth, sandboxes, templates, projects, API keys, notifications, webhooks, usage, billing, and more. For sandboxes, it covers not only create/list/connect flows but also file-oriented and command-oriented workflows such as sandbox exec, plus advanced sandbox run-code flows on compatible templates. It stores credentials locally (for example under ~/.scalebox-cli/) and targets your chosen API base URL.

Best for: terminal-first workflows, scripts, and operators who want readable commands and JSON output without maintaining SDK dependencies.

Relationship to the API: The CLI uses the backend for control-plane tasks, but for many in-sandbox operations it can also connect directly to the sandbox domain with sandbox-specific credentials. This gives a more complete end-to-end terminal workflow while still fitting the same product model. See CLI Reference for installation, authentication, and command topics.

SDKs (Python, JavaScript, Go, …)

Official SDKs wrap the HTTP API with idiomatic types, helpers, and error handling for your language. They are distributed as separate repositories (for example Python, JavaScript, and Go clients linked from the docs home).

Best for: long-lived applications, agents, notebooks, and backends that manage sandboxes as part of product logic.

Relationship to the API: SDKs are maintained against the same REST API, but like the CLI they may also switch to direct sandbox-domain access after the backend returns runtime connection details such as sandbox_domain and sandbox-scoped tokens.

How the pieces work together

Architecture summary

Web console / CLI / SDK / custom HTTP → backend control plane → sandbox created and exposed → backend-proxied access and/or direct sandbox-domain access

Typical flow:

1. You authenticate (console session or API key for CLI/SDK/API).
2. You define templates and create sandboxes through whichever surface fits (console click-path, scalebox-cli sandbox create, SDK call, or POST to the API).
3. The control plane provisions and runs your sandbox; you poll or stream status via API/CLI/SDK or watch the console.
4. You then work with the running sandbox either through backend-proxied operations or by connecting directly to the sandbox domain, depending on the interface and the runtime capability you need.

Surfaces are composable: many teams use the console for keys and visibility, the CLI for local iteration, and the API or SDK in production automation.

Getting started

1. Account — Sign up on your ScaleBox instance and open the dashboard to create or copy an API key.
2. Pick a surface — Use the CLI quick start for terminal setup, or choose an SDK from the links on the Guides overview, or call the API directly using API Reference.
3. Create a sandbox — Start from a public template, then explore ports, lifecycle, and advanced topics in the guides and CLI/API docs.

For a feature-focused walkthrough of WebRTC inside sandboxes, see WebRTC in Sandboxes.