Databricks Sandbox quickstart

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 runs code in an isolated, serverless environment, so agents can safely run the code they write. You can use a sandbox from an agent, from Python code, or from a terminal. Each of the following paths works on its own, so choose the one that matches how you work:

For an overview of Databricks Sandbox, including compute size, storage, and limitations, see Databricks Sandbox.

Requirements

Give an existing agent a sandbox tool to safely execute code

Use this path when you build your agent with the Agent Bricks CLI and want the agent to run the code it writes, such as data analysis in Python, without that code running in the agent's own environment.

You don't create a sandbox first. The sandbox tool connects your agent to the Azure Databricks-managed system.ai.sandbox service, which runs the agent's code in a sandbox for you.

To add the tool, run the following command in your agent project:

agentbricks tools add sandbox

The command records the tool in the project's agent.toml, and the agent calls the sandbox at runtime through the system.ai.sandbox MCP service. Code in the sandbox runs with the Unity Catalog permissions of the tool's identity. By default, that identity is the user who sent the request. To use the app's service principal instead, add --auth app, and grant the service principal access to the data that the agent's code needs.

Use the Python SDK to create a sandbox

Use this path when you want to create sandboxes and run commands in them from your own Python code, such as an application or a custom agent that manages its own sandboxes. The Databricks SDK for Python is the recommended way to work with sandboxes from code.

  1. Install or upgrade the SDK:

    pip install --upgrade databricks-sdk
    
  2. Create a sandbox:

    from databricks.sdk import WorkspaceClient
    from databricks.sdk.service.sandbox import Sandbox
    
    w = WorkspaceClient()
    
    created = w.sandbox.create_sandbox(
        sandbox=Sandbox(),
        sandbox_id="my-sandbox",
    )
    print(created.name)   # "sandboxes/my-sandbox"
    
  3. Run a command in the sandbox. The command runs directly, without a shell, so to run a shell command, call /bin/bash -c:

    from google.protobuf.duration_pb2 import Duration
    
    resp = w.sandbox.execute_command_sync(
        "sandboxes/my-sandbox",
        "/bin/bash",
        args=["-c", "echo hello world && whoami"],
        execution_timeout=Duration(seconds=30),
    )
    print(resp.exit_code)   # 0
    print(resp.stdout)      # "hello world\nsandbox-agent\n"
    
  4. Delete the sandbox when you're done. Deleting a sandbox removes its home directory and stops billing for it:

    w.sandbox.delete_sandbox("sandboxes/my-sandbox")
    

To get, list, update, stop, and restart sandboxes, see Create and manage sandboxes with the SDK.

Note

You cannot connect over SSH to a sandbox that you create with the Databricks SDK. To work in a sandbox interactively from a terminal or IDE over SSH, create it with the Databricks CLI instead. See Use the Databricks CLI to create a sandbox and databricks sandbox ssh.

Use the Databricks CLI to create a sandbox

Use this path when you want to work in a sandbox interactively from a terminal. Connect to a sandbox over SSH to run longer agent tasks without keeping your local machine active. For example, you can drive a coding agent from the Databricks CLI, or connect a desktop IDE or an agent harness such as Cursor, Claude, or Codex.

To create a sandbox and connect to it, run:

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

When you connect, the Databricks CLI in the sandbox is installed and authenticated to the workspace where the sandbox runs. If your workspace has Unity Gateway configured, Azure Databricks also configures common coding harnesses, such as Claude and Codex, to use it the first time you connect. See Create a custom model service . To use Git from the sandbox, configure Git credentials. See Connect your Git provider to Databricks.

For all commands, run databricks sandbox -h, or see sandbox command group.

Tip

To run Claude Code or Codex in the same environment as your workspace code and data, use the SSH tunnel to serverless compute or a dedicated cluster instead. The agents are preconfigured for Unity Gateway. See Run coding agents in an SSH session.

Additional resources