Skip to main content
Last updated on

Databricks Sandbox quickstart

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 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 Databricks-managed system.ai.sandbox service, which runs the agent's code in a sandbox for you. You configure only which data the sandbox can access and whether it can write.

To add the tool, run agentbricks tools add sandbox with one or more scopes that limit which data the sandbox can access:

Bash
# Read one table.
agentbricks tools add sandbox --scope table:samples.nyctaxi.trips

# Read a volume and a workspace folder.
agentbricks tools add sandbox --scope volume:main.default.reports --scope workspace:/Workspace/Shared/data

# Allow writes to a volume.
agentbricks tools add sandbox --scope volume:main.default.output --permission read_write

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. By default, the sandbox runs with the permissions of the user who sent the request. To use the app's service principal instead, add --auth app. When you deploy with agentbricks deploy, Agent Bricks grants the app's service principal access to the scoped resources for tools that use --auth app.

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:

    Bash
    pip install --upgrade databricks-sdk

  2. Create a sandbox:

    Python
    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:

    Python
    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:

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

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

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:

Bash
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, 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.

Run Omnigent on a sandbox​

Use this path when you work in Omnigent and want your agent sessions to run on a managed cloud host instead of your laptop. Managed Omnigent can use a sandbox as the host where your agent sessions run. The sandbox keeps running when your laptop is off, and models route through Unity Gateway without API keys.

  1. In your web browser, go to <workspace-url>/omnigent.
  2. Select New session.
  3. Open the host picker and select Sandbox.
  4. Describe a task in the composer and send it to start the session.

For more about hosts and runners, see Omnigent quickstart.

Additional resources​

On this page