Development Guide¶

Prerequisites¶

Python 3.11+
Docker — the only host requirement. Nix runs inside the builder stage of tests/closure-docker/Dockerfile.

Setup¶

git clone https://github.com/Agentiix/Agentix.git
cd Agentix
pip install -e '.[dev]'        # fastapi, uvicorn, httpx, pytest, ruff

Daily Workflow¶

Run the runtime server locally (no sandbox)¶

agentix-server                 # http://localhost:8000
agentix-server --port 9000

Without any closures mounted, the server exposes its built-ins (/health, /exec, /upload, /download). Useful for iterating on the runtime without the Docker round-trip.

Build closures¶

The repo's runtime and mock closures share one Dockerfile:

docker build -t agentix/runtime:dev      -f tests/closure-docker/Dockerfile .
docker build -t agentix/mock-agent:dev   -f tests/closure-docker/Dockerfile tests/closures/mock-agent
docker build -t agentix/mock-dataset:dev -f tests/closure-docker/Dockerfile tests/closures/mock-dataset

Smoke-test end-to-end in Docker¶

import asyncio
from agentix import DockerDeployment, RuntimeClient, SandboxConfig
from agentix_closures import mock_agent  # typed stubs

async def main():
    deployment = DockerDeployment()
    config = SandboxConfig(
        image="ubuntu:24.04",
        runtime="agentix/runtime:dev",
        closures=["agentix/mock-agent:dev"],
    )
    async with deployment.session(config) as sb:
        async with RuntimeClient(sb.runtime_url) as c:
            print(await c.run("uname -a"))
            result = await c.remote(mock_agent.run, instruction="hi")
            print(result.patch)

asyncio.run(main())

Lint & test¶

ruff check agentix/ tests/
pytest                      # unit tests
pytest -x                   # stop on first failure

Adding a new closure¶

Everything inside the sandbox is a closure. Copy a reference and write your own Dockerfile:

cp -r tests/closures/mock-agent my-closure
# edit my-closure/default.nix and the source package for your logic
# author my-closure/Dockerfile (see tests/closure-docker/Dockerfile for a working reference)
docker build -t my-closure:0.1.0 ./my-closure

Use it:

SandboxConfig(
    image="ubuntu:24.04",
    runtime="agentix/runtime:dev",
    closures={"mine": "my-closure:0.1.0"},
)

See docs/closure-protocol.md for the closure ABI.