Merk
Tilgang til denne siden krever autorisasjon. Du kan prøve å logge på eller endre kataloger.
Tilgang til denne siden krever autorisasjon. Du kan prøve å endre kataloger.
Important
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 Azure 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
Your workspace must be in a supported region. See Features with limited regional availability.
To use the SDK, Python 3.10 or above.
To use the Databricks CLI over SSH, install the Databricks CLI and authenticate it with
databricks auth login:databricks auth login # authenticate to a Databricks workspace
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.
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. You can't change this limit.
- You can store up to 10 GB outside your home directory, but this data is deleted when you stop your sandbox. This limit doesn't apply to files under
/Workspaceor/Volumes, which are stored in the workspace or volume. See Access workspace files and volumes.
Access workspace files and volumes
Each sandbox mounts workspace files and Unity Catalog volumes as local directories. Code and agents in the sandbox can read and write these files with standard file tools, such as ls, cp, or Python's open(), without calling the Databricks SDK or Databricks CLI.
| Path | Contents |
|---|---|
/Workspace |
Workspace files, such as /Workspace/Users/<user-name> and /Workspace/Shared. See Programmatically interact with workspace files. |
/Volumes/<catalog>/<schema>/<volume> |
Files in Unity Catalog volumes. See Work with files in Unity Catalog volumes. |
Access to these paths uses a credential that Azure Databricks creates for the sandbox, not the token that you use to call the sandbox. Restrictions on your calling token don't apply to these paths. This credential is separate from the Databricks credential that code in the sandbox uses to call Azure Databricks APIs. Access follows the workspace and Unity Catalog permissions of the sandbox's identity:
- For a sandbox that you create with the Databricks SDK or Databricks CLI, the identity is the user who created the sandbox.
- For the Agent Bricks sandbox tool, the identity is the user who sent the request, or the app's service principal if you configure the tool with
--auth app. See Give an existing agent a sandbox tool to safely execute code.
That identity needs the following permissions:
- Workspace files: Permission to view a workspace file to read it, and permission to edit it to write it.
- Volumes: The
READ VOLUMEprivilege to read files, and bothREAD VOLUMEandWRITE VOLUMEto write files, plusUSE CATALOGandUSE SCHEMAon the parent catalog and schema. See Privileges for Unity Catalog volumes.
Files that you write under /Workspace or /Volumes are stored in the workspace or volume, not in sandbox storage, so they remain after you stop or delete the sandbox.
/Workspace and /Volumes are the only workspace data paths mounted in a sandbox. The DBFS root and cloud storage paths aren't available as local paths in a sandbox.
Networking
There are no restrictions on network egress from a sandbox, and egress is not configurable. Direct ingress to the sandbox's public IP is closed to all traffic, and you can't change this.
Port forwarding
To reach a web server, notebook, or API running in a sandbox from your machine, use port forwarding. Forwarded traffic passes through the workspace instead of using the sandbox's public IP. Only the sandbox owner can forward a port. For instructions, see Forward a port from a sandbox.
Databricks credentials
So that code in a sandbox can call Azure Databricks APIs, each sandbox is provisioned with a Azure Databricks credential that authenticates as the sandbox's identity. For a sandbox that you create with the Databricks SDK or Databricks CLI, that's the user who created the sandbox. For the Agent Bricks sandbox tool, it's the user who sent the request, or the app's service principal if you configure the tool with --auth app. 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 Azure 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.
- Changes outside your home directory do not persist after you stop a sandbox, except for files that you write under
/Workspaceor/Volumes. See Access workspace files and volumes. 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, Azure 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.