SDK
Key Terms

Key Terms

Terminology and definitions used throughout the CodeSandbox SDK.

Authentication

  • API Key: Authentication token required to use the CodeSandbox SDK. Created at https://codesandbox.io/t/api (opens in a new tab) and exposed as CSB_API_KEY environment variable.

  • Session: Authentication and connection context that allows client applications to interact with sandboxes directly.

  • Host Token: Authentication token required to access hosts of private sandboxes. Provides secure access to sandbox ports and services.

Development environments

  • Firecracker VM: The virtualization technology that powers each sandbox, providing complete isolation and security for running untrusted code.

  • Sandbox: An isolated, persistent virtual environment backed by a Firecracker Virtual Machine(VM) where code can be executed securely.

  • Template: Pre-configured environment specification that enables quick sandbox creation with specific setups, dependencies, and configurations.

  • VM Tier: Computing resource specification for sandboxes, ranging from Micro to Small (8 cores/16GB RAM) with higher tiers available through custom templates.

  • DevContainer: Container configuration system used by CodeSandbox for environment setup. Uses .devcontainer/devcontainer.json for configuration.

  • Workspace: The persistent working directory (/project/workspace) where sandbox files are stored and managed with git-based persistence.

Connections

  • Hosts: The publicly accessible URLs where sandbox services are exposed, following the pattern https://$SANDBOX_ID-$PORT.csb.app.

  • Ports: Network endpoints exposed by sandbox services. Automatically detected or manually configured in task definitions.

  • Client: A connection object that provides methods to interact with a sandbox, including file system operations, command execution, and terminal management.

  • Browser Client: A client connection that runs in a web browser environment, allowing interaction with sandboxes from frontend applications.

  • Node Client: A client connection designed for Node.js-like environments, such as React Native applications.

Interactions

  • Terminal: Interactive shell process that persists throughout a session, allowing command-line interaction with the sandbox environment.

  • Commands: Interface for running shell commands in a sandbox. Commands clean themselves up after execution, unlike terminals which persist.

  • Tasks: Long-running processes defined in sandbox configuration, such as development servers. Managed through the Tasks API with start, stop, and restart capabilities.

  • Setup Tasks: Commands that run automatically after a sandbox starts, typically used for dependency installation and initial configuration.

  • Forks: A new sandbox created from an existing sandbox.

  • Live Forks: Sandboxes created from a currently running sandbox, which is slower than forking from templates or hibernated sandboxes.

Lifecycle

  • Hibernation: Automatic suspension of sandbox execution after a specified timeout period. Sandboxes can be resumed later while preserving their state.

  • Resume: Resumes a hibernated sandbox, restoring it to an active state while preserving all previous work and configurations.

  • Snapshots: Disk/Memory snapshot that is generated when hibernating a Sandbox and consumed when resuming a Sandbox.