Documentation

Python: sandboxes

Create, pause, resume, and delete a Linux workspace.

Before you run it

Install the Python SDK and create an API key in your dashboard. The SDK reads it from the environment or a .env file:

.env shell

BOLTZLABS_API_KEY=ak_your_key_here

Create a sandbox

sandbox.py

from boltzlabs import Sandbox

sandbox = Sandbox.create(environment="python")

Run commands and manage files

usage.py

sandbox.exec("python -c 'print(1)'")            # a shell command
sandbox.exec("pip install requests")
print(sandbox.url(8080))                        # public URL for a port inside

sandbox.pause()                                 # release CPU/RAM, keep files
sandbox.resume()                                # start the same workspace again

sandbox.delete()                                # stops the meter

Open a port

ports.py

sandbox = Sandbox.create(internet=True, name="web")
sandbox.exec("python -m http.server 8000")

print(sandbox.url(8000))          # public preview URL — needs internet=True

# A local forward needs no networking, and no --host on the server:
#   boltz forward web 8000    (Ctrl-C to stop)

Automatic cleanup

with.py

with Sandbox.create(environment="python") as sandbox:
    print(sandbox.exec("python -c 'print(sum(range(101)))'"))

# destroyed here, however the block ended

Read command results

result.py

print(sandbox.exec("ls"))              # prints stdout
if sandbox.exec("test -f /app/x"):     # True when the exit code was 0
    ...
sandbox.exec("make").check()           # raises if it failed

# .stdout .stderr .exit_code .duration_ms when you want them.
# A non-zero exit is data, not an exception: your program failed, not the call.

Open a terminal

terminal.py

sandbox.terminal()                                  # interactive
print(sandbox.terminal("tty; echo from-a-real-tty"))  # scripted

List sandboxes and available options

listing.py

import boltzlabs

boltzlabs.me()             # who your key belongs to      (boltz auth status)
boltzlabs.sandboxes()      # everything you have running  (boltz ls)
boltzlabs.sandbox(id)      # one of them, by id           (boltz status <id>)
boltzlabs.environments()   # runtimes and coding agents  (boltz environments)
boltzlabs.machines()       # machines and prices          (boltz machines)

All guides