Development

This page is for framework development. If you are writing an agent or dataset package, start with integrate an agent or integrate a dataset.

Prerequisites

Python 3.11 or newer
Docker for end-to-end sandbox tests
Agentix is one monorepo uv workspace — the runtime and provider plugins live under plugins/ (e.g. plugins/runtime-basic, plugins/providers/docker) and are installed editable by uv sync --all-packages. There are no sibling repos to check out.

Setup

git clone https://github.com/Agentix-Project/Agentix.git
cd Agentix
uv sync --all-packages --all-extras

The PyPI distribution is named agentixx; the import package is agentix.

Run the Runtime Locally

You can run the runtime server without Docker while iterating on client, server, or worker code. There’s no console script — the bundle starts it via /nix/runtime/bootstrap.sh, but during dev you can launch the ASGI app directly with uvicorn:

uvicorn agentix.runtime.server.app:app --host 0.0.0.0 --port 8000
# Or override the port:
AGENTIX_BIND_PORT=9000 uvicorn agentix.runtime.server.app:app --port 9000

The server exposes /health; remote calls use /socket.io/.

Bundles, Not a Base Image

There is no separate runtime base image to build. agentix build produces a bundle, staging the Dockerfile shipped at agentix/builder/Dockerfile and running every heavy step inside the build container. Providers then overlay that bundle onto any task image at /nix via Docker’s --mount type=image, so the same bundle works across task images with no rebuild.

Build a Bundle

agentix build
agentix build path/to/project --name my-rollout:dev
BUNDLE=$(agentix deploy docker dist/my-rollout-dev-linux-amd64.bundle.tar --format json | jq -r .bundle)
agentix build path/to/project --dry-run

The build installs the project and its dependency closure into /nix/runtime. If the project includes default.nix, the build also splices system binaries into the final bundle.

Smoke Test a Sandbox

import asyncio

from agentix.bash import run
from agentix import SandboxConfig
from agentix.provider.docker import DockerProvider


async def main() -> None:
    provider = DockerProvider()
    config = SandboxConfig(image="python:3.13-slim", bundle="/home/me/.cache/agentix/bundles/sha256-...")

    async with provider.session(config) as sandbox:
        result = await sandbox.remote(run, command="echo hi")
        print(result.stdout)


asyncio.run(main())

Lint and Test

ruff check agentix/ tests/
pytest
pytest -x

Codebase Map

Path	Purpose
`agentix/runtime/shared`	Wire types, msgpack codec, Socket.IO event names
`agentix/runtime/client`	`RuntimeClient` and transport behavior
`agentix/runtime/server`	FastAPI app, Socket.IO handlers, worker client, worker process, callable invocation
`agentix/provider`	SandboxProvider protocol + backend discovery
`agentix/cli`	Build + deploy CLI (`agentix build`, `agentix deploy`, `agentix plugin`)
`agentix/sio`	Sandbox-side namespace API
`agentix/utils`	log + trace bridges
`agentix/builder`	`flake.nix`/`Dockerfile`/`bundle-build.sh` shipped as wheel data

Design Rules

Keep the user model centered on client.remote(fn, ...).
Keep bundle behavior dependency-driven through pyproject.toml.
Prefer composition over inheritance outside lifecycle protocols.
Do not add compatibility shims for old API shapes unless there is a concrete external constraint.

Start

Concepts

How-to

Reference

Contribute

Prerequisites

Setup

Run the Runtime Locally

Bundles, Not a Base Image

Build a Bundle

Smoke Test a Sandbox

Lint and Test

Codebase Map

Design Rules

​Prerequisites

​Setup

​Run the Runtime Locally

​Bundles, Not a Base Image

​Build a Bundle

​Smoke Test a Sandbox

​Lint and Test

​Codebase Map

​Design Rules

Prerequisites

Setup

Run the Runtime Locally

Bundles, Not a Base Image

Build a Bundle

Smoke Test a Sandbox

Lint and Test

Codebase Map

Design Rules