curl -sSL https://raw.githubusercontent.com/AgentX-ai/AgentX-trace-eval/main/install.sh | bashexport PATH="$HOME/.agentx/bin:$PATH" # the installer prints this line but doesn't apply itagentx-server --dev
pip install agentx-pythonagentx-trace-eval --dev
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):
{"level":30,"time":"2026-09-13T09:41:07.213Z","msg":"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.
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.
git clone https://github.com/AgentX-ai/AgentX-trace-eval.git && cd AgentX-trace-eval/engineyarn && 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 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):
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):
./build.sh./dist/agentx-server --dev
./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:
export AGENTX_API_BASE_URL=http://localhost:4700/api/v1export AGENTX_API_KEY=agtx_local_... # from the startup log
from agentx import AgentXclient = AgentX.from_env()with client.tracer.trace("my-agent") as span: span.input = "hello" span.output = "hi there"
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.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"AgentX","colors":{"primary":"#2A5699","light":"#5C8DCC","dark":"#1A3F73"},"logo":{"light":"https://mintcdn.com/agentx-ffe8d995/ZTzZ3HDQJ-RJxymw/logo/light.png?fit=max\u0026auto=format\u0026n=ZTzZ3HDQJ-RJxymw\u0026q=85\u0026s=c1e30c949dc1cc2aaa3a137c1ee5c77f","dark":"https://mintcdn.com/agentx-ffe8d995/ZTzZ3HDQJ-RJxymw/logo/dark.png?fit=max\u0026auto=format\u0026n=ZTzZ3HDQJ-RJxymw\u0026q=85\u0026s=35a521e090f7875c15bef7ae392af788"},"favicon":"https://mintcdn.com/agentx-ffe8d995/FRrvmlkH0m2BUb9c/logo/favicon.png?fit=max\u0026auto=format\u0026n=FRrvmlkH0m2BUb9c\u0026q=85\u0026s=e87d636d38c8e6e187b4be187e72381d","api":{"mdx":{"auth":{"method":"key","name":"x-api-key"},"server":"http://localhost:4700"}},"navbar":{"primary":{"type":"github","href":"https://github.com/AgentX-ai/AgentX-trace-eval"}},"footer":{"socials":{"website":"https://www.agentx.so/mcp/ai-evaluation","github":"https://github.com/AgentX-ai/AgentX-trace-eval"}},"styling":{"latex":true},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"agentx-ffe8d995","hasAudioNarration":false,"actualSubdomain":"agentx-ffe8d995","customDomains":["developers.agentx.so"],"gitSource":{"type":"github","owner":"agentx-ai","repo":"agentx-mintlify","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6ac683381cb9dd011c327d04","clientVersion":"0.0.4270","searchFilterCounts":[{"language":"default","tag":"API Reference","count":25},{"language":"default","tag":"Offline Evaluation","count":24},{"language":"default","tag":"Trace","count":17},{"language":"default","tag":"Scorers \u0026 Monitoring","count":16},{"language":"default","tag":"Custom Evaluations","count":13},{"language":"default","tag":"Documentation","count":13},{"language":"default","tag":"Framework Integrations","count":12},{"language":"default","tag":"Framework Examples","count":10},{"language":"default","tag":"Tracing","count":8},{"language":"default","tag":"Live Traffic Scoring","count":7}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"treatment","enabled":true,"payload":{"type":"string","value":"treatment"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[]}
{"page":{"pagePath":"self-host/installation","slug":"/self-host/installation","pageMetadata":{"title":"Installation","description":"curl | bash, the Python SDK launcher, Docker, or build from source - then connect the dashboard and SDK","href":"/self-host/installation"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"curl | bash, the Python SDK launcher, Docker, or build from source - then connect the dashboard and SDK\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,em:`em`,li:`li`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,CodeGroup,Heading,Table,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!CodeGroup)_missingMdxReference(`CodeGroup`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`Prebuilt releases cover macOS and Linux on arm64/amd64 - no Go, Node, or Bun needed at runtime.\nPick one path:`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Path`}),_jsx(_components.th,{children:`Best for`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.a,{href:`#quick-install-prebuilt`,children:`Quick install`})}),_jsx(_components.td,{children:`Trying it out, local development`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.a,{href:`#docker`,children:`Docker`})}),_jsx(_components.td,{children:`Servers, teams, anything long-running`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.a,{href:`#build-from-source`,children:`From source`})}),_jsx(_components.td,{children:`Contributing, patching the engine`})]})]})]}),`\n`,_jsx(Heading,{level:`2`,id:`quick-install-prebuilt`,children:`Quick install (prebuilt)`}),`\n`,_jsxs(CodeGroup,{children:[_jsx(CodeBlock,{filename:`curl | bash`,numberOfLines:`3`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`3`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -sSL`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` https://raw.githubusercontent.com/AgentX-ai/AgentX-trace-eval/main/install.sh`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` |`}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:` bash`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`export`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` PATH`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`$HOME`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`/.agentx/bin:`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`$PATH`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"`}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # the installer prints this line but doesn't apply it`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`agentx-server`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --dev`})]}),`\n`]})})}),_jsx(CodeBlock,{filename:`Python SDK`,numberOfLines:`2`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`pip`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` install`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` agentx-python`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`agentx-trace-eval`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --dev`})]}),`\n`]})})})]}),`\n`,_jsxs(_components.p,{children:[`Both download the same prebuilt release (engine, CLI, dashboard) into `,_jsx(_components.code,{children:`~/.agentx/bin`}),`\n(override with `,_jsx(_components.code,{children:`AGENTX_INSTALL_DIR`}),`). The install script prints the `,_jsx(_components.code,{children:`export PATH`}),` line above\nwithout applying it - run it, and add it to your shell profile to keep it. The pip path needs\nno PATH step: `,_jsx(_components.code,{children:`agentx-trace-eval`}),` lands wherever pip already puts console scripts. Once the\nengine is up, the startup log prints the default project’s key - logs are structured JSON\nlines (pipe through `,_jsx(_components.code,{children:`npx pino-pretty`}),` for a readable form):`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`json`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`json`,children:_jsxs(_components.code,{language:`json`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`{`}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"level\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`:`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:`30`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"time\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"2026-09-13T09:41:07.213Z\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`}),_jsx(_components.span,{style:{color:`#116329`,\"--shiki-dark\":`#9CDCFE`},children:`\"msg\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Default project API key: agtx_local_...\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`}`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`--dev`}),` opens the dashboard in your browser; omit it to run headless (behind a process manager,\nfor example) - the API comes up identically either way.`]}),`\n`,_jsx(Heading,{level:`2`,id:`docker`,children:`Docker`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`4`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`4`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`git`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` clone`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` https://github.com/AgentX-ai/AgentX-trace-eval.git`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` \u0026\u0026 `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#DCDCAA`},children:`cd`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` AgentX-trace-eval`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` build`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -t`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` agentx-selfhost`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` .`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` run`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -d`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -p`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` 4700:4700`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -v`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` agentx-data:/data`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` agentx-selfhost`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` logs`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` $(`}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` ps`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -lq`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`) `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`2>\u00261`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` |`}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:` grep`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"API key\"`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Open `,_jsx(_components.a,{href:`http://localhost:4700`,children:`http://localhost:4700`}),` - the dashboard connects itself (in the default auth-disabled mode\nthe engine hands the browser the Default project’s API key, nothing to paste). The key from\n`,_jsx(_components.code,{children:`docker logs`}),` is what your SDK/scripts use as `,_jsx(_components.code,{children:`AGENTX_API_KEY`}),`; it prints on every start. For\nmulti-user or network-exposed deployments set `,_jsx(_components.code,{children:`-e AGENTX_AUTH=enabled`}),`, which requires sign-in\nand never hands the key out.`]}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`/data`}),` holds the SQLite database and config (`,_jsx(_components.code,{children:`AGENTX_HOME`}),`) - mount a named volume so state\nsurvives recreation, or set `,_jsx(_components.code,{children:`AGENTX_DB_URL`}),` to your Postgres and skip the volume.`]}),`\n`,_jsxs(_components.li,{children:[`Pass provider keys with `,_jsx(_components.code,{children:`-e OPENAI_API_KEY=...`}),` (or set them later in Platform Settings).`]}),`\n`,_jsxs(_components.li,{children:[`The image has a `,_jsx(_components.code,{children:`/health`}),` HEALTHCHECK.`]}),`\n`,_jsxs(_components.li,{children:[`The build pulls the latest dashboard bundle and revalidates it on every rebuild (ETag-checked\n`,_jsx(_components.code,{children:`ADD`}),` layer), so a newly published dashboard is picked up with no `,_jsx(_components.code,{children:`--no-cache`}),`. Pin one with\n`,_jsx(_components.code,{children:`--build-arg AGENTX_WEB_URL=.../releases/download/vX.Y.Z/agentx-web.tar.gz`}),`.`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`The repo also ships two Compose files: `,_jsx(_components.code,{children:`docker-compose.yml`}),` (engine + Postgres) and\n`,_jsx(_components.code,{children:`docker-compose.enterprise.yml`}),` (engine + Postgres + ClickHouse - the\n`,_jsx(_components.a,{href:`/self-host/configuration#deployment-tiers`,children:`enterprise tier`}),`), plus a Helm chart at\n`,_jsx(_components.code,{children:`deploy/helm/agentx`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`build-from-source`,children:`Build from source`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Prerequisites:`}),` Node.js + `,_jsx(_components.a,{href:`https://yarnpkg.com/`,children:`Yarn`}),`; `,_jsx(_components.a,{href:`https://go.dev/`,children:`Go`}),` and\n`,_jsx(_components.a,{href:`https://bun.sh/`,children:`Bun`}),` only for the compiled single-binary distribution, not day-to-day dev.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`git`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` clone`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` https://github.com/AgentX-ai/AgentX-trace-eval.git`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` \u0026\u0026 `}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#DCDCAA`},children:`cd`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` AgentX-trace-eval/engine`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`yarn`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` \u0026\u0026 `}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`yarn`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` dev`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --dev`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`That’s the whole dev loop: `,_jsx(_components.code,{children:`yarn dev`}),` builds the `,_jsx(_components.code,{children:`@agentx/judge-core`}),` workspace package\nautomatically (a ~1s step), `,_jsx(_components.code,{children:`.env`}),` is optional, and if the repo-root `,_jsx(_components.code,{children:`web/`}),` is missing dev mode\ndownloads the prebuilt dashboard bundle from the repo’s releases on first boot. An existing\n`,_jsx(_components.code,{children:`web/`}),` is never touched on a normal boot - see `,_jsx(_components.a,{href:`#upgrading`,children:`Upgrading`}),` for refreshing it.\nOffline, fetch it manually (into the `,_jsx(_components.strong,{children:`repo root`}),`, not `,_jsx(_components.code,{children:`engine/`}),` - the repo-root `,_jsx(_components.code,{children:`web/`}),` is the\none canonical bundle location for a checkout, and a copy under `,_jsx(_components.code,{children:`engine/web`}),` is ignored):`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`mkdir`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -p`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` web`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` \u0026\u0026 `}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -fsSL`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` https://github.com/AgentX-ai/AgentX-trace-eval/releases/latest/download/agentx-web.tar.gz`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` |`}),_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:` tar`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -xz`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -C`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` web`})]}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`For the full packaged layout (compiled engine binary + Go CLI, exactly what a release install\nlooks like):`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`2`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`./build.sh`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`./dist/agentx-server`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --dev`})]}),`\n`]})})}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[_jsx(_components.code,{children:`./build.sh`}),` runs `,_jsx(_components.code,{children:`rm -rf web`}),` at the repo root, so it destroys a manually fetched dashboard\nbundle placed there. Without a sibling `,_jsx(_components.code,{children:`AgentX-eval-front`}),` checkout it re-downloads the\nlatest dashboard release; set `,_jsx(_components.code,{children:`AGENTX_WEB_RELEASE_TAG=vX.Y.Z`}),` to pin the dashboard version\nwhen building from source.`]})}),`\n`,_jsx(Heading,{level:`2`,id:`upgrading`,children:`Upgrading`}),`\n`,_jsxs(_components.p,{children:[`The engine and the dashboard version independently (Platform Settings shows both in its\nlower-right corner, e.g. `,_jsx(_components.code,{children:`Engine v0.3.8 · UI v0.3.6`}),`; a source checkout reports `,_jsx(_components.code,{children:`dev`}),`).`]}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Dashboard.`}),` A downloaded dashboard bundle is never touched on a normal boot - without this,\na source host quietly serves whatever it downloaded first, forever. Pass `,_jsx(_components.code,{children:`--upgrade`}),` to\nre-download the latest dashboard release before serving; it works the same in every layout:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`3`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`3`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`yarn`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` dev`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --upgrade`}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # source checkout (from engine/)`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`agentx-server`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --upgrade`}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # curl | bash install`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`agentx-trace-eval`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --upgrade`}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # Python SDK launcher`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`The new bundle is staged and verified before it replaces the old one, so a failed or\ninterrupted download keeps the existing dashboard serving and logs a warning - `,_jsx(_components.code,{children:`--upgrade`}),` can\nnever break a working UI. The boot log states what happened either way\n(`,_jsx(_components.code,{children:`Upgrading the dashboard bundle in ... (currently built ...)`}),`). `,_jsx(_components.code,{children:`--upgrade`}),` also refuses to\noverwrite a locally-built bundle that is `,_jsx(_components.em,{children:`newer`}),` than the latest release (a provable downgrade,\njudged by both bundles’ `,_jsx(_components.code,{children:`build-info.json`}),` stamps) unless `,_jsx(_components.code,{children:`AGENTX_WEB_FORCE=1`}),` makes the\nroll-back deliberate.`]}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Engine.`}),` Re-run the installer for your path: `,_jsx(_components.code,{children:`curl | bash`}),` again (installs the latest\nrelease into `,_jsx(_components.code,{children:`~/.agentx/bin`}),`; pin a release with `,_jsx(_components.code,{children:`AGENTX_VERSION=vX.Y.Z`}),`), or\n`,_jsx(_components.code,{children:`agentx-trace-eval --update`}),` for the SDK launcher (its own flag, consumed before the handoff:\nre-downloads the engine release). A source checkout upgrades with `,_jsx(_components.code,{children:`git pull`}),`.`]}),`\n`,_jsxs(_components.p,{children:[`Both at once, on the launcher: `,_jsx(_components.code,{children:`agentx-trace-eval --update --upgrade`}),` refreshes the engine and\nthen the dashboard.`]}),`\n`,_jsx(Heading,{level:`2`,id:`connect`,children:`Connect`}),`\n`,_jsxs(_components.p,{children:[`The dashboard connects itself: in the default auth-disabled mode the engine hands the browser\nthe `,_jsx(_components.code,{children:`Default project`}),` API key on first visit, so you land straight on a working screen. (A\nconnect screen only appears against an older engine that doesn’t hand the key out.) Because\nanyone who can reach the port gets the key, disabled mode is for local/trusted use - for a\nshared, multi-user, or network-exposed instance, use\n`,_jsx(_components.a,{href:`/authentication#the-three-modes`,children:_jsx(_components.code,{children:`AGENTX_AUTH=enabled`})}),`, which requires\nsign-in and never hands the key out.`]}),`\n`,_jsx(_components.p,{children:`Point the SDK at the engine with the same key - no separate SDK, no code changes:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`export`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` AGENTX_API_BASE_URL`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`http`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`://`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`localhost`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`:`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`4700`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`/`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`api`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`/`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`v1`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`export`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` AGENTX_API_KEY`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`agtx_local_`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`... `}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:`# from the startup log`})]}),`\n`]})})}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`7`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`7`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`from`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` agentx `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`import`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` AgentX`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`client `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` AgentX.from_env()`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`with`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` client.tracer.trace(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"my-agent\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`) `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`as`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` span:`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` span.input `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"hello\"`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` span.output `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"hi there\"`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Everything under `,_jsx(_components.a,{href:`/sdk/tracing`,children:`Tracing`}),`, `,_jsx(_components.a,{href:`/sdk/monitor`,children:`Monitor`}),`, and\n`,_jsx(_components.a,{href:`/sdk/evaluations/overview`,children:`Evaluations`}),` works the same against self-host as against the hosted\nAPI.`]}),`\n`,_jsxs(Heading,{level:`2`,id:`the-agentx-trace-eval-launcher`,children:[`The `,_jsx(_components.code,{children:`agentx-trace-eval`}),` launcher`]}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`agentx-trace-eval`}),` (bundled with `,_jsx(_components.code,{children:`agentx-python`}),`) is a thin launcher, not a reimplementation:\nthe first run downloads the engine/CLI release into `,_jsx(_components.code,{children:`~/.agentx/bin`}),` and hands off to it, so\ninstalling the Python SDK stays light for the common hosted-API case.`]}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`Each SDK release pins the engine release it was tested against, and the launcher converges\nthe install to that pin - upgrading the SDK upgrades the engine to the matching pair.`}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`AGENTX_TRACE_EVAL_VERSION`}),` overrides the pin with a specific tag, or `,_jsx(_components.code,{children:`latest`}),` (which trusts\nwhatever is installed and prints a notice when a newer release exists).`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`--update`}),` is the launcher’s own flag (force-reinstall the resolved engine release); every\nother flag - `,_jsx(_components.code,{children:`--dev`}),`, `,_jsx(_components.code,{children:`--upgrade`}),`, `,_jsx(_components.code,{children:`--port`}),`, `,_jsx(_components.code,{children:`--db-url`}),` - passes through to `,_jsx(_components.code,{children:`agentx-server`}),`\nuntouched. See `,_jsx(_components.a,{href:`#upgrading`,children:`Upgrading`}),`.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`AGENTX_TRACE_EVAL_SKIP_WEB`}),` skips downloading the dashboard bundle for headless use (CI, for\nexample).`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`There is no Homebrew formula - `,_jsx(_components.code,{children:`curl | bash`}),`, the SDK launcher, and Docker are the supported\npaths.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Installation","description":"curl | bash, the Python SDK launcher, Docker, or build from source - then connect the dashboard and SDK","href":"/self-host/installation"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Quick install (prebuilt)","slug":"quick-install-prebuilt","depth":2,"children":[]},{"title":"Docker","slug":"docker","depth":2,"children":[]},{"title":"Build from source","slug":"build-from-source","depth":2,"children":[]},{"title":"Upgrading","slug":"upgrading","depth":2,"children":[]},{"title":"Connect","slug":"connect","depth":2,"children":[]},{"title":"The agentx-trace-eval launcher","slug":"the-agentx-trace-eval-launcher","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"agentx-ffe8d995","siteName":"AgentX","title":"Installation - AgentX","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-09-14T02:27:25.999Z","originalFileLocation":"self-host/installation.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"curl | bash, the Python SDK launcher, Docker, or build from source - then connect the dashboard and SDK\">\u003cmeta data-mint-head name=\"application-name\" content=\"AgentX\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/agentx-ffe8d995/sticQuUfAA1h_xwo/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/agentx-ffe8d995/sticQuUfAA1h_xwo/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/agentx-ffe8d995/sticQuUfAA1h_xwo/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/agentx-ffe8d995/sticQuUfAA1h_xwo/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/agentx-ffe8d995/sticQuUfAA1h_xwo/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/agentx-ffe8d995/sticQuUfAA1h_xwo/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/agentx-ffe8d995/sticQuUfAA1h_xwo/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/agentx-ffe8d995/sticQuUfAA1h_xwo/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/agentx-ffe8d995/sticQuUfAA1h_xwo/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Installation - AgentX\">\u003cmeta data-mint-head property=\"og:description\" content=\"curl | bash, the Python SDK launcher, Docker, or build from source - then connect the dashboard and SDK\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"AgentX\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://developers.agentx.so/self-host/installation\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://agentx-ffe8d995.mintlify.site/_mintlify/api/og/v2?division=Self-Hosting\u0026amp;title=Installation\u0026amp;description=curl+%7C+bash%2C+the+Python+SDK+launcher%2C+Docker%2C+or+build+from+source+-+then+connect+the+dashboard+and+SDK\u0026amp;theme=2ebdc38e645cd0f197f78a50\u0026amp;signature=4ad99b738a7fb3ea449a7ab039b80c0d0c648f47f19b25c4221bacb6550aa947\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Installation - AgentX\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"curl | bash, the Python SDK launcher, Docker, or build from source - then connect the dashboard and SDK\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://agentx-ffe8d995.mintlify.site/_mintlify/api/og/v2?division=Self-Hosting\u0026amp;title=Installation\u0026amp;description=curl+%7C+bash%2C+the+Python+SDK+launcher%2C+Docker%2C+or+build+from+source+-+then+connect+the+dashboard+and+SDK\u0026amp;theme=2ebdc38e645cd0f197f78a50\u0026amp;signature=4ad99b738a7fb3ea449a7ab039b80c0d0c648f47f19b25c4221bacb6550aa947\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/agentx-ffe8d995/sticQuUfAA1h_xwo/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"AgentX\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#2A5699\">\u003clink data-mint-head rel=\"canonical\" href=\"https://developers.agentx.so/self-host/installation\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/self-host/installation.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://developers.agentx.so/#organization\",\"name\":\"AgentX\",\"url\":\"https://developers.agentx.so\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/agentx-ffe8d995/ZTzZ3HDQJ-RJxymw/logo/light.png?fit=max\u0026auto=format\u0026n=ZTzZ3HDQJ-RJxymw\u0026q=85\u0026s=c1e30c949dc1cc2aaa3a137c1ee5c77f\"}},{\"@type\":\"WebSite\",\"@id\":\"https://developers.agentx.so#website\",\"name\":\"AgentX\",\"url\":\"https://developers.agentx.so\",\"publisher\":{\"@id\":\"https://developers.agentx.so/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://developers.agentx.so/self-host/installation#webpage\",\"url\":\"https://developers.agentx.so/self-host/installation\",\"name\":\"Installation\",\"description\":\"curl | bash, the Python SDK launcher, Docker, or build from source - then connect the dashboard and SDK\",\"dateModified\":\"2026-09-14T02:27:25.999Z\",\"isPartOf\":{\"@id\":\"https://developers.agentx.so#website\"},\"breadcrumb\":{\"@id\":\"https://developers.agentx.so/self-host/installation#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://developers.agentx.so/self-host/installation#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Self-Hosting\",\"item\":\"https://developers.agentx.so/self-host/overview\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Installation\",\"item\":\"https://developers.agentx.so/self-host/installation\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://developers.agentx.so/self-host/installation#article\",\"headline\":\"Installation\",\"name\":\"Installation\",\"description\":\"curl | bash, the Python SDK launcher, Docker, or build from source - then connect the dashboard and SDK\",\"url\":\"https://developers.agentx.so/self-host/installation\",\"mainEntityOfPage\":{\"@id\":\"https://developers.agentx.so/self-host/installation#webpage\"},\"dateModified\":\"2026-09-14T02:27:25.999Z\",\"publisher\":{\"@id\":\"https://developers.agentx.so/#organization\"},\"isPartOf\":{\"@id\":\"https://developers.agentx.so#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"AgentX\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"AgentX\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/self-host/installation.md","siteName":"AgentX","nav":{"global":null,"tabs":[{"tab":"Documentation","groups":[{"group":"Get Started","pages":[{"title":"Introduction","href":"/introduction"},{"title":"Quickstart","href":"/quickstart"},{"title":"Authentication","href":"/authentication"},{"title":"Concepts","href":"/concepts"},{"title":"Errors","href":"/errors"}]},{"group":"Self-Hosting","pages":[{"title":"Self-Host Overview","description":"The full Trace, Monitor, Evaluate, and Improve stack on your own machine - no account, bring your own LLM keys","href":"/self-host/overview"},{"title":"Installation","href":"/self-host/installation"},{"title":"Configuration","description":"Every flag and environment variable with its default, deployment tiers, Prometheus metrics, the audit trail, and the end-to-end smoke test","href":"/self-host/configuration"},{"title":"Backup \u0026 export","href":"/self-host/backup"},{"title":"High availability \u0026 DR","href":"/self-host/high-availability"}]},{"group":"Python SDK","pages":[{"title":"Python SDK Overview","href":"/sdk/overview"},{"title":"Python SDK Reference","href":"/sdk/python-reference"}]},{"group":"Guides","pages":[{"title":"Coming from DeepEval","href":"/monitor/coming-from-deepeval"}]}]},{"tab":"Trace","pages":[{"title":"Trace","href":"/sdk/tracing"}]},{"tab":"Scorers \u0026 Monitoring","pages":[{"title":"Scorers \u0026 Monitoring","href":"/monitor/scorers"}]},{"tab":"Offline Evaluation","pages":[{"title":"Offline Evaluation","href":"/sdk/evaluations/overview"}]},{"tab":"Improve","pages":[{"title":"Improve","href":"/improve/tool-schemas"}]},{"tab":"CI/CD","pages":[{"title":"CI/CD","href":"/integrations/self-host-ci"}]},{"tab":"API Reference","pages":[{"title":"API Reference","href":"/api-reference/tracing/submit-trace"}]}]},"basePath":"","title":"Installation - AgentX","deploymentId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","buildId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","dynamics":[],"chunks":[]}