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

PathPurpose
agentix/runtime/sharedWire types, msgpack codec, Socket.IO event names
agentix/runtime/clientRuntimeClient and transport behavior
agentix/runtime/serverFastAPI app, Socket.IO handlers, worker client, worker process, callable invocation
agentix/providerSandboxProvider protocol + backend discovery
agentix/cliBuild + deploy CLI (agentix build, agentix deploy, agentix plugin)
agentix/sioSandbox-side namespace API
agentix/utilslog + trace bridges
agentix/builderflake.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.