Skip to main content
Last updated on

Databricks Sandbox

Beta

This feature is in Beta. To enable this feature preview in the workspace, opt into the Databricks Sandbox setting in the workspace Previews page. See Manage Databricks previews.

Databricks Sandbox lets you run untrusted code in an isolated environment through the Databricks REST API, SDK, or Databricks CLI. The sandbox provides serverless, on-demand compute for running code dynamically.

Each sandbox includes a persistent home directory. You can stop and start a sandbox at any time, and the data in your home directory persists.

The sandbox is ideal for:

  • Running an agent harness.
  • Executing user-written or AI-written code.
  • Running background tasks or workers.
  • Launching interactive IDE or SSH sessions.

Prerequisites​

Get started​

To create a sandbox and run code in it, see Databricks Sandbox quickstart. The quickstart covers each way to use a sandbox:

  • A sandbox tool for agents that you build with the Agent Bricks CLI.
  • The Databricks SDK for Python, the recommended way to work with sandboxes from code.
  • The Databricks CLI, to connect to a sandbox over SSH.
  • Omnigent, which can use a sandbox as the host for agent sessions.

Compute size​

Databricks Sandbox comes with 4 vCPUs and 8 GB of RAM. This size is not configurable.

Storage​

warning

At the end of the Beta period, Databricks might perform a one-time purge of data stored in sandboxes. Do not store anything you cannot afford to lose.

Databricks Sandbox comes with network-attached storage.

  • Data in your home directory (/home/sandbox-agent) persists for the lifetime of your Databricks Sandbox. Even after stopping your Databricks Sandbox, the data in your home directory is available when you start your next session.
  • Your home directory can store up to 100 GB. At this time, this cannot be changed.
  • You can store up to 10 GB outside your home directory, but this data is deleted when you stop your sandbox.

Networking​

There are no restrictions on network egress from a sandbox, and egress is not configurable.

Databricks credentials​

So that code in a sandbox can call Databricks APIs, each sandbox is provisioned with a Databricks credential that authenticates as the user who created the sandbox. Each token in the credential is valid for 1 hour and is refreshed automatically before it expires. Refreshing continues for up to 24 hours, after which the credential expires. This credential lifetime is separate from the 24-hour runtime limit. The credential doesn't depend on your sign-in session, so it keeps working if you sign out or your own token expires.

The credential is saved as the DEFAULT profile in ~/.databrickscfg, so the Databricks SDK and the Databricks CLI in the sandbox use it automatically.

Custom images​

You can create a sandbox from your own container image stored in Artifact Registry, so every sandbox starts with your packages, tools, and configuration already installed. See Create a sandbox from a custom image.

Usage costs​

Databricks does not currently charge for usage of this feature. However, cost and pricing for features in Beta are subject to change.

For complete billing usage information, see Databricks pricing. Databricks anticipates billing sandbox usage for:

  • Runtime compute: Billed hourly while your Databricks Sandbox is running.
  • Persistent storage: You are billed for the data stored in your home directory until your Databricks Sandbox is deleted. Storage incurs billing as long as the Databricks Sandbox instance exists. To stop paying for storage, you must delete the sandbox.
  • Data transfer

Limitations​

  • Quotas are enforced. By default, you can have at most 200 active sandboxes per user (800 total across all states), and a workspace can have at most 400 active sandboxes (2,000 total). To request an increase, contact your Databricks account team. See Resource limits.
  • You cannot connect over SSH to a sandbox that you create with the Databricks SDK. To connect over SSH, create the sandbox with the Databricks CLI. See Use the Databricks CLI to create a sandbox.
  • Databricks Sandbox is a compute primitive for running code, not a general-purpose Spark runtime. For Spark workloads, use Connect to serverless compute.
  • The public IP addresses of your Databricks Sandbox can change at any time. The default ingress of the sandbox is closed to all traffic, and you can't change this.
  • Changes outside your home directory do not persist after you stop a sandbox. To start every sandbox with the same packages and configuration, use a custom image. See Create a sandbox from a custom image. To reuse files across sessions of one sandbox, store them in your home directory.
  • A sandbox can run for at most 24 hours after each start. After 24 hours, Databricks stops the sandbox, including any running commands and background processes. This limit applies even when inactivity auto-stop is turned off with --no-autostop, and you can't extend it through the Databricks CLI or API. To continue, start the sandbox again, which begins a new 24-hour period. The data in your home directory is kept.
On this page