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). The install script prints the export PATH line above
without applying it - run it, and add it to your shell profile to keep it. The pip path needs
no PATH step: agentx-trace-eval lands wherever pip already puts console scripts. Once the
engine is up, the startup log prints the default project’s key - logs are structured JSON
lines (pipe through npx pino-pretty for a readable form):
--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):
./build.sh runs rm -rf web at the repo root, so it destroys a manually fetched dashboard
bundle placed there. Without a sibling AgentX-eval-front checkout it re-downloads the
latest dashboard release; set AGENTX_WEB_RELEASE_TAG=vX.Y.Z to pin the dashboard version
when building from source.
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 ...)). --upgrade also refuses to
overwrite a locally-built bundle that is newer than the latest release (a provable downgrade,
judged by both bundles’ build-info.json stamps) unless AGENTX_WEB_FORCE=1 makes the
roll-back deliberate.
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. 
