Skip to content
Axern

Python SDK

The Python SDK offers synchronous Sandbox and asynchronous AsyncSandbox surfaces.

Terminal window
uv add axern-sdk==<version>

The official package is published as axern-sdk on PyPI.

Pin the SDK to the Axern release used by the gateway and runtime, install it only after publication completes, and review the corresponding release notes before upgrading.

import os


from axern_sdk import AxernClient, Sandbox


client = AxernClient.from_context(
    os.path.expanduser("~/.config/axern/config.json")
)


with Sandbox(
    client=client,
    image="docker.io/library/python:3.12-slim",
) as sandbox:
    result = sandbox.exec(
        "python -c \"print('hello from Python')\"",
        text=True,
        check=True,
    )
    print(result.stdout)


    sandbox.write_text("/tmp/message.txt", "payload\n")
    print(sandbox.read_text("/tmp/message.txt"))


client.close()

Read-only tool images and Secret projections are explicit immutable Run inputs:

from axern_sdk import ImageMount, SecretFile


with Sandbox(
    client=client,
    image="docker.io/library/python:3.12-slim",
    image_mounts=[ImageMount("registry.example/claude-code@sha256:<digest>", "/__claude_code")],
    secret_files=[SecretFile("/run/secrets/config", "secret-workload", "config.json")],
) as sandbox:
    sandbox.exec(["/__claude_code/bin/claude"], check=True)

The SDK sends Secret references only, never plaintext. Every Run must declare its own mounts and Secret projections; they are not inherited from an earlier Run. Credentials for caller-local services remain outside the sandbox, which can reach those services through an Allocation-scoped TunnelSession.

Secret files default to mode 0400; explicit modes must be read-only. Axern rejects pseudo-filesystems, executable/library trees, its runtime-state paths, and critical system identity files as Secret targets.

Use exec_stream() for incremental output and process() when you need stdin, termination, or explicit wait behavior. Directory transfer is archive-backed and rejects unsafe paths and links.