Skip to content

CLI reference

Every subcommand is itself an entry-point plugin under the agentix.cli group. The framework's builtins are listed below; downstream pip install adds more without framework patches.

agentix --help

agentix build

Build a single namespace image.

agentix build <spec>
agentix build primitives/bash --dry-run
agentix build bash --tag my-bash:dev

<spec> accepts the same forms agentix install does — see spec resolvers.

  • Path: ./primitives/bash or any directory with a pyproject.toml.
  • Short name: looked up under the repo's primitives/.
  • PyPI dist: agentix-bash (currently surfaces NotImplementedError; fetch path is stubbed).

--tag overrides the auto-derived agentix/<short>:<version> tag. --dry-run stages the docker build context to ./build/<name>/ and prints the path instead of invoking docker.

agentix install

Bundle multiple namespaces into one image. The runtime discovers them via entry points at startup.

agentix install bash files claude-code -o my-agent:0.1.0
agentix install primitives/bash ./my-experimental-namespace -o demo:dev
agentix install bash files --dry-run

The output image carries every named namespace pip-installed alongside the runtime. No bundle disposition file — discovery is just importlib.metadata.entry_points(group="agentix.namespace").

-o / --output is the bundle image tag. --dry-run stages to ./build/<bundle-short>/.

agentix deploy

Provision a sandbox.

agentix deploy <backend> --image <tag>
agentix deploy local --image my-agent:0.1.0
agentix deploy local --image my-agent:0.1.0 --detach
agentix deploy daytona --image docker.io/me/my-agent:0.1.0    # currently NotImplementedError

<backend> is the name of any registered agentix.deployment plugin. agentix plugins --group agentix.deployment lists what's installed.

By default the command stays in the foreground: prints the sandbox's runtime_url, waits for Ctrl-C, then tears the sandbox down. --detach exits after create() and just prints the handle so the user can manage the sandbox lifetime themselves.

  • --base — base task image (default ubuntu:24.04)
  • --runtime — runtime image ref (default agentix/runtime:latest)
  • --detach — exit immediately after sandbox creation

agentix plugins

List every installed plugin across every framework axis.

agentix plugins
agentix plugins --group agentix.deployment      # filter by axis
agentix plugins --verbose                       # show tracebacks for load failures

Output one line per plugin: name, target, dist@version, load status. Loading is forced (so failures surface here, not at the first agentix deploy … call).

agentix check

List installed namespaces and smoke-import each one.

agentix check

With the entry-point model, namespace stub-impl drift is impossible (one class, the methods are the implementation). agentix check is a fast health check: every namespace declared under agentix.namespace actually imports without error. Non-zero exit code if any failed.

Configuration via environment

Most plugin-specific config reads from environment variables, not command-line flags. Examples:

Variable Used by Purpose
AGENTIX_BIND_PORT start / runtime server Bind port (default 8000)
AGENTIX_UPLOAD_ROOT agentix.files namespace Sandbox-side root for file I/O
DAYTONA_API_KEY daytona deployment API auth
E2B_API_KEY / E2B_TEMPLATE_ID e2b deployment API auth + template