Sandbox

A Sandbox is a self-contained, isolated environment for developing and running a modern cloud application end-to-end.

Definition

A sandbox is defined with multiple components listed together in a YAML definition. For example:

overview: the optional overview of the sandbox.
env:
- KEY=VALUE
endpoints:
- name: ...
  ...
workspaces:
- name: ...
  ...
dependencies:
- name: ...
  service_type: ...
  ...
containers:
- name: ...
  image: ...
  ...
customizations:
- ...

The definition describes all the workloads that form the environment, the network endpoints that expose services externally, environment variables shared across workloads, and customization policies.

Overview

overview is an optional markdown document that is rendered at the top of the details view of a template or a sandbox.

The content supports templating with variable substitution. For example:

Sandbox Notes

Sandbox name {{sandbox.name}}
Last updated {{sandbox.updatedAt}}
Owner {{sandbox.owner}}
Template {{sandbox.template}}

For unknown variable, we display {{unknown}}

is rendered as:

Sandbox Notes

Sandbox name sandbox-name
Last updated 2022-01-01
Owner sandbox-user
Template example-template

For unknown variable, we display 

An unknown variable is substituted with an empty string.

The supported substitution variables are:

Note: the variables marked as Supported in the Org column can also be used in the onboarding message from the org settings.

Workloads

Workloads are the runtime units inside a sandbox. They must be scheduled and run on a host machine which provides CPU, memory, networking, and storage resources.

There are multiple types of workloads for different purposes.

Workspaces

Workspaces are the main working spaces for developers. A workspace is created based on a container image (called a base snapshot), with changed files stored in a writable delta layer on top of the read-only layers from the base image. The developer has root privilege and full access to the file system, including the ability to install any software.

A workspace has special capabilities:

• An automated start-up sequence covering:
  • System and home directory customization
  • Personalization
  • Source code checkout
  • Build tasks
  • Daemon launch
• Management of background processes called Daemons
• Management of cron jobs called Jobs
• A built-in WebIDE
• A built-in SSH server
• Access to Crafting-specific runtime information
• Access to Secrets

See Workspace Automation for full details on the start sequence, checkouts, and daemons.

Dependencies

Dependencies are commonly used services such as databases, message queues, and caches. They are built-in and pre-configured for development use, and in most cases can be used directly with minimal or no configuration.

For example:

dependencies:
- name: mysql
  service_type: mysql
  version: '8.3'
  properties:
    database: myapp
    username: foo
    password: bar

Field reference:

• name: the name of the dependency, also used as its hostname within the sandbox. Must conform to DNS-1123 naming conventions.
• service_type: the type of service. Use cs depsvc list or the Web UI to find available service types.
• version: an optional specific version. If omitted, a default version is used.
• properties: service-specific configuration options. All are optional; defaults are applied based on service type.

Container

Beyond built-in dependency services, any Docker container image can be included in a sandbox for specific functionality. For example:

containers:
- name: sqlpad
  image: sqlpad/sqlpad:latest
  env:
  - 'SQLPAD_AUTH_DISABLED=true'
  - 'SQLPAD_AUTH_DISABLED_DEFAULT_ROLE=admin'
  - 'SQLPAD_CONNECTIONS__mysql__name=mysql'
  - 'SQLPAD_CONNECTIONS__mysql__driver=mysql2'
  - 'SQLPAD_CONNECTIONS__mysql__host=mysql'
  - 'SQLPAD_CONNECTIONS__mysql__database=app'
  - 'SQLPAD_CONNECTIONS__mysql__username=root'
  - 'SQLPAD_DEFAULT_CONNECTION_ID=mysql'
  wait_for:
  - mysql

Unlike the common container runtime behavior, Crafting containers persist their full root filesystem by default. To opt out of persistence, specify volatile: true in the container definition.

Networking

Each sandbox has a private network connecting all its workloads together. Workloads can communicate with each other directly using their hostname (the same as the workload name), assigned private IPs, or hostname aliases specified via the hostnames field.

The networks of different sandboxes are completely isolated and inaccessible to each other.

Each workload has one external network interface (eth0). A port listened on this interface can be accessed by other workloads in the same sandbox using the hostname. Ports can also be exposed to the external network via an Endpoint.

For example, given this sandbox definition:

endpoints:
- name: app
  http:
    routes:
    - path_prefix: /
      backend:
        target: dev
        port: web
workspaces:
- name: dev
  ports:
  - name: web
    port: 8080
    protocol: HTTP/TCP
  ...
dependencies:
- name: mysql
  service_type: mysql

From the dev workspace, the MySQL database is accessible directly by hostname — for example: mysql -h mysql ...

Port 8080 is exposed as a backend of an endpoint, so accessing https://app--sandbox-org.sandboxes.run will route traffic to that port (assuming sandbox name sandbox and org name org).

Outbound network access is allowed via NAT. Access to specific IP ranges can be configured during deployment. See Sandbox Networking for more details.

Storage

Each workload has dedicated persistent storage. Crafting containers persist their full root filesystem by default (unlike typical container runtimes), so files are preserved across restarts and rescheduling.

For workspaces, the root filesystem is restored from the base snapshot plus the delta layer of changed files. The home directory (/home/owner) is not included in the base snapshot, because it contains sensitive information such as credentials, personalized configurations, source code, and build outputs that should not be shared with other members.

The home directory can be restored separately using a home snapshot, which captures an explicit list of directories and files. On top of that, a personal home snapshot (a special type of home snapshot) can be unpacked to restore personalized files for the current sandbox owner.

See Workspace Snapshots for full details.

Placement

The workloads in the same sandbox can be scheduled on different nodes. The private network is an overlay network layered on top of the physical network connecting those nodes.

See Also

• Template — reusable sandbox definitions
• Snapshot — filesystem state capture and restore
• Endpoints — exposing services externally
• Sandbox Networking — networking details
• Workspace Automation — start sequences and automation
• Lifecycle — sandbox lifecycle events