Bundles

A bundle is the sandbox’s world: your project, Agentix, integration packages, transitive Python dependencies, and optional system binaries in one bundle. agentix build [path] takes a normal Python project and produces a deploy-ready bundle. The default output is a portable tar containing manifest.json and the complete nix/ runtime tree.

agentix build ./my-rollout --name my-rollout:0.1.0 --output dist/my-rollout.bundle.tar
agentix deploy docker dist/my-rollout.bundle.tar

What Goes In

Agentix does not maintain a separate plugin manifest. The project’s pyproject.toml is the manifest.

[project]
name = "my-rollout"
version = "0.1.0"
dependencies = [
    "agentixx>=0.2.0",
    "agentix-runtime-basic>=0.1.0",
    "agentix-agent-claude-code>=0.1.0",
    "agentix-dataset-swe>=0.1.0",
]

During the build, Agentix copies the project into the bundle and uses uv to resolve and install the dependency closure into the runtime venv:

uv venv /nix/runtime/venv
VIRTUAL_ENV=/nix/runtime/venv uv sync --active --frozen --no-dev --no-editable

That sync brings in user code, direct dependencies, transitive dependencies, and integration modules such as agentix.bash or agentix.plugins.datasets.swe. uv sync --frozen resolves from the project’s lockfile, --no-dev drops dev-only dependency groups, and --no-editable installs everything as a regular (non-editable) copy so the bundle is self-contained.

Runtime Layout

/nix/runtime/
├── bootstrap.sh           # container entry point (provider backends exec this)
├── venv/                  # the uv venv — all Python deps
│   └── lib/python3.11/site-packages/
│       ├── agentix/
│       ├── agentix/bash/
│       ├── agentix/agents/claude_code/
│       ├── agentix/plugins/datasets/swe/
│       └── app.py
└── {bin,lib,...}/         # symlinkJoin of the Nix closures (system binaries)

The runtime server and worker use this same environment. If the worker can import a module from that environment, the host can call it with client.remote(fn, ...).

System Binaries

If the project root includes default.nix, agentix build adds a Nix builder stage. The derivation closure is copied into the final bundle, and binaries are linked under /nix/runtime/bin. Worker subprocesses inherit the runtime server’s environment, with the bundle venv and Nix runtime bins prepended to PATH:

/nix/runtime/venv/bin:/nix/runtime/bin:${PATH}

That is how CLI wrappers can call tools by name:

await asyncio.create_subprocess_exec("git", "status")
await asyncio.create_subprocess_exec("claude", "-p", instruction)

Bundles Compose Integrations

Agent wrappers, dataset scorers, sandbox primitives, and application code are all normal Python packages. A rollout bundle chooses which packages coexist in one sandbox.

Package type	Example	Why include it
Framework	`agentixx`	Runtime client/server protocol and worker invocation
Primitive	`agentix-runtime-basic`	Shell and file operations in the sandbox
Agent wrapper	`agentix-agent-claude-code`	CLI execution behind a typed Python function
Scorer wrapper	`agentix-dataset-swe`	Benchmark grading behind a typed Python function
User project	`my-rollout`	Orchestration-specific functions and dependencies

Mental Model

Bundle = what exists in the sandbox
Remote call = which installed function runs
SandboxProvider = where the bundle is staged and started

Keep those concerns separate and the same integration can move from a local smoke test to a larger rollout system without changing its Python API.

Start

Concepts

How-to

Reference

Contribute

What Goes In

Runtime Layout

System Binaries

Bundles Compose Integrations

Mental Model

​What Goes In

​Runtime Layout

​System Binaries

​Bundles Compose Integrations

​Mental Model

What Goes In

Runtime Layout

System Binaries

Bundles Compose Integrations

Mental Model