CodeSandbox Documentation

The Free tier is intended for hobbyists and evaluation. It includes:

• 400 free monthly credits: Used for VM-based resources. For context, this is approximately 40 hours of development on a Nano VM per month.
• 20 Sandboxes: A workspace limit for the entire workspace.

Important Notes:

• Sandboxes vs. VMs: Standard Sandboxes do not run on VMs, so time spent in them does not consume credits.
• Credit Exhaustion: If monthly credits are exhausted before the billing cycle ends, all VM Sandboxes and Repositories will enter a frozen state.

The Pro tier is designed for professional development teams and cloud-based software engineering. It provides a higher baseline of usage and supports customization via add-ons and on-demand credits.

The Pro tier is recommended if you need:

• More than 5 members in your workspace.
• More than 40 hours of VM runtime per month.
• Additional VM storage (per individual VM Sandbox and Repository branch).
• Access to higher VM specifications.
• Unlimited Sandboxes.

The CodeSandbox web editor is a customized version of VS Code for the web. It includes standard VS Code tools in the Activity Bar (File explorer, Search, Source Control, Run and Debug, and the Extension marketplace) and a specialized CodeSandbox Devtool extension for unique platform features.

Key layout components:

• Activity Bar: Standard VS Code tools.
• Devtool Extension: Provides access to CodeSandbox-specific features like Preview ports, Tasks, and Shared Terminals.
• Editor Panels: Standard layout places previews, documentation, and setup tools in the right-side panels.
• Terminal Panel: Displays running tasks, private terminals, and shared terminals.

Sandboxes use different persistence layers that affect how quickly an environment can be resumed:

Default Persistence

When a Sandbox is hibernated, a memory snapshot is created.

• Memory/Disk Snapshot: Resumes in 0.5–2 seconds. Sandboxes are stored on disk for up to 7 days.
• Disk Snapshot: If disk space is limited or after 7 days, Sandboxes may be archived. Resuming from disk takes 5–20 seconds as setup tasks must run.
• Archived: Stored in long-term cold storage. Resuming takes 20–60 seconds.

Managed Persistence (Best Practices)

For complete control and optimal resume times, do not rely solely on VM snapshots. Instead:

1. Persist workspace data to Git or a database.
2. Delete the Sandbox when the user/agent session ends.
3. On resume, recreate the environment from a template and pull data from Git/your database.

In the CodeSandbox SDK, every sandbox is created from a template. When you call sdk.sandboxes.create without providing a specific template ID, the SDK automatically forks the "Universal" template to create your sandbox.

Technically, the SDK forks a snapshot (a hibernated Sandbox). This mechanism allows you to create a base sandbox containing specific dependencies, files, or running servers, which can then be cloned repeatedly to serve as a foundation for new projects.

Storage

Environment variables are stored in a database using AES encryption. The encryption key is stored separately from the database and is rotated periodically on an unannounced schedule.

Access Control

• Visibility: Environment variables are only viewable by users with write access to the project.
• Logging Warning: For public projects (sandboxes or repositories), any user can view the logs of your running tasks. Do not log sensitive information to the console, as it may be exposed in these logs.

Forking Behavior

To prevent credential leakage, environment variables do not travel to forks of VMs. CodeSandbox disables memory snapshotting for clones of VMs containing secrets to ensure this isolation.

Credits are used to measure VM (Virtual Machine) usage. The amount of credits consumed depends on the type of VM used and the duration of runtime.

• Browser Sandboxes: These run in the browser and do not require VMs, so they are free to use and do not consume credits.
• VM Sandboxes: These consume credits based on the VM size (e.g., Nano, Micro, Small) and the time spent working on the project.

Examples of credit consumption:

• A single developer on a Nano VM for 40 hours $\approx$ 400 credits.
• A team of three on a Micro VM for 60 total hours $\approx$ 1200 credits.
• A single developer on a Small VM for 10 hours $\approx$ 400 credits.

Storage limits are applied to the VM disk space of each individual VM Sandbox or Repository branch running in your workspace.

For example, if your subscription tier (such as the Free tier) includes 20 GB of storage, every single VM Sandbox or Repository branch will have its own 20 GB storage limit. If you exceed the storage capacity of your current tier, you must upgrade to a higher Pro tier.