Reference · Python SDK

Python SDK

Public surface of the grotte PyPI package. Two equivalent entrypoints — Sandbox (sync) and AsyncSandbox (async). Hand-curated from docstrings.

Install

bash

pip install grotte

Two entrypoints — pick the one that matches your code:

from grotte import Sandbox          # sync
from grotte import AsyncSandbox     # async (use with await)

Method names are identical between the two; the async version returns awaitables. Examples below show the sync API; for async, prefix every call with await and the surrounding context manager with async with.

`Sandbox` / `AsyncSandbox`

Lifecycle

Method	Returns	Description
`Sandbox.create(template=None, **opts)`	`Sandbox`	Create from a template (default `base`).
`Sandbox.connect(sandbox_id, **opts)`	`Sandbox`	Reconnect to a running sandbox.
`Sandbox.list(**opts)`	`SandboxPaginator`	Iterate sandboxes (running by default).
`sandbox.is_running(request_timeout=None)`	`bool`	Health probe.
`sandbox.kill(...)`	`None`	Terminate immediately.
`sandbox.pause(...)`	`bool`	Pause + persist filesystem.
`sandbox.resume(...)`	`Sandbox`	Resume a paused sandbox. Alias for `connect()`.

from grotte import Sandbox
 
with Sandbox.create("base") as sandbox:
    result = sandbox.commands.run('echo "Hello"')
    print(result.stdout)
# kill() called on context exit

Async equivalent:

from grotte import AsyncSandbox
 
async with await AsyncSandbox.create("base") as sandbox:
    result = await sandbox.commands.run('echo "Hello"')
    print(result.stdout)

Timeout / TTL

Method	Returns	Description
`set_timeout(timeout, ...)`	`None`	Set total max lifetime (seconds, from now).
`refresh_ttl(seconds, ...)`	`None`	Add seconds to current TTL (heartbeat-style).

Network

Method	Returns	Description
`set_network(internet_access=True, ...)`	`None`	Toggle outbound internet access.

sandbox.set_network(internet_access=False)  # cut egress for untrusted code

Snapshots

Method	Returns	Description
`create_snapshot(...)`	`SnapshotInfo`	Snapshot the filesystem to a reusable template.

URLs

Method	Returns	Description
`get_host(port)`	`str`	Host-only string.
`get_url(port)`	`str`	Full `https://…` URL — wraps `get_host`. Prefer this for previews.
`upload_url(path=None, ...)`	`str`	Pre-signed upload URL.
`download_url(path, ...)`	`str`	Pre-signed download URL.

`sandbox.filesystem` · alias `sandbox.files`

Both names point at the same Filesystem instance — filesystem is the canonical attribute, files exists for typing brevity in user code.

Method	Returns	Description
`read(path, format="text", ...)`	`str \| bytes \| Iterator`	Read a file. `format` ∈ `text` (default), `bytes`, `stream`.
`write(path, data, ...)`	`EntryInfo`	Write a file (`data` accepts `str` or `bytes`).
`write_files(files, ...)`	`list[EntryInfo]`	Batch-write many files in one round-trip.
`list(path, ...)`	`list[EntryInfo]`	List directory entries.
`make_dir(path, ...)`	`bool`	mkdir -p.
`rename(src, dst, ...)`	`EntryInfo`	Rename / move.
`remove(path, ...)`	`None`	rm -rf.
`exists(path, ...)`	`bool`	Check if a path exists.
`get_info(path, ...)`	`EntryInfo`	Stat-like metadata for a path.

sandbox.filesystem.write("/tmp/hello.txt", "world")
print(sandbox.filesystem.read("/tmp/hello.txt"))  # "world"

`sandbox.commands`

Method	Returns	Description
`run(command, ...)`	`CommandResult`	Run a command, wait for exit, return `(stdout, stderr, exit_code)`.
`connect(pid, ...)`	`CommandHandle`	Attach to an already-running command.
`list(...)`	`list[ProcessInfo]`	List currently-running processes.
`kill(pid, ...)`	`bool`	SIGKILL by pid.
`send_stdin(pid, data, ...)`	`None`	Pipe data into a running process's stdin.

result = sandbox.commands.run("python -c 'print(2+2)'")
print(result.stdout)  # "4\n"

For long-running processes, set background=True and stream output from the returned handle:

handle = sandbox.commands.run("npm run dev", background=True)
for chunk in handle.stdout:
    print(chunk, end="")

`sandbox.pty` · interactive PTY

For commands that need a real terminal (REPLs, full-screen TUI apps, interactive prompts):

pty = sandbox.pty.create(rows=24, cols=80)
pty.send_stdin(b"python\n")
output = pty.read()
pty.kill()

`sandbox.git`

Convenience wrappers around git operations inside the sandbox — clone, pull, status. Same shape as the underlying commands.run("git ...") calls, with typed returns.

Templates (build-time)

Two builder classes, parallel to the runtime split:

from grotte import Template, AsyncTemplate
 
template = (
    Template()
    .from_image("ubuntu:22.04")
    .run_cmd("apt-get update && apt-get install -y python3-pip")
    .run_cmd("pip install pandas")
    .set_workdir("/opt/work")
)

See Defining a template for the full builder API.

Common kwargs

Every method accepts:

Kwarg	Type	Description
`request_timeout`	`float \| None`	Per-request timeout in seconds.

API key is read from the GROTTE_API_KEY env var by default; override per-call via api_key=....

Install

Sandbox / AsyncSandbox