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, no pip install at run time, just a Nix closure under /nix/store/....
3. Deploy a sandbox: the bundle is overlaid onto a task base image with --volumes-from. Different task images, same runtime.
4. Call a remote function with RuntimeClient.remote(fn, …).

​

Prerequisites

• Python 3.11 or newer
• Docker (Engine 20.10+; 25.0+ recommended once --mount type=image stabilizes)
• Nix on the build host (the framework vendors a pinned Nixpkgs revision)
• uv for dependency locking (uv.lock is mandatory — uv2nix reads it to build the Python closure)

​

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-agentix/
├── pyproject.toml
├── uv.lock                       # run `uv lock`
├── run.py                        # host orchestrator
└── src/
    └── hello_agentix/
        └── __init__.py           # sandbox-side module (placeholder here)

[project]
name = "hello-agentix"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "agentixx>=0.1.5",
    "agentix-runtime-basic>=0.1.4",      # bash + files namespaces
    "agentix-deployment-docker>=0.1.4",  # local-docker backend
]

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

[tool.hatch.build.targets.wheel]
packages = ["src/hello_agentix"]

# Pure placeholder for this quickstart — bash.run from
# agentix-runtime-basic does all the work.
#
# Add your own functions when you outgrow bash:
#
#     async def greet(name: str) -> str:
#         return f"hello {name} from inside the sandbox"

uv lock

​

Install + build

cd hello-agentix
uv sync
uv run agentix build . --name hello-agentix
# → docker images now has hello-agentix:0.1.0 and hello-agentix:latest

1. Stages your project + every plugin’s default.nix (each plugin ships its system deps next to its Python module).
2. Runs nix build against the vendored Nixpkgs pin: uv2nix produces a derivation for every entry in uv.lock, symlinkJoin merges them with the plugin trees.
3. Streams the resulting dockerTools.streamLayeredImage tarball into docker load and also applies a :latest alias for convenience.

​

Call it

import asyncio

from agentix import RuntimeClient, SandboxConfig, session
from agentix.bash import run
from agentix.deployment.docker import DockerDeployment


async def main() -> None:
    deployment = DockerDeployment()
    config = SandboxConfig(
        # Task base image — workload environment.
        image="python:3.13-slim",
        # Bundle overlay from `agentix build`.
        bundle="hello-agentix:0.1.0",
    )
    async with session(deployment, config) as sandbox:
        print(f"sandbox up at {sandbox.runtime_url}")
        async with RuntimeClient(sandbox.runtime_url) as client:
            result = await client.remote(run, command="echo hello from $(uname -a)")
            print(f"exit={result.exit_code} stdout={result.stdout!r}")


asyncio.run(main())

uv run python run.py

sandbox up at http://localhost:33803
exit=0 stdout='hello from Linux <kernel> ... GNU/Linux\n'

​

How the overlay works

# Once per distinct bundle — stopped container holds its /nix.
docker create --name agentix-runtime-<hash> hello-agentix:0.1.0

# Per sandbox — task image plus the runtime's /nix as a shared volume.
docker run -d --name <sid> -p 127.0.0.1:<port>:<port> \
    -e AGENTIX_BIND_PORT=<port> \
    --volumes-from agentix-runtime-<hash>:ro \
    --entrypoint /nix/runtime/bin/agentix-server \
    python:3.13-slim

​

Next