Skip to main content
Last updated on

Create and manage sandboxes with the SDK

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 does not currently charge for usage of this feature. However, cost and pricing for features in Beta are subject to change.

The Databricks SDK for Python includes a sandbox client for creating sandboxes, running commands in them, and managing their lifecycle. This page walks through those operations. For an overview of Databricks Sandbox, see Databricks Sandbox.

Install the SDK​

Install or upgrade the Databricks SDK for Python, which includes the sandbox client:

Bash
pip install --upgrade databricks-sdk

Create a WorkspaceClient​

All sandbox operations run through a WorkspaceClient. Create a WorkspaceClient using credentials resolved from your environment, a configuration profile, or an explicit host and token:

Python
from databricks.sdk import WorkspaceClient

# Resolve credentials from the environment or the default config profile:
w = WorkspaceClient()

# Or select a specific ~/.databrickscfg profile:
w = WorkspaceClient(profile="my-workspace")

# Or pass the host and token explicitly:
w = WorkspaceClient(host="https://<workspace>.cloud.databricks.com", token="dapi...")

For more information about configuring and authenticating the SDK, see Databricks SDK for Python.

Create a sandbox​

Create a sandbox by ID. You can optionally configure the compute spec, such as the inactivity timeout that controls how long the sandbox stays running without activity:

Python
from google.protobuf.duration_pb2 import Duration
from databricks.sdk.service.sandbox import ComputeSpec, Sandbox, SandboxSpec

created = w.sandbox.create_sandbox(
    sandbox=Sandbox(
        spec=SandboxSpec(compute=ComputeSpec(inactivity_timeout=Duration(seconds=900))),
    ),
    sandbox_id="my-sandbox",
)
print(created.name)   # "sandboxes/my-sandbox"

Get and list sandboxes​

Retrieve a single sandbox by name, or list all sandboxes:

Python
sandbox = w.sandbox.get_sandbox("sandboxes/my-sandbox")
print(sandbox.status.state)   # SandboxState.SANDBOX_STATE_RUNNING

for sandbox in w.sandbox.list_sandboxes():
    print(sandbox.name, sandbox.status.state if sandbox.status else None)

Run a command in a sandbox​

Run a command in a sandbox and read its output. The first argument is the sandbox name, followed by the program to run and its arguments. This is a direct exec with no shell, so to run a shell command, invoke /bin/bash -c. Pass any environment variables through envs:

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"],
    envs={"MY_VAR": "value"},
    execution_timeout=Duration(seconds=30),
)
print(resp.status)      # ExecuteCommandStatus.EXECUTE_COMMAND_STATUS_COMPLETED
print(resp.exit_code)   # 0
print(resp.stdout)      # "hello world\nsandbox-agent\n"
print(resp.stderr)
print(resp.truncated)   # True if the output was truncated

Update sandbox metadata​

You can update a sandbox's display name and inactivity timeout. Only the following field paths are accepted. Any other path returns INVALID_PARAMETER_VALUE:

  • display_name
  • spec.compute.inactivity_timeout
Python
from databricks.sdk.common.types.fieldmask import FieldMask
from databricks.sdk.service.sandbox import ComputeSpec, Sandbox, SandboxSpec
from google.protobuf.duration_pb2 import Duration

# Rename the sandbox
w.sandbox.update_sandbox(
    name="sandboxes/my-sandbox",
    sandbox=Sandbox(display_name="renamed sandbox"),
    update_mask=FieldMask(["display_name"]),
)

# Extend the inactivity timeout
w.sandbox.update_sandbox(
    name="sandboxes/my-sandbox",
    sandbox=Sandbox(spec=SandboxSpec(compute=ComputeSpec(inactivity_timeout=Duration(seconds=1800)))),
    update_mask=FieldMask(["spec.compute.inactivity_timeout"]),
)

Stop and restart a sandbox​

Stop a sandbox to release its compute while preserving your home directory:

Python
w.sandbox.stop_sandbox("sandboxes/my-sandbox")    # Moves to SANDBOX_STATE_STOPPED

Start the sandbox again to resume work:

Python
w.sandbox.start_sandbox("sandboxes/my-sandbox")   # Moves to SANDBOX_STATE_RUNNING

Delete a sandbox​

Delete a sandbox when you are done. Deleting a sandbox removes its home directory and stops billing for the sandbox:

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

Additional resources​

On this page