Self-hosting quickstart
Ivy runs anywhere Docker runs. One docker compose up starts the ingest router, the OpenTelemetry Collector, ClickHouse, and the API with the dashboard and MCP server. It is MIT licensed and has no limits.
Start it
git clone https://github.com/ivytrace/ivy && cd ivy
docker compose -f deploy/docker-compose.yml up -d --build| Service | Address |
|---|---|
| Dashboard, API and MCP server | http://localhost:3000 (API at /api, MCP at /mcp) |
| OTLP/HTTP ingest | http://localhost:4318/v1/traces, with Authorization: Bearer <key> |
| ClickHouse HTTP | http://localhost:8123 |
On startup Ivy creates a default workspace, its default project and an ingest key (IVY_INGEST_API_KEY, dev-ingest-key unless you set it). Stop with docker compose -f deploy/docker-compose.yml down (add -v to delete the data).
Settings that matter
Set these in your shell or in deploy/.env. Change the defaults before exposing Ivy to a network.
| Variable | Default | |
|---|---|---|
IVY_INGEST_API_KEY |
dev-ingest-key |
Key of the default project |
IVY_COLLECTOR_TOKEN |
dev-collector-token |
Shared secret between the ingest router and the collector |
IVY_CLICKHOUSE_USER, IVY_CLICKHOUSE_PASSWORD |
ivy, ivy |
ClickHouse credentials |
IVY_RETENTION_DAYS |
30 |
How long traces are kept (set before the first start) |
IVY_PUBLIC_URL |
The URL people use to reach Ivy | |
IVY_INGEST_PUBLIC_URL |
The ingest URL your Lambda functions can reach (needed for auto-trace) | |
IVY_SECRET_KEY |
Encrypts per-project auto-trace keys |
The deploy README lists every variable.
Sign-in with OIDC
Without OIDC, the dashboard, API and MCP server run open (for setups behind your own authenticating proxy) and the dashboard shows an "authentication disabled" banner. To require sign-in:
- Register a public SPA client with your provider (Keycloak, Auth0, Okta, Entra ID, Authentik, Zitadel, …) with the redirect URI
<your URL>/auth/callback, and an API audience whose access tokens are JWTs. - Set
IVY_OIDC_ISSUERandIVY_OIDC_CLIENT_ID(andIVY_OIDC_AUDIENCEif it differs from the client ID). - For several workspaces with members and invitations, set
IVY_SINGLE_TENANT=0. For invitation emails, setIVY_SMTP_URLandIVY_EMAIL_FROM.
Ivy never uses passwords of its own.
Send traces
- Lambda, by hand: build and publish the layer (layer README), then set
IVY_ENDPOINTto your ingest URL andIVY_API_KEYto a project key (manual setup). - Lambda, with auto-trace: give Ivy an AWS identity (
IVY_AWS_PRINCIPAL_ARNand AWS credentials) that can assume the role the CloudFormation template creates, and setIVY_INGEST_PUBLIC_URL. Then connect accounts in the dashboard. Without a hook that publishes templates, the dashboard offers the template as a download. - Anything else: any OpenTelemetry SDK, over OTLP/HTTP to port 4318 (OpenTelemetry).
Alerts
Turn on Slack and the weekly digest with environment variables, and use the on-error-group-created hook for anything else. See setting up alerts.
Agents
Point your agent at your instance: claude mcp add --transport http ivy https://ivy.example.com/mcp, and tell it to use your URL instead of https://ivytrace.dev when following llms.txt.
Updating
Pull the new version, apply the schema (it is idempotent) and restart:
git pull
docker compose -f deploy/docker-compose.yml up -d --build
docker compose -f deploy/docker-compose.yml exec -T clickhouse /docker-entrypoint-initdb.d/init.sh