Quickstart

1. Declare deps in a normal Python project.
2. agentix build packages the project + every transitive dep into a self-contained bundle — no FROM, nothing installed at run time, just a uv venv plus a Nix closure under /nix/....
3. Deploy a sandbox: the bundle is bind-mounted onto a task base image at /nix. Different task images, same runtime.
4. Call a remote function with sandbox.remote(fn, …).

​

Prerequisites

• Python 3.11 or newer
• Docker or Podman for the build executor and local sandbox backend
• uv (optional) to commit a uv.lock. With a lock the build is reproducible (uv sync --frozen); without one the build container resolves dependencies fresh

​

One project, two images

• bundle — the bundle from agentix build. Generic and reusable. Holds Python, agentixx, every plugin, your code, all transitive deps under /nix/store/... with libc vendored.
• image — the task-specific base the workload runs in (a SWE-bench task image, a customer environment, plain Ubuntu, …).

​

Layout

hello-world/
├── pyproject.toml
├── uv.lock                       # optional — `uv lock` for reproducible builds
├── default.nix                   # adds ripgrep (rg) to the runtime PATH
├── main.py                       # defines hello(); also host orchestrator
└── README.md

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "hello-world"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "agentixx>=0.2.0",
    "agentix-runtime-basic",      # bash + files namespaces
    "agentix-provider-docker",    # docker/podman backend
]

[tool.agentix]
nix = "default.nix"               # extra system deps for the runtime

# Hatchling cannot infer root-level main.py from the project name, so
# include it explicitly in the wheel that agentix build installs.
[tool.hatch.build.targets.wheel]
only-include = ["main.py"]

import subprocess

from agentix.provider import providers
from agentix.provider.base import SandboxConfig


def hello() -> str:
    """Return the bundled ripgrep version from the runtime PATH."""
    proc = subprocess.run(
        ["rg", "--version"], check=True, capture_output=True, text=True
    )
    return proc.stdout.splitlines()[0]

{ pkgs }:

pkgs.symlinkJoin {
  name = "hello-world-sys";
  paths = [ pkgs.ripgrep ];
}

uv lock

​

Install + build

cd examples/hello-world
uv sync
uv run agentix build . --output dist/hello-world.bundle.tar
BUNDLE=$(uv run agentix deploy docker dist/hello-world.bundle.tar --format json | jq -r .bundle)

1. Stages your project + every plugin’s default.nix (each plugin ships its system deps next to its Python module).
2. Runs Nix for the interpreter/system closures and installs the Python dependency closure with uv inside the build container:
   uv venv /nix/runtime/venv
   VIRTUAL_ENV=/nix/runtime/venv uv sync --active --frozen --no-dev --no-editable
   
3. Writes a portable bundle tar containing manifest.json + nix/.

​

Call it

import asyncio
import subprocess

from agentix.provider import providers
from agentix.provider.base import SandboxConfig


def hello() -> str:
    """Return the bundled ripgrep version from the runtime PATH."""
    proc = subprocess.run(
        ["rg", "--version"], check=True, capture_output=True, text=True
    )
    return proc.stdout.splitlines()[0]


async def main(bundle: str) -> None:
    # String-driven selection at a dynamic boundary; typed code can also
    # `from agentix.provider.docker import DockerProvider` and construct it directly.
    provider = providers().get("docker")()
    config = SandboxConfig(
        # Task base image — workload environment.
        image="python:3.13-slim",
        # Cache path captured from `agentix deploy ... --format json`.
        bundle=bundle,
    )
    async with provider.session(config) as sandbox:
        print(f"sandbox up at {sandbox.runtime_url}")
        print(f"Host result:    {hello()}")
        print(f"Sandbox result: {await sandbox.remote(hello)}")

uv run python main.py --bundle "$BUNDLE"

sandbox up at http://localhost:33803
Host result:    ripgrep 14.1.0
Sandbox result: ripgrep 14.1.0

​

How the overlay works

# Per sandbox — task image plus the cached runtime /nix.
docker run -d --name <sid> -p 127.0.0.1:<port>:<port> \
    -e AGENTIX_BIND_PORT=<port> \
    --mount type=bind,source="$BUNDLE"/nix,target=/nix,readonly \
    --entrypoint /nix/runtime/bootstrap.sh \
    python:3.13-slim

​

Next