CLI reference

The Agentix CLI has two core verbs plus a read-only inspector:

agentix build turns a Python project into a deploy-ready runtime bundle tar.
agentix deploy deploys that portable tar to a provider backend (local extract for docker/podman/apptainer; upload + register for managed services like E2B / Daytona / Modal).
agentix plugin list lists the installed provider backends and whether each one loads.

agentix --help
agentix build --help
agentix deploy --help
agentix plugin --help

`agentix build`

Package one project root into a bundle artifact.

agentix build
agentix build path/to/project
agentix build . --name my-rollout:0.1.0
agentix build . --platform linux/amd64
agentix build . --output dist/
agentix build . --dry-run

The project root must contain pyproject.toml. The default bundle name and tag are derived from [project].name and [project].version; -n / --name overrides them.

Option	Meaning
`path`	Project root, default `.`
`-n`, `--name`	Bundle `NAME` or `NAME:TAG`; bare names use `[project].version`
`-o`, `--output`	Output file or directory; defaults to `dist/<name>-<tag>-<platform>.bundle.tar`
`--platform`	Sandbox runtime platform, `linux/amd64` or `linux/arm64`; defaults to local CPU
`--dry-run`	Stage the Dockerfile and build context without running Docker
`--container-engine`	Container engine (Docker-compatible CLI: `docker`, `podman`, …); default `docker`
`--container-arg` / `--container-run-arg`	Raw args for the container build / export `run`; repeatable
`--nix-arg`	Raw arg forwarded verbatim to the in-container `nix build`; repeatable
`--uv-arg`	Raw arg forwarded verbatim to the in-container `uv sync`; repeatable

--nix-arg, --uv-arg, and --container-arg are raw passthroughs — each value is a shell-style string forwarded to the underlying engine (quote a whole sub-flag as one value), so any knob is reachable without a bespoke flag or env var. Point nix at a CN mirror, or override the builder base image:

agentix build . \
  --nix-arg "--option extra-substituters https://nix-mirror.example/nix-channels/store" \
  --container-arg "--build-arg AGENTIX_BUILDER_BASE=ghcr.io/nixos/nix:latest"

--platform describes the Linux container platform where the sandbox will run, not the machine that invokes the build. For example, use --platform linux/amd64 when building on an Apple Silicon Mac for a remote x86 sandbox.

Dependency Model

The CLI never enumerates integrations. It installs the project into the runtime venv, and uv sync resolves and installs everything declared by the project. With a committed uv.lock the in-container build runs uv sync --frozen --no-dev --no-editable (locked, reproducible); without one it resolves fresh. Either way the bundle gets a non-editable, production-only dependency closure.

pyproject.toml

[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",
]

That project builds one bundle containing the framework, sandbox primitives, the agent wrapper, the scorer wrapper, transitive deps, and the project itself.

Dry Run

agentix build . --dry-run

Dry run stages the generated Dockerfile and copied project tree under ./build/<tag>/, prints what would be built, and exits without invoking Docker.

`agentix deploy`

agentix deploy is a plugin-owned subcommand group. Each installed provider plugin (agentix-provider-docker, future -e2b, -modal, …) contributes its own agentix deploy <name> subcommand via the agentix.deploy.commands entry-point group. The core CLI knows nothing about backend-specific flags — it just discovers what’s installed:

agentix deploy list                         # focused: installed deploy backends
agentix deploy --help                       # full help, also lists backends
agentix deploy docker --help                # docker-specific flags
agentix deploy podman --help                # podman-specific flags
agentix deploy docker dist/my-rollout.bundle.tar
agentix deploy podman dist/my-rollout.bundle.tar

agentix deploy list is the structured discovery surface — text by default, JSON with --format json:

$ agentix deploy list
docker  agentix-provider-docker@0.1.4  Deploy a bundle tar to docker (local cache extract).
podman  agentix-provider-docker@0.1.4  Deploy a bundle tar to podman (local cache extract).

3 provider(s) installed without a deploy subcommand (see `agentix plugin list`):
  apptainer, daytona, e2b

The “without a deploy subcommand” line names providers whose SandboxProvider class is registered (i.e. agentix plugin list shows them) but who haven’t wired up an agentix.deploy.commands entry yet — useful for telling “not installed” from “installed but not yet wired for deploy”. The deploy operation is backend-specific:

Local backends (docker, podman) unpack the portable tar into a content-addressed host cache and print the cache root.
Managed services (e2b, modal, daytona, fly — when wired) upload the tar and print the service-side template / volume reference.

Use whatever deploy prints as SandboxConfig.bundle. The three flags every backend supports (via the shared common_options helper):

Option	Meaning
`bundle`	Bundle tar produced by `agentix build`
`-n`, `--name`	Optional backend bundle label
`--platform`	Optional runtime platform; defaults to manifest platform
`--format`	Output format: `text` (default) or `json`

Plus whatever flags the chosen backend declares (e.g. docker’s --container-engine / --run-arg). With --format json, deploy prints a machine-readable object so the cache path can be read with jq:

BUNDLE=$(agentix deploy docker dist/my-rollout.bundle.tar --format json | jq -r .bundle)

Deploy output also includes a shell-comment block of copy-pasteable inspect / cleanup commands the provider surfaces via DeployedBundle.hints:

bundle -> /Users/me/.cache/agentix/bundles/sha256-abc/
platform -> linux/amd64
cache -> /Users/me/.cache/agentix/bundles/sha256-abc/
name -> hello:1.0.0

# inspect contents
ls -la /Users/me/.cache/agentix/bundles/sha256-abc/nix/

# remove from cache
rm -rf /Users/me/.cache/agentix/bundles/sha256-abc/

Adding a new deploy backend

A plugin registers its deploy subcommand in its own pyproject.toml:

[project.entry-points."agentix.deploy.commands"]
mybackend = "my_plugin.deploy:_deploy_cmd"

The subcommand is an ordinary @click.command that decorates with common_options (from agentix.cli.deploy) for the shared flags, layers its own backend-specific flags on top, and calls print_deploy_result to render.

Bundle Tar

The tar contains:

manifest.json
nix/

The nix/ tree is the complete runtime closure and must appear at /nix inside a sandbox. Backends that stage bundles across machines can unpack this tar into their cache and bind it into task containers. The transient build image used to produce the tar is kept locally under an agentix-bundle-cache:* tag and overwritten on later builds, so the container builder can reuse it for incremental builds.

`agentix plugin`

A read-only inspector for the installed provider backends.

agentix plugin list

agentix plugin list enumerates every provider backend discovered through the agentix.provider entry-point group and reports whether each one loaded OK or failed to import. Use it to confirm a backend such as docker or podman is installed and importable before you deploy.

Configuration

Most runtime configuration lives in explicit provider config objects or CLI flags. Runtime bootstrap uses a small internal env contract.

Variable	Used by	Purpose
`AGENTIX_BIND_PORT`	runtime server	Sandbox-side bind port, default `8000`
`AGENTIX_UPLOAD_ROOT`	file primitive packages	Sandbox-side root for file operations
`AGENTIX_LOG_DIR`	runtime worker	Durable in-sandbox log directory, default `/tmp/agentix` (`sandbox-<worker-id>.log`); set empty to disable
`DAYTONA_API_KEY`	`daytona` backend	API authentication
`E2B_API_KEY`	`e2b` backend	API authentication

Third-party packages that need their own top-level workflow should ship a separate console script such as agentix-yourcmd instead of expanding the core CLI.

Start

Concepts

How-to

Reference

Contribute

`agentix build`

Dependency Model

Dry Run

`agentix deploy`

Adding a new deploy backend

Bundle Tar

`agentix plugin`

Configuration

​agentix build

​Dependency Model

​Dry Run

​agentix deploy

​Adding a new deploy backend

​Bundle Tar

​agentix plugin

​Configuration

`agentix build`

Dependency Model

Dry Run

`agentix deploy`

Adding a new deploy backend

Bundle Tar

`agentix plugin`

Configuration