Skip to main content
Prebuilt releases cover macOS and Linux on arm64/amd64 - no Go, Node, or Bun needed at runtime. Pick one path:

​
Quick install (prebuilt)

Both download the same prebuilt release (engine, CLI, dashboard) into ~/.agentx/bin (override with AGENTX_INSTALL_DIR). Once it’s up:
--dev opens the dashboard in your browser; omit it to run headless (behind a process manager, for example) - the API comes up identically either way.

​
Docker

Open http://localhost:4700 - the dashboard connects itself (in the default auth-disabled mode the engine hands the browser the Default project’s API key, nothing to paste). The key from docker logs is what your SDK/scripts use as AGENTX_API_KEY; it prints on every start. For multi-user or network-exposed deployments set -e AGENTX_AUTH=enabled, which requires sign-in and never hands the key out.
  • /data holds the SQLite database and config (AGENTX_HOME) - mount a named volume so state survives recreation, or set AGENTX_DB_URL to your Postgres and skip the volume.
  • Pass provider keys with -e OPENAI_API_KEY=... (or set them later in Platform Settings).
  • The image has a /health HEALTHCHECK.
  • The build pulls the latest dashboard bundle and revalidates it on every rebuild (ETag-checked ADD layer), so a newly published dashboard is picked up with no --no-cache. Pin one with --build-arg AGENTX_WEB_URL=.../releases/download/vX.Y.Z/agentx-web.tar.gz.
The repo also ships two Compose files: docker-compose.yml (engine + Postgres) and docker-compose.enterprise.yml (engine + Postgres + ClickHouse - the enterprise tier), plus a Helm chart at deploy/helm/agentx.

​
Build from source

Prerequisites: Node.js + Yarn; Go and Bun only for the compiled single-binary distribution, not day-to-day dev.
That’s the whole dev loop: yarn dev builds the @agentx/judge-core workspace package automatically (a ~1s step), .env is optional, and if the repo-root web/ is missing dev mode downloads the prebuilt dashboard bundle from the repo’s releases on first boot. An existing web/ is never touched on a normal boot - see Upgrading for refreshing it. Offline, fetch it manually (into the repo root, not engine/ - the repo-root web/ is the one canonical bundle location for a checkout, and a copy under engine/web is ignored):
For the full packaged layout (compiled engine binary + Go CLI, exactly what a release install looks like):

​
Upgrading

The engine and the dashboard version independently (Platform Settings shows both in its lower-right corner, e.g. Engine v0.3.8 · UI v0.3.6; a source checkout reports dev). Dashboard. A downloaded dashboard bundle is never touched on a normal boot - without this, a source host quietly serves whatever it downloaded first, forever. Pass --upgrade to re-download the latest dashboard release before serving; it works the same in every layout:
The new bundle is staged and verified before it replaces the old one, so a failed or interrupted download keeps the existing dashboard serving and logs a warning - --upgrade can never break a working UI. The boot log states what happened either way (Upgrading the dashboard bundle in ... (currently built ...)). Engine. Re-run the installer for your path: curl | bash again (installs the latest release into ~/.agentx/bin; pin a release with AGENTX_VERSION=vX.Y.Z), or agentx-trace-eval --update for the SDK launcher (its own flag, consumed before the handoff: re-downloads the engine release). A source checkout upgrades with git pull. Both at once, on the launcher: agentx-trace-eval --update --upgrade refreshes the engine and then the dashboard.

​
Connect

The dashboard connects itself: in the default auth-disabled mode the engine hands the browser the Default project API key on first visit, so you land straight on a working screen. (A connect screen only appears against an older engine that doesn’t hand the key out.) Because anyone who can reach the port gets the key, disabled mode is for local/trusted use - for a shared, multi-user, or network-exposed instance, use AGENTX_AUTH=enabled, which requires sign-in and never hands the key out. Point the SDK at the engine with the same key - no separate SDK, no code changes:
Everything under Tracing, Monitor, and Evaluations works the same against self-host as against the hosted API.

​
The agentx-trace-eval launcher

agentx-trace-eval (bundled with agentx-python) is a thin launcher, not a reimplementation: the first run downloads the engine/CLI release into ~/.agentx/bin and hands off to it, so installing the Python SDK stays light for the common hosted-API case.
  • Each SDK release pins the engine release it was tested against, and the launcher converges the install to that pin - upgrading the SDK upgrades the engine to the matching pair.
  • AGENTX_TRACE_EVAL_VERSION overrides the pin with a specific tag, or latest (which trusts whatever is installed and prints a notice when a newer release exists).
  • --update is the launcher’s own flag (force-reinstall the resolved engine release); every other flag - --dev, --upgrade, --port, --db-url - passes through to agentx-server untouched. See Upgrading.
  • AGENTX_TRACE_EVAL_SKIP_WEB skips downloading the dashboard bundle for headless use (CI, for example).
There is no Homebrew formula - curl | bash, the SDK launcher, and Docker are the supported paths.