Loading...
Loading...
Databricks Sandbox: on-demand serverless compute for running untrusted or agent-generated code and background tasks. Create/start/stop/delete sandboxes, run commands (synchronous execute_command_sync in all SDKs; streaming execute_command in the Python SDK only), and manage files through the Databricks SDK (Python, Java, Go, JavaScript). Use for Databricks Sandbox, serverless code-execution environments, or coding-agent runtimes.
npx skill4agent add databricks/databricks-agent-skills databricks-sandboxexecute_command_syncexecute_commanduv pip install "databricks-sdk[sandbox]>=0.154.0"sandboxexecute_commanddatabricks-sdkexecute_command_sync~/.databrickscfgdatabricks-coreWorkspaceClientnamesandboxes/<sandbox_id>create_sandboxsandbox_idnamecreate_sandboxPENDINGstop_sandboxSTOPPINGget_sandbox(name).status.stateimport time
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.sandbox import ComputeSpec, Sandbox, SandboxSpec, SandboxState
from google.protobuf.duration_pb2 import Duration
w = WorkspaceClient()
def wait_for_state(name: str, state: SandboxState, timeout: float = 300) -> Sandbox:
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
sandbox = w.sandbox.get_sandbox(name=name)
if sandbox.status and sandbox.status.state == state:
return sandbox
time.sleep(2)
raise TimeoutError(f"{name} did not reach {state}")
# Create returns while the sandbox is still PENDING; wait for RUNNING before use.
# A sandbox bills hourly while running; set inactivity_timeout so it auto-stops when
# idle.
# Sandboxes can be updated with update_sandbox. The only accepted update paths
# are display_name and spec.compute.inactivity_timeout.
created = w.sandbox.create_sandbox(
sandbox=Sandbox(spec=SandboxSpec(compute=ComputeSpec(inactivity_timeout=Duration(seconds=3600)))),
sandbox_id="my-sandbox",
)
name = created.name # "sandboxes/my-sandbox"
wait_for_state(name, SandboxState.SANDBOX_STATE_RUNNING)
# Inspect
sandbox = w.sandbox.get_sandbox(name=name)
for s in w.sandbox.list_sandboxes():
print(s.name)
# Stop keeps the home directory; it returns while STOPPING, so wait for STOPPED
# before starting again.
w.sandbox.stop_sandbox(name=name)
wait_for_state(name, SandboxState.SANDBOX_STATE_STOPPED)
w.sandbox.start_sandbox(name=name)
wait_for_state(name, SandboxState.SANDBOX_STATE_RUNNING)
# Delete is terminal.
w.sandbox.delete_sandbox(name=name)/home/sandbox-agentstop_sandbox()start_sandbox()execute_commandexecute_command_synccreate_sandbox()start_sandbox()execute_commandexecute_command_sync| Mode | Method | Use for |
|---|---|---|
| Synchronous | | Short commands where you only need the final stdout/stderr/exit code |
| Streaming | | Long-running or interactive commands where you consume output as it is produced |
execute_commandCommandProcessexecute_command_synccmd/bin/bash -c "..."argsfrom google.protobuf.duration_pb2 import Duration
resp = w.sandbox.execute_command_sync(
"sandboxes/my-sandbox",
"/bin/bash",
args=["-c", "echo hello && whoami"],
execution_timeout=Duration(seconds=30),
)
print(resp.status, resp.exit_code, resp.truncated, resp.stdout, resp.stderr)
# Check resp.status for the terminal status: exit_code is unset when the command is
# killed (e.g. timed out) or fails to start. resp.truncated is True when the output
# hit the sync size cap - use execute_command (streaming) for large output.execute_commandCommandProcessstdoutstderrwait()withproc.pidw.sandbox.execute_command_sync(name, "/bin/kill", args=[str(proc.pid)])with w.sandbox.execute_command(
"sandboxes/my-sandbox",
"/bin/bash",
args=["-c", "for i in 1 2 3; do echo line $i; sleep 1; done"],
) as proc:
for line in proc.stdout:
print(line, end="")
exit_code = proc.wait() # also available as proc.exit_code once finishedstdoutstderrStreamMode.PIPEStreamMode.DEVNULLStreamMode.STDOUTstderrtext=Falsebytesstrconnect_command(name, command_id)list_commands(parent="sandboxes/my-sandbox")parentnamepath/home/sandbox-agent/homew.sandbox.create_directory(parent="sandboxes/my-sandbox", path="/home/sandbox-agent/data", parents=True)
for entry in w.sandbox.list_directory_contents(parent="sandboxes/my-sandbox", path="/home/sandbox-agent/data"):
print(entry.path)
w.sandbox.get_metadata(parent="sandboxes/my-sandbox", path="/home/sandbox-agent/data")
w.sandbox.rename_path(parent="sandboxes/my-sandbox", source="/home/sandbox-agent/a", destination="/home/sandbox-agent/b")
w.sandbox.delete_path(parent="sandboxes/my-sandbox", path="/home/sandbox-agent/b", recursive=True)execute_command