Configure the cloud sandbox

Connect Sandock to a local or self-hosted Busabase so AirApps that need Python, a framework, or isolation can run.

Cloud sandbox is an AirApp engine: each run gets a temporary cloud machine from Sandock. Use it when an app needs Python, native dependencies, or a framework like Next.js, or when you would rather not run app processes on your own server.

This message means your Busabase has not been configured yet:

This AirApp requires a cloud sandbox, but Sandock is not configured on this deployment.

All it takes is one API key, and self-hosted installs have no plan limit on it. busabase.com needs no configuration: it is available on Plus and above.

Get an API key

Sign up and sign in at Sandock.
Go to Account Settings → API Keys and click Create New Key.
Copy the key. It is shown only once.

The server running Busabase must be able to reach https://sandock.ai. Visitors' browsers do not need to.

Set the key

Give SANDOCK_API_KEY to the Busabase server process, then restart it. Pick your deployment.

Open source (busabase server)

SANDOCK_API_KEY=your-key busabase server

Open source or all-in-one image (docker run)

Add this to your existing command:

-e SANDOCK_API_KEY=your-key

Compose

Add a line to .env, then recreate the container:

SANDOCK_API_KEY=your-key

docker compose up -d

Helm

Store the key in a Secret, then reference it in values.yaml:

kubectl create secret generic sandock --from-literal=apiKey=your-key

app:
  extraEnv:
    - name: SANDOCK_API_KEY
      valueFrom:
        secretKeyRef:
          name: sandock
          key: apiKey

Keep app.replicaCount: 1 on Helm. A run's state lives in the process that started it, so with several replicas previews fail at random.

Desktop has no setting for this yet.

Optional settings

Variable	Default	What it does
`SANDOCK_BASE_URL`	`https://sandock.ai`	Another Sandock service. Origin only, without `/api/v1`.
`SANDOCK_SPACE_ID`	empty	The Sandock space that holds the sandboxes.
`SANDOCK_IMAGE`	empty	The runtime image.

Check that it works

After restarting, hover over any AirApp in the sidebar, click ···, and choose Settings.
The Engine dropdown should now include Cloud sandbox.
Select it, save, and run the app. Logs show the sandbox being provisioned, npm install, then the start command. A small app shows its preview in about 35 seconds.

Premium needs a valid licence to run apps.

Cost and cleanup

Sandboxes are billed to your Sandock account. Each run gets one machine with 1 CPU core and 1 GB of memory.

Situation	When it stops
You click Stop	Right away
Left open with nobody watching	After about 15 idle minutes
The Busabase server shuts down mid-run	Within 4 hours, when Sandock expires it

Only the person who started a run can see its preview. A cloud sandbox is temporary, so don't use it to serve a public website.

Troubleshooting

What you see	Cause and fix
No Cloud sandbox in the dropdown	The key did not reach the server process, or it has not restarted. A path in `SANDOCK_BASE_URL` does the same.
The server won't start after adding the key, with `Sandock AirApp previews require a shared Redis cache` in the logs	A startup check in older images. Upgrade to the latest image.
Logs stop at provisioning	Check that the server can reach `sandock.ai` and that the key is valid.
Logs show the app started but the preview is blank	Check that the app reads the `PORT` environment variable.