ASAREE

Analytical Sandbox for Agentic Research, Engineering, and Experimentation — a workbench for running LLM agents as designed experiments rather than one-off prompts.

You build a pipeline of agents on a visual protocol canvas, declare the factors you want to vary across it (model, effort, whether a critic gate is enabled, anything else bound to a node's config), and ASAREE materializes the full factorial design as cells, runs every replicate, and collects each replicate's metrics so the comparison is a measured result instead of an impression. Datasets are registered, split, and versioned as they pass between agents, and the tools the agents reach for are MCP servers, so a run is reproducible end to end.

ASAREE is built on top of Motoro, which provides the agent runtime, execution patterns, LLM service, and MCP integration. Motoro ships no HTTP layer, no auth, and no UI; ASAREE adds those, plus the experiment/protocol/dataset model, and depends on Motoro as a pinned library — in-process, not a service call.

Releases and development

For installation, reproducible research, and production deployments, use a tagged GitHub Release. The latest release is the recommended version for new installations. The project treats every published release tag as permanent so a deployment or experiment can be recreated from the same source later. Repository administrators enforce this policy with GitHub's release immutability setting; ordinary Git tags are not inherently immutable.

The main branch contains the latest development version. It may include changes that have not yet been released or fully validated for production, so do not use main when an exact, stable version matters.

Get started

You need git and Docker with Compose v2 (docker compose version), about 10 GB of free disk, and 10–20 minutes for the first build.

1. Install a release and start it. Open the releases page, choose a tag, and replace vX.Y.Z below with that tag (for example, v0.3.0).

git clone --branch vX.Y.Z --depth 1 https://github.com/EpistasisLab/ASAREE.git
cd ASAREE
cp .env.example .env
docker compose up -d --build

Contributors who intentionally want the current development version can clone main instead:

git clone --branch main https://github.com/EpistasisLab/ASAREE.git

That brings up Postgres, Redis, both migration steps, the API, the run worker, and the frontend.

2. Check it came up.

docker compose ps       # the two migrate services read "Exited (0)" — that's success
curl localhost:8000/health

3. Register. Open http://localhost:5173 and create an account.

4. Add an LLM API key for Anthropic, OpenAI, or Azure Foundry, under Profile → LLM credentials.

To keep them safe, put your own ASAREE_ENCRYPTION_KEY in .env before you save your first one — the sample value shipped in .env.example is public, and rotating the key later means re-entering every stored credential.

python3 -c "import secrets; print(secrets.token_urlsafe(32))"
docker compose up -d    # picks up the changed .env

5. Run an experiment. Follow the worked myocardial-infarction use case in publications/bioinformatics/README.md — five agents in series building a classifier on a public dataset. It picks up exactly where this step leaves off.

Everyday commands

docker compose logs -f asaree-app     # or asaree-worker, asaree-frontend
docker compose up -d --build          # rebuild after pulling new code
docker compose restart asaree-app     # apply an edited .env
docker compose down                   # stop, keep all data

The frontend hot-reloads from your checkout; backend changes need a rebuild.

docker compose up -d --build also runs pending database migrations. The one-shot motoro-migrate service upgrades Motoro's motoro database first; asaree-migrate then upgrades ASAREE's asaree database. The API and worker start only after both migration services exit successfully. docker compose restart asaree-app restarts only that service and does not rerun the migration services.

Before upgrading an existing production deployment, back up both databases. Then check out the desired release tag and recreate the stack:

git fetch --tags
git switch --detach vX.Y.Z
docker compose up -d --build
docker compose ps

To run the migrations explicitly against an external PostgreSQL server, build the release's migration image, supply URLs for both databases, and run the two chains in order. URL-encode any special characters in the credentials.

docker compose build motoro-migrate asaree-migrate

MOTORO_DB_URL='postgresql+asyncpg://USER:PASSWORD@HOST:PORT/motoro'
ASAREE_DB_URL='postgresql+asyncpg://USER:PASSWORD@HOST:PORT/asaree'

docker compose run --rm --no-deps motoro-migrate deploy --url "$MOTORO_DB_URL"
docker compose run --rm --no-deps asaree-migrate upgrade --url "$ASAREE_DB_URL"

docker compose run --rm --no-deps motoro-migrate current --url "$MOTORO_DB_URL"
docker compose run --rm --no-deps asaree-migrate current --url "$ASAREE_DB_URL"

The stack binds ports 8000 (API), 5173 (frontend), 5453 (Postgres), and 6381 (Redis). If one is taken, set POSTGRES_PORT or REDIS_PORT in .env; the first two are in compose.yml.

Every bundled MCP server — asaree-workspace, motoro-okf, and the six domain servers (asaree-sklearn-dc, -eda, -fs, -fte, -model, -stats, from mcp-servers/) — ships as a dependency of the app and registers itself each time the app or worker starts (see asaree.services.system_mcp_servers).

Resetting your dev environment

One Postgres server hosts two databases in a single volume — motoro (core's schema) and asaree (this repo's). Wiping it wipes both at once: every user, agent, experiment, dataset, MCP server registration, and LLM credential.

docker compose down -v
docker compose up -d --build

You're now at true zero. To get back to a working state:

1. Register a user in the GUI again (and, for SDK/notebook work, issue a token — see the SDK's Auth bootstrap).
2. Re-add the LLM credential, then re-run a use case notebook's early setup cells (experiment, dataset, agent creation) — or, for the public myocardial-infarction use case, follow its walkthrough: publications/bioinformatics/README.md.