Skip to main content
Last updated on

Databricks Sandbox

Beta

This feature is in Beta. At this time, Databricks does not charge for usage for this feature.

Databricks Sandbox is a compute environment for humans and agents, accessible over SSH, running in the Databricks serverless compute plane.

The sandbox allows you to:

  • Create a persistent development sandbox you can access over SSH. Run longer agent tasks without needing your local machine to be active.
  • Run a coding agent in a secure, sandboxed environment:
    • Drive your coding agent directly from the Databricks CLI over SSH
    • Connect to a desktop IDE or agent harness like Cursor, Claude or Codex.
  • Spin up short-lived environments for sub-agents, experiments, or agent-authored programs. Use this with MCP, or when building custom agents with the Supervisor API or Custom Agents on Apps.

Why should I use Databricks Sandbox?​

  • Databricks-native governance

    • Runs in the Databricks serverless compute plane. Data on your Databricks Sandbox stays within your workspace governance boundary.
    • Seamless integration with AI Gateway for governed LLM inference and MCP calls.

  • Built for running agents

    • Starts in seconds. Create fresh environments for experiments, sub-agents, or isolated tasks, and throw them away when you're done.
    • Storage persists across sessions. Install your tools and config once, stop the Databricks Sandbox, and reconnect later to the same filesystem and state.
    • Run concurrent sessions on one instance. Open multiple SSH sessions to one Databricks Sandbox over a shared filesystem. An agent can work on a task in one session while you tail logs or edit files in another, all on the same instance.

Prerequisites (CLI)​

To create and use a Databricks Sandbox with the Databricks CLI, you must:

  1. Install the Databricks CLI on your local machine.

  2. Authenticate the Databricks CLI using databricks auth login:

Bash
databricks auth login  # authenticate to a Databricks workspace
note

Sandboxes can be launched automatically by other products, including Supervisor API.

Create a sandbox (CLI)​

To create a Databricks Sandbox using the Databricks CLI, run the following commands:

Bash
databricks sandbox create      # create your sandbox
databricks sandbox register    # optional: register SSH keys
databricks sandbox ssh         # SSH to your default sandbox

When you SSH into your sandbox, the Databricks CLI is installed and authenticated to the Databricks workspace where your sandbox is running. You may also want to configure git credentials. See Connect your Git provider to Databricks.

For detailed command help, run databricks sandbox -h, or see sandbox command group.

Run a coding agent​

Databricks recommends using ucode, the Unity AI Gateway Coding CLI, to run a coding agent. With ucode, you can set up your preferred agent harness to use AI Gateway. Run ucode configure for setup.

  • Use the CLI directly: SSH from your terminal. Use ucode to drive the coding agent of your choice for AI Gateway integration.
  • Connect desktop apps over SSH: See the instructions for using Claude, Codex, or Visual Studio Code or Cursor.
  • Run a web UI: For example, run OpenCode web and connect to it from your local machine using SSH port forwarding.

Data persistence​

warning

Storage during Beta is not persistent and may be deleted.

Databricks Sandbox comes with network-attached storage. Performance is similar to typical cloud offerings.

  • You can start many concurrent SSH sessions to one Databricks Sandbox, and they all see the same file system.
  • Data in your home directory (/home/sandbox-agent) persists for the lifetime of your Databricks Sandbox. Even after stopping your Databricks Sandbox, 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.
  • Data outside your home directory is deleted if you stop your sandbox. You can store up to 10 GB outside your home directory.

Usage costs​

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

  • Runtime compute, billed hourly while your Databricks Sandbox is running. Exact rates are to be determined.
    • Storage outside your home directory is included as part of the runtime compute cost of the Databricks Sandbox.
  • Persistent storage in your home directory, at rates similar to default 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. Stopping your Databricks Sandbox does not stop billing for storage.
  • Data transfer at existing rates.

Limitations​

  • Does not yet integrate with serverless egress controls. Do not use Databricks Sandbox in a workspace with (SEG) enabled. For more information about serverless egress controls, see What is serverless egress control?.

  • Tech specs: 4 cores, 16 GB RAM, up to 100 GB storage. This currently cannot be changed, but Databricks plans to offer larger instance types in the future.

  • Maximum 40 sandboxes per user. Maximum 100 sandboxes per workspace.

  • Only available in the following regions:

    • AWS us-east-1
    • AWS us-west-2
    • AWS eu-west-1
    • AWS ap-southeast-1
    • AWS ap-south-1

  • Public IP addresses of your Databricks Sandbox may change at any time.

  • This is a beta release. Data stored in your home directory will be deleted when the beta period is over. Do not store anything you are not comfortable losing.

  • There is no native way to persist environments outside of the home directory, or to customize your environment at startup time. However, you can persist any needed packages or configuration in your home directory.

On this page