Sandbox Definition

A Sandbox Definition is a YAML document that describes the complete topology of a Sandbox: its workloads, networking endpoints, shared volumes, external resources, and customization policies.

The definition is the authoritative source of truth for everything inside a sandbox. It is stored in a Template or directly in a sandbox, and can be edited at any time through the Web Console or the CLI (cs sandbox edit).

Structure Overview

overview: Optional markdown description shown in the Web Console.

env:
- KEY=VALUE             # Shared environment variables

volumes:
- name: ...             # Named volumes shared across workloads

endpoints:
- name: ...             # External-facing HTTP or TCP endpoints

workspaces:
- name: ...             # Developer workspaces

dependencies:
- name: ...             # Managed services (MySQL, Postgres, etc.)

containers:
- name: ...             # Custom Docker containers

resources:
- name: ...             # External cloud resources

customizations:
- flavor: ...           # Flavors, lockdown, MCP, LLM agent, etc.

The name field of every workload — workspace, dependency, or container — must be unique across the entire definition, regardless of type. Endpoints use a separate namespace.

Top-Level Fields

Environment Variables Example

env:
- APP_ENV=development
- DATABASE_URL=postgres://db:5432/app
- LOG_LEVEL=debug
- FULL_PATH=/opt/app/bin:${PATH}   # Expansion supported

Environment variables defined here are injected into all workloads in the sandbox. Individual workloads can also define their own env entries, which are appended after these.

Workspace

A Workspace is the primary Linux environment for a developer. It has a full root filesystem, a built-in SSH server and WebIDE, support for source code checkouts, automated builds, background daemons, and cron jobs.

See Workspace Automation for full details on the start sequence.

Workspace Example

workspaces:
- name: dev
  base_snapshot: ubuntu-dev-base
  home_snapshot: team-home
  ports:
  - name: web
    port: 8080
    protocol: HTTP/TCP
  - name: api
    port: 9000
    protocol: HTTP/TCP
  env:
  - NODE_ENV=development
  wait_for:
  - mysql
  checkouts:
  - path: app
    repo:
      git: git@github.com:example-org/app
    manifest:
      overlays:
      - inline:
          hooks:
            post-checkout:
              cmd: npm install
            build:
              cmd: npm run build
          daemons:
            server:
              run:
                cmd: npm start

In this example, the dev workspace:

1. Starts with the ubuntu-dev-base root filesystem snapshot.
2. Waits for mysql to be ready before proceeding with its start sequence.
3. Checks out app into ~/app.
4. Runs npm install after checkout, then npm run build.
5. Launches npm start as a persistent daemon after the build succeeds.
6. Exposes port 8080 as web and port 9000 as api for use in endpoints.

Workspace.System

System-level configuration injected at workspace startup.

File Injection Example

workspaces:
- name: dev
  system:
    files:
    - path: /etc/sandbox.d/setup
      mode: '0755'
      overwrite: true
      content: |
        #!/bin/bash
        echo "Configuring system..."
        apt-get install -y my-tool
    - path: ~/.config/app/config.yaml
      mode: '0644'
      template: |
        user: {{env "$SANDBOX_OWNER_EMAIL"}}
        token: {{secret "api-token"}}

Workspace.Lifecycle

Hooks that run during sandbox lifecycle transitions for this workspace. See Lifecycle for full details.

Lifecycle.Handler

Workspace.Restriction

Controls Restriction Mode, which blocks non-admin access to this workspace and mounts Admin Only secrets. See Restriction Mode for full details.

Dependency

A managed service (such as a database or cache) that is pre-configured for development use. Dependencies are accessible to all workloads in the sandbox via their name as a hostname.

Dependency Example

dependencies:
- name: mysql
  service_type: mysql
  version: '8.3'
  properties:
    database: myapp
    username: app
    password: secret
- name: cache
  service_type: redis
  version: '7'

Both mysql and cache are accessible from any workspace directly by hostname:

mysql -h mysql -u app -psecret myapp
redis-cli -h cache

Container

A workload launched from any Docker container image. Unlike typical container runtimes, Crafting containers persist their root filesystem by default — files survive restarts unless volatile: true is set.

Container Example

containers:
- name: sqlpad
  image: sqlpad/sqlpad:latest
  env:
  - SQLPAD_AUTH_DISABLED=true
  - SQLPAD_CONNECTIONS__mysql__name=MySQL
  - SQLPAD_CONNECTIONS__mysql__driver=mysql2
  - SQLPAD_CONNECTIONS__mysql__host=mysql
  - SQLPAD_CONNECTIONS__mysql__database=myapp
  - SQLPAD_CONNECTIONS__mysql__username=app
  wait_for:
  - mysql
- name: docs
  image: nginx:alpine
  volatile: true          # Reset on every restart
  volume_mounts:
  - name: docs-content
    path: /usr/share/nginx/html

The sqlpad container automatically connects to the mysql dependency using its hostname. It waits for MySQL to be ready before starting. The docs container is stateless — its filesystem resets to the base image on each restart.

Endpoint

Endpoints expose workload ports to the external network. Each endpoint is assigned a DNS name and is accessible via HTTPS (HTTP endpoints) or TLS (TCP endpoints). See Endpoints for full details.

HTTPRouter

HTTPRoutingRule

Each rule routes requests matching a path pattern to a backend workload. Exactly one of path_prefix, path, or header_regexp must be specified.

TCPRouter

AuthProxy

Controls who can access an HTTP endpoint.

AuthProxy.Rule

Rules are evaluated in order. The first matching rule's action determines the outcome.

AuthProxy.Passthrough

Endpoint Examples

HTTP endpoint with path-based routing:

endpoints:
- name: app
  http:
    routes:
    - path_prefix: /api
      backend:
        target: dev
        port: api
    - path_prefix: /
      backend:
        target: dev
        port: web
    path: /dashboard         # Browser opens this path by default
    request_headers:
      X-Foo: Bar

HTTP endpoint open to external users:

endpoints:
- name: preview
  http:
    routes:
    - path_prefix: /
      backend:
        target: frontend
        port: http
    auth_proxy:
      rules:
      - action: ACCEPT
        pattern: '*@partner.com'
      - action: REJECT
        pattern: 'blocked@partner.com'

The blocked@partner.com rule is evaluated first (rules run in order), so that address is rejected even though it matches *@partner.com.

Internal endpoint (accessible only within the org's sandboxes):

endpoints:
- name: internal-api
  type: INTERNAL
  http:
    routes:
    - path_prefix: /
      backend:
        target: backend
        port: api
    auth_proxy:
      disabled: true

TCP endpoint with TLS passthrough:

endpoints:
- name: db
  tcp:
    backend:
      target: dev
      port: postgres
    tls_passthrough: true

Volume

Named volumes that can be mounted into workspaces and containers. Volumes must be declared here before they can be referenced in a volume_mounts entry.

Each volume must specify exactly one source: content, secret, or workload.

Volume.Content

Volume.Secret

Volume.Workload

VolumeMount

A mountpoint declaring where a volume should appear in a container's filesystem.

VolumeMount.VolumeFrom

Exactly one of volume_name or volume must be specified.

ResourceGroup

External resources whose lifecycle is tied to the sandbox — for example, cloud infrastructure provisioned via Terraform or custom scripts. See External Resources for full details.

Each ResourceGroup must specify exactly one of handlers or terraform.

ResourceGroup.Handlers

Each handler field is an ExecHandler.

ExecHandler

ExecHandler.UseWorkspace:

ResourceGroup.Terraform

Terraform.Exec

ResourceGroup Example

resources:
- name: aws
  brief: AWS infrastructure for this sandbox
  terraform:
    workspace: dev
    dir: infra/aws
    require_build: true
    run:
      max_retries: 3
      timeout: 1800s
      vars:
        sandbox_id: '$SANDBOX_ID'
    save_state: true
- name: k8s-deploy
  wait_for:
  - aws
  handlers:
    on_create:
      use_workspace:
        name: dev
        run:
          dir: infra/k8s
          cmd: kubectl apply -f manifests/
    on_delete:
      use_workspace:
        name: dev
        run:
          dir: infra/k8s
          cmd: kubectl delete -f manifests/ || true
    on_suspend:
      use_workspace:
        name: dev
        run:
          cmd: kubectl scale --replicas=0 deploy --all -n sandbox-${SANDBOX_ID}
    on_resume:
      use_workspace:
        name: dev
        run:
          cmd: kubectl scale --replicas=1 deploy --all -n sandbox-${SANDBOX_ID}

Here, k8s-deploy waits for aws to complete (using wait_for), so AWS infrastructure is always provisioned before the Kubernetes deployment begins.

Customization

Customizations allow advanced configuration of a sandbox or template. Each entry in the customizations list must specify exactly one type.

Flavor

A Flavor is a named preset that overrides parts of the sandbox at creation time. Users can select a flavor when creating a sandbox to get a specific configuration. See also Customization.

Flavor.Workspace:

Flavor.Workspace.Checkout:

Flavor Example:

customizations:
- flavor:
    name: frontend-only
    description: Only the frontend workspace; no backend services.
    env:
    - DISABLE_BACKEND=true
    excludes:
    - backend
    - mysql
    workspaces:
      frontend:
        checkouts:
        - path: ui
          version_spec: next
- flavor:
    name: full-stack
    description: All services running end-to-end.
    default: true

Env (Customization)

Exposes an environment variable defined in the top-level env list as a configurable field in the sandbox creation UI.

StringChoice:

Customization Env Example:

env:
- REGION=us-east-1

customizations:
- env:
    name: REGION
    display_name: AWS Region
    description: The AWS region where sandbox resources will be provisioned.
    choice:
      options:
      - us-east-1
      - us-west-2
      - eu-west-1
      default: us-east-1

Lockdown

Applies security hardening policies to selected workloads. See Lockdown for full details.

IPFilter:

DNSFilter:

Lockdown Example:

customizations:
- lockdown:
    apply_to:
    - agent-*
    allow_api_access: false
    allow_ssh_keypair: false
    accessible_secrets:
    - github-token
    outbound_ip_filters:
    - cidrs:
      - 0.0.0.0/0
      ports:
      - 22
      block: true           # Block all outbound SSH
    dns_filters:
    - names:
      - '**.internal.corp'
      block: true           # Block resolution of internal corporate DNS

Kubernetes

Defines a Kubernetes interception plan for routing traffic between the sandbox and a connected Kubernetes cluster. See Kubernetes Dev Experience for full details.

Kubernetes.Workload:

Kubernetes.Ingress:

Kubernetes.InterceptCondition:

Detach Env

Detaches sandbox-specific and owner-specific information from the environment inside the sandbox. This allows pooled sandboxes to keep their processes running while in STANDBY state, enabling instant availability when claimed.

When enabled:

• SANDBOX_* environment variables for sandbox name, folder, and owner are not injected.
• Git user configuration is not set (so git push will not work until manually configured).

MCP Server

Declares that this sandbox exposes an MCP (Model Context Protocol) server, making it discoverable for authorization as an org-level MCP server. See MCP Servers for full details.

MCP Server Example:

endpoints:
- name: mcp
  type: INTERNAL
  http:
    routes:
    - path_prefix: /
      backend:
        target: dev
        port: mcp
    auth_proxy:
      disabled: true

customizations:
- mcp_server:
    endpoint: mcp
    protocol: SSE

LLM Agent

Declares that this sandbox or template can be used as an LLM agent. See Agentic Sessions for context.

Property Set

Defines opaque key/value pairs used to activate external functionality. The type field identifies which functionality should react to this property set.

Settings Override

Applies named org-level settings overrides to the sandbox.

Checkout

A checkout declares a source code repository that a workspace automatically clones and manages.

Checkout.Repo

Exactly one of git or github must be specified.

Checkout.Repo.GitHub:

Checkout.History

Limits the amount of git history fetched, useful for large repositories.

Checkout.Manifest

Defines the automation configuration for a checkout. When overlays is specified, the default .sandbox/manifest.yaml file in the repository is ignored.

Checkout.Manifest.Overlay

Exactly one of file, content, or inline must be specified.

Repo.Manifest

The manifest defines the automation that runs inside a checkout: hooks, daemons, jobs, commands, and tests.

Run

The run schema is used by hooks, daemons, jobs, and lifecycle handlers.

Repo.Daemon

Repo.Job

Manifest Example

checkouts:
- path: app
  repo:
    git: git@github.com:example-org/app
  manifest:
    overlays:
    - inline:
        env:
        - NODE_ENV=development
        hooks:
          post-checkout:
            cmd: npm install
          build:
            cmd: npm run build
        daemons:
          server:
            run:
              cmd: node dist/server.js
              env:
              - PORT=8080
        jobs:
          cleanup:
            run:
              cmd: ./scripts/cleanup.sh
            schedule: '0 3 * * *'   # Every day at 3am

GlobalProcess

A system-level background process (daemon) launched as root before checkout tasks run. Defined under workspace.system.daemons.

Exactly one of run or spec must be specified.

SetupFile

A file to inject into the workspace filesystem on every startup (after snapshots are applied). Defined under workspace.system.files.

Exactly one of content, template, symlink, or secret must be specified.

SetupFile.Secret:

PortSpec

Declares a port exposed by a workload (workspace or container).

TargetPort

References a named port on a workload, used in endpoint backends and port-forward rules.

PortForwardRule

Maps a remote address to a local address inside a workspace, enabling direct access to sandbox services from the developer's local machine.

ServiceProbes

Defines health, readiness, and activity probes for a workload.

Probe

Each probe must specify exactly one check method: command, tcp_port, or http_get.

Probe.HttpGet:

Probe Example

containers:
- name: api
  image: myapp/api:latest
  ports:
  - name: http
    port: 8080
    protocol: HTTP/TCP
  probes:
    readiness:
    - http_get:
        port: 8080
        path: /healthz
      interval: 5s
      positive_threshold: 2
      negative_threshold: 3
      initial_delay: 10s
    health:
    - tcp_port: 8080
      interval: 30s
      negative_threshold: 3

ScheduleSpec

Controls which node pool a workload is scheduled on and what resources it requests. See Schedule Specification for full details.

This feature is only available in Crafting Enterprise Edition.

ScheduleSpec.PoolSelector:

ScheduleSpec.ResourceRequest:

ScheduleSpec.Storage:

ScheduleSpec.Storage.LocalDisk:

UserContext

Specifies user and/or group identity for running a container process.

Exactly one of uid or user (and optionally one of gid or group) must be specified.

See Also

• Sandbox — sandbox concepts and workload types
• Template — reusable sandbox definitions
• Workspace Automation — start sequence, checkouts, daemons, and jobs
• Endpoints — exposing services externally
• Lifecycle — sandbox lifecycle events and hooks
• External Resources — cloud resource provisioning
• Lockdown — security hardening for workloads
• Restriction Mode — admin-only access during startup
• Schedule Specification — node pool and resource requirements
• Readiness and Wait For — coordinating workload startup
• MCP Servers — exposing MCP servers from a sandbox
• Agentic Sessions — LLM agent sessions