> ## Documentation Index
> Fetch the complete documentation index at: https://developers.agentx.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> curl | bash, the Python SDK launcher, Docker, or from source - then connect the dashboard and SDK

## Docker

```bash theme={null}
git clone https://github.com/AgentX-ai/AgentX-Trace-Eval.git && cd AgentX-Trace-Eval
docker build -t agentx-selfhost .
docker run -d -p 4700:4700 -v agentx-data:/data agentx-selfhost
docker logs $(docker ps -lq) 2>&1 | grep "API key"
```

Open [http://localhost:4700](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`.

## Install from source

<CodeGroup>
  ```bash curl | bash theme={null}
  curl -sSL https://raw.githubusercontent.com/AgentX-ai/AgentX-Trace-Eval/main/install.sh | bash
  agentx-server --dev
  ```

  ```bash Python SDK theme={null}
  pip install agentx-python
  agentx-trace-eval --dev
  ```
</CodeGroup>

Both download the same prebuilt release (engine, CLI, dashboard) for macOS/Linux on
arm64/amd64 - no Go, Node, or Bun needed. Once it's up:

```
AgentX self-host engine listening on http://localhost:4700
Default project API key: agtx_local_...
```

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

## 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`](/authentication#multi-user-mode-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:

```bash theme={null}
export AGENTX_API_BASE_URL=http://localhost:4700/api/v1
export AGENTX_API_KEY=agtx_local_...   # from the startup log
```

```python theme={null}
from agentx import AgentX

client = AgentX.from_env()

with client.tracer.trace("my-agent") as span:
    span.input = "hello"
    span.output = "hi there"
```

Everything under [Tracing](/sdk/tracing), [Monitor](/sdk/monitor), and
[Evaluations](/sdk/evaluations/overview) works the same against self-host as against the hosted
API.

## From source

**Prerequisites:** Node.js + [Yarn](https://yarnpkg.com/); [Go](https://go.dev/) and
[Bun](https://bun.sh/) only for the compiled single-binary distribution, not day-to-day dev.

```bash theme={null}
git clone https://github.com/AgentX-ai/AgentX-Trace-Eval.git && cd AgentX-Trace-Eval/engine
yarn && yarn dev --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 `web/` is missing dev mode downloads the
prebuilt dashboard bundle from the repo's releases on first boot. Offline, fetch it manually:

```bash theme={null}
mkdir -p web && curl -fsSL https://github.com/AgentX-ai/AgentX-Trace-Eval/releases/latest/download/agentx-web.tar.gz | tar -xz -C web
```

For the full packaged layout (compiled engine binary + Go CLI, exactly what a release install
looks like):

```bash theme={null}
./build.sh
./dist/agentx-server --dev
```

## The `agentx-trace-eval` launcher

`agentx-trace-eval` (bundled with `agentx-python`) is a thin launcher, not a reimplementation:
the first run downloads the matching engine/CLI release into `~/.agentx/bin` and hands off to
it, so installing the Python SDK stays light for the common hosted-API case.
`AGENTX_TRACE_EVAL_VERSION` pins a release; `AGENTX_TRACE_EVAL_SKIP_WEB` skips the dashboard
for headless use.

There is no Homebrew formula - `curl | bash`, the SDK launcher, and Docker are the supported
paths.