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
  • Sibling runtime and deployment repos checked out next to Agentix/ when testing full rollouts

​
Setup

git clone https://github.com/Agentiix/Agentix.git
cd Agentix
pip install -e '.[dev]'
pip install -e ../Agentix-Runtime-Basic
pip install -e ../Agentix-Deployment-Docker
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. 
agentix-server
agentix-server --port 9000
The server exposes /health; remote calls use /socket.io/.

​
Build the Runtime Base Image

Bundles extend a base image. Build it from the sibling runtime repo when testing end-to-end locally. 
docker build -t agentix/runtime:0.1.0 -f ../Agentix-Runtime-Basic/runtime/Dockerfile .
Rebuild the base image when runtime code or dependency versions change.

​
Build a Bundle

agentix build
agentix build path/to/project -o my-rollout:dev
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 image.

​
Smoke Test a Sandbox

import asyncio

from agentix import RuntimeClient
from agentix.bash import run
from agentix.deployment.base import SandboxConfig, session
from agentix.deployment.docker import DockerDeployment


async def main() -> None:
    deployment = DockerDeployment()
    config = SandboxConfig(image="python:3.13-slim", bundle="my-rollout:dev")

    async with session(deployment, config) as sandbox:
        async with RuntimeClient(sandbox.runtime_url) as client:
            result = await client.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/deploymentDeployment protocol and backend discovery
agentix/cliBuild command

​
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.