Templates

CodeSandbox has default templates that you can use to create sandboxes. These templates are available in the Template Library and by default we use the "Universal" template. To create your own template you will need to use our CLI.

💡

To find inspiration check our template repository on GitHub: https://github.com/codesandbox/sandbox-templates (opens in a new tab)

Creating the template

Create a new folder in your project and add the files you want to have available inside your Sandbox. For example set up a Vite project:

npx create-vite@latest my-template

Now we need to configure the template with tasks so that it will install dependencies and start the dev server. Create a my-template/.codesandbox/tasks.json file with the following content:

{
    // Commands that configures the Sandbox after it has started
    "setupTasks": [
        "npm install"
    ],
    // Tasks that can be controlled by the Sandbox Client
    "tasks": {
        "dev-server": {
            "name": "Dev Server",
            "command": "npm run dev",
            // We have automatic port detection, but configuring
            // this will guarantee the port is assigned on the task
            "preview": {
                "port": 5173
            },
            "runAtStart": true
        }
    }
}

The setupTasks will run after the Sandbox has started, before any other tasks.

💡

Do NOT start dev servers or other long running processes in the setupTasks. This will block the setup process and prevent the Sandbox from starting properly.

Now we are ready to deploy the template to our clusters, run:

$ CSB_API_KEY=your-api-key npx @codesandbox/sdk build ./my-template --privacy private --vm-tier Nano --vm-build-tier Micro --ports 5173

💡

The template defaults to a Micro VM Tier for both building the template and when creating Sandboxes from it. You can not "downsize" Sandboxes when creating them from a template, so make sure you set the minimum tier you want here. It is recommended to make templates private, but they default to "unlisted". Use build --help for documentation on all parameters.

This will start the process of creating Sandboxes for each of our clusters, write files, restart, wait for port 5173 to be available and then hibernate. This generates the snapshot that allows you to quickly create Sandboxes already running a dev server from the template.

When all clusters are updated successfully you will get a "Template Tag" back which you can use when you create your sandboxes.

import { VMTier } from '@codesandbox/sdk'
 
const sandbox = await sdk.sandboxes.create({
    id: 'some-template-id',
    // Defaults to your --vm-tier parameter when building the template
    vmTier: VMTier.Micro
})

CI

If you run the template builder on CI you can pass the --ci flag. This removes the interactive "failed sandbox" behavior and rather creates the template id regardless. The Sandbox that errored will show the error.

Custom Docker Image

CodeSandbox uses Dev Containers (opens in a new tab) for configuring Docker or Docker Compose for an environment. You can configure Docker by creating a .devcontainer/devcontainer.json file inside your template folder with these contents:

{
  "image": "ubuntu:22.04"
}

When we boot the sandbox, we’ll make sure that the docker image is pulled (or built) and we’ll make sure that all shells will start within this container. Your /project/workspace folder will also be mounted inside the container.

💡

There is also a /project/sandbox folder, but consider this deprecated.

You can decide to build the Docker image as part of the template creation process as well. You can do this by defining this in your .devcontainer/devcontainer.json:

{
  "build": {
		"dockerfile": "Dockerfile"
  }
}

And creating a .devcontainer/Dockerfile with the contents of your Dockerfile.

For more options (like running docker compose, or adding additional features), you can look at the Dev Container docs (opens in a new tab).

Setup Tasks vs Dockerfile

When would you configure something in the Dockerfile, and when would you configure something in setup tasks?

As a rule of thumb, if something is configured in relation to the environment (like installing Node, or installing Postgres, or installing Bun), it should go into the Dockerfile. If something is related to the project setup (installing dependencies, building a binary), it should go inside setup tasks.

Pricing Repositories