Skip to main content

Watasu Python SDK

Python SDK for Watasu.

Install

Requires Python 3.10 or newer.

pip install watasu

Set WATASU_API_KEY before using the SDK.

Usage

from watasu import Sandbox

sbx = Sandbox()
sbx.files.write("/home/user/a.py", "print(2 + 2)")
result = sbx.commands.run("python /home/user/a.py")
print(result.stdout)
sbx.kill()

Sandbox(), Sandbox.create, and Sandbox.connect return only after the Watasu API supplies a usable data-plane session. The SDK does not poll sandbox readiness.

sbx.beta_pause()
sbx.resume(timeout=300)

Choose what happens when the sandbox timeout expires:

with Sandbox.beta_create(auto_pause=True) as sbx:
    result = sbx.commands.run("echo retained")
    print(result.stdout)

Sandbox.create(lifecycle={"on_timeout": "pause", "auto_resume": True}) keeps the retained disk after timeout and allows a later data-plane request to resume that paused sandbox automatically. The default timeout action is kill.

Mount a named persistent volume when the sandbox starts:

with Sandbox.create(
    volume_mounts={
        "/workspace/cache": "cache",
        "/data/models": {"name": "models"},
    }
) as sbx:
    sbx.commands.run("echo ready > /workspace/cache/status.txt")

Create and edit a persistent volume while it is detached:

from watasu import Volume

volume = Volume.create("cache")
volume.make_dir("/workspace")
volume.write_file("/workspace/status.txt", "ready\n", mode="0644")
print(volume.read_file("/workspace/status.txt"))
print([entry.path for entry in volume.list("/workspace")])
volume.remove("/workspace/status.txt")
volume.destroy()
from watasu import Sandbox

with Sandbox.create() as sbx:
    result = sbx.commands.run("echo hello")
    print(result.stdout)

Leaving the context manager calls kill().

Code Interpreter

pip install watasu-code-interpreter
from watasu_code_interpreter import Sandbox

with Sandbox.create() as sbx:
    context = sbx.create_code_context()
    execution = sbx.run_code(
        "print('hello')\n2 + 3",
        context=context,
        on_stdout=lambda message: print(message.line),
    )
    print(execution.text)
    sbx.remove_code_context(context)

watasu_code_interpreter.Sandbox starts the code-interpreter template by default. Code runs in persistent Python contexts and returns structured results, logs, and error fields for each execution.

MCP Gateway

import os

from watasu import Sandbox

with Sandbox.create(
    mcp={
        "github": {
            "command": "github-mcp-server",
            "args": ["stdio"],
            "env": {"GITHUB_TOKEN": os.environ["GITHUB_TOKEN"]},
        }
    }
) as sbx:
    print(sbx.get_mcp_url())
    print(sbx.get_mcp_token())

Listing Sandboxes

from watasu import Sandbox

paginator = Sandbox.list(
    query={"metadata": {"purpose": "ci"}, "state": ["running"]},
    limit=20,
)

for sandbox in paginator.list_items():
    print(sandbox.sandbox_id, sandbox.state)

Git, Watch, PTY, And Signed File URLs

from watasu import PtySize, Sandbox

with Sandbox.create() as sbx:
    sbx.git.init("/workspace/new-project", initial_branch="main")
    sbx.git.clone(
        "https://github.com/acme/project.git",
        path="/workspace/project",
        branch="main",
        depth=1,
    )
    status = sbx.git.status("/workspace/project")
    sbx.git.configure_user(
        "Watasu Bot",
        "bot@watasu.local",
        scope="local",
        path="/workspace/project",
    )
    sbx.git.create_branch("/workspace/project", "feature/docs")
    sbx.git.add("/workspace/project", files=["README.md"])
    sbx.git.commit(
        "/workspace/project",
        "Update docs",
        author_name="Watasu Bot",
        author_email="bot@watasu.local",
    )
    sbx.git.push(
        "/workspace/project",
        remote="origin",
        branch="feature/docs",
        set_upstream=True,
    )
    remote_url = sbx.git.remote_get("/workspace/project", "origin")
    sbx.git.restore("/workspace/project", paths=["README.md"])
    sbx.git.reset("/workspace/project", mode="hard", target="HEAD")

    watcher = sbx.files.watch_dir("/workspace/project", recursive=True)
    sbx.files.write_files(
        [
            {"path": "/workspace/project/a.txt", "data": "alpha"},
            {"path": "/workspace/project/b.bin", "data": b"\x00\x01\x02"},
        ]
    )
    patch = sbx.files.apply_diff(
        """*** Begin Patch
*** Update File: a.txt
@@
-alpha
+beta
*** End Patch""",
        cwd="/workspace/project",
    )
    print(patch.status)

    terminal = sbx.pty.create(PtySize(rows=30, cols=100))
    terminal.send_stdin("echo hello\n")
    result = terminal.wait()

    upload_url = sbx.upload_url("/workspace/input.bin")
    download_url = sbx.download_url("/workspace/output.bin")

    events = watcher.get_new_events()
    watcher.stop()

Network Policy

with Sandbox.create(
    network={
        "allow_out": lambda ctx: list(ctx.rules.keys()) + ["pypi.org:443"],
        "deny_out": ["169.254.169.254"],
        "rules": {
            "api.example.com": [
                {"transform": {"headers": {"authorization": "Bearer token"}}}
            ]
        },
        "mask_request_host": "${PORT}-sandbox.example.com",
    }
) as sbx:
    sbx.update_network(
        allow_internet_access=False,
        allow_package_registry_access=True,
        allow_out=["registry.npmjs.org:443"],
    )

Template Builds

from watasu import Template

template = (
    Template()
    .from_python_image("3.12")
    .copy("requirements.txt", "/workspace/requirements.txt")
    .apt_install(["git"])
    .pip_install(["pytest"])
    .set_envs({"PIP_DISABLE_PIP_VERSION_CHECK": "1"})
    .run_cmd("echo ready")
)

build = Template.build_in_background(
    template,
    "python-ci:stable",
    tags=["stable"],
    cpu_count=2,
    memory_mb=2048,
)
status = Template.get_build_status(build)

Template.assign_tags("python-ci:stable", ["prod"])
print(Template.exists("python-ci"))

The same builder classes are also available from the sync and async template namespaces:

from watasu.template_sync import Template
from watasu.template_async import AsyncTemplate

Template names resolve server-side. python-ci starts the latest ready build; python-ci:stable starts the tagged build.

Template(file_context_path=".").from_dockerfile("Dockerfile") parses common FROM, WORKDIR, COPY, RUN, ENV, CMD, and ENTRYPOINT instructions into Watasu's package-spec builder.

Metrics And Snapshots

import datetime

from watasu import Sandbox

with Sandbox.create() as sbx:
    metrics = sbx.get_metrics(
        start=datetime.datetime.now(datetime.timezone.utc)
        - datetime.timedelta(minutes=5),
        end=datetime.datetime.now(datetime.timezone.utc),
    )
    snapshot = sbx.create_snapshot(name="ready")
    snapshots = sbx.list_snapshots().list_items()
    all_snapshots = Sandbox.list_snapshots(limit=100).next_items()
    restored = sbx.restore(snapshot_id=snapshot.snapshot_id)
    sbx.delete_snapshot(snapshot.snapshot_id)

Watasu snapshots are backed by sandbox checkpoints. Use the returned snapshot_id when restoring from a checkpoint.

Async API

import datetime

from watasu import AsyncSandbox


async def main() -> None:
    async with await AsyncSandbox.create() as sbx:
        result = await sbx.commands.run("echo hello")
        print(result.stdout)

        metrics = await sbx.get_metrics(
            start=datetime.datetime.now(datetime.timezone.utc)
            - datetime.timedelta(minutes=5),
            end=datetime.datetime.now(datetime.timezone.utc),
        )
        snapshot = await sbx.create_snapshot(name="ready")
        snapshots = await sbx.list_snapshots().list_items()
        all_snapshots = await AsyncSandbox.list_snapshots(limit=100).list_items()
        await sbx.delete_snapshot(snapshot.snapshot_id)

Unsupported control/runtime surfaces fail with explicit errors instead of silently falling back to client-side polling.

Metadata

Release files for watasu 0.1.77

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for watasu 0.1.77
File Size Uploaded Provenance Actions
watasu-0.1.77.tar.gz 263.1 kB With provenance Details for watasu-0.1.77.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for watasu 0.1.77
File Interpreter ABI Platform Actions
watasu-0.1.77-py3-none-any.whl Python 3 none any Details for watasu-0.1.77-py3-none-any.whl

Total release size: 336.9 kB

Release files / watasu-0.1.77.tar.gz

Download URL watasu-0.1.77.tar.gz
Size 263.1 kB
Tags Source
SHA-256 checksum
How to use checksums
da3a8e4f18754d8ffe571f5fd22b9e8968ec1efb820cb82419441a07d1f7f5a3
BLAKE2b-256 checksum
How to use checksums
f4ec79c9d6a1874fbd97c156e32a3b2a33bfefeaf6caae19afffd95b914c72ca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Release files / watasu-0.1.77-py3-none-any.whl

Download URL watasu-0.1.77-py3-none-any.whl
Size 73.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bb9448b476e0f1101414220a5d7ccfe75f38f7a340bdbe8268c1817fcbdcc071
BLAKE2b-256 checksum
How to use checksums
7b1be95650e95b6ceceda5750d2ccb64374152db5c77cb6949be8f3ae73d788a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Security for watasu 0.1.77

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for watasu-0.1.77.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.77 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page