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.

HeaderRegexp

Matches a request by the value of a single HTTP header.

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.

Validator

A validation rule applied to the value entered by the user. Exactly one rule kind must be specified.

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

PortRange

Defines a range of ports.

DNSFilter

RepoCredentialFilter

A rule that controls whether the workload may obtain credentials for accessing a particular source repository. Typically used together with the GitHub App integration to constrain which repos an AI agent may request access tokens for.

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
    repo_credential_filters:
    - repo_url:
      - prefixed: https://github.com/example-org/public-
      # Rules without `block` are allow-rules and stop evaluation.
    - repo_url: []          # Match anything else
      block: true           # Deny credentials for all other repos

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

Interception (including mirroring and cluster networking) is performed independently for each sandbox workload. A single sandbox workload can only target one cluster, but different workloads in the same sandbox can target different clusters by overriding cluster. See Intercepting from Multiple Clusters.

Kubernetes.Workload Example (multiple clusters):

customizations:
- kubernetes:
    plan: dev
    cluster: cluster-1            # default target cluster for the plan
    workloads:
    - kind: Deployment
      name: frontend
      namespace: web
      workload: frontend-dev      # targets cluster-1
    - kind: Deployment
      name: billing
      namespace: billing
      workload: billing-dev
      cluster: cluster-2          # this workload targets a different cluster
      network_namespace: billing  # DNS suffix uses the "billing" namespace in cluster-2

Kubernetes.Workload.PortForward

Forwards traffic for a single port of the intercepted Kubernetes workload to a port on the sandbox workload that replaces it.

Kubernetes.Workload.PortForward Example:

customizations:
- kubernetes:
    plan: dev
    workloads:
    - kind: Deployment
      name: checkout
      namespace: shop
      workload: checkout-dev
      port_forward:
      - port: 80                    # plain HTTP on the K8s side, forwarded to 8080 in the sandbox
        to: 8080
      - port: 443
        to: 8443
        protocol: HTTPS             # K8s side terminates TLS
        dest_protocol: HTTPS        # sandbox workload also serves over TLS
      - port: 9000
        protocol: GRPC              # gRPC over TLS, forwarded to the same port

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.

MCPServer.Auth

Authentication configuration for the MCP server. Currently only token-based authentication is supported.

MCPServer.Auth.Token

Describes how a token is presented and where the token value comes from. Exactly one of login or secret must be specified to provide the token value.

MCPServer.Auth.Login

MCPServer.Auth.Secret

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.

LLMAgent.Exec

Specifies which workload runs the agent and how it is launched.

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.

Process.Spec

Launches a process directly, without a shell. Use it when the command, its environment, and its restart behaviour need precise control.

Process.Identity

Process.RestartPolicy

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.

ServiceProbes.ActivityDetection

Adjusts the built-in activity detection used by Auto Suspension, on top of the activity probes above.

Both lists accept the same session types: ANY, SSH, PORT_FORWARD, EXEC, CLIENT, WEB_TERMINAL, WEB_IDE, RDP, JETBRAINS, ENDPOINT, AGENT. Use ANY to refer to every session type at once — for example, disable ANY and enable only the session types that should keep the sandbox alive.

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

ScheduleSpec.Storage.Engine

A special storage engine backing the persistent layer of the workload. Exactly one backend must be specified.

ScheduleSpec.Storage.Engine.File

The engine setting is captured when the workload is created and is preserved for its whole lifetime. Later changes to engine in the definition are ignored.

workspaces:
- name: dev
  base_snapshot: ubuntu-dev-base
  schedule_spec:
    storage:
      engine:
        file:
          server: shared-files

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.

StringMatcher

A general-purpose rule for matching a string value. Used wherever a list of flexible string predicates is needed (for example, repo_url entries in a Lockdown repo_credential_filters rule).

Exactly one of equals, contains, prefixed, suffixed, pattern, or regexp must be specified.

StringMatcher.Options

StringMatcher Example

- equals: https://github.com/foo/pub        # exact URL
- prefixed: https://github.com/foo/         # all repos under the foo org
- pattern: https://github.com/foo/docs-*    # glob pattern
- regexp: '^https://github\.com/[^/]+/svc-' # regex

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