# Self-hosted Lambda tracing

Ivy is open source under the MIT license, and the hosted service at ivytrace.dev runs the same images you can run yourself. `docker compose up` starts the OpenTelemetry Collector, ClickHouse, the API, the dashboard and the MCP server. Self-hosted Ivy has no limits and no payment code, and your traces never leave your servers.

## One command

```
git clone https://github.com/ivytrace/ivy && cd ivy
docker compose -f deploy/docker-compose.yml up -d --build
```

- Dashboard, API and MCP server on `http://localhost:3000`
- OTLP/HTTP ingest on `http://localhost:4318`

The full guide, with environment variables, sign-in and AWS setup, is in the [self-hosting docs](https://ivytrace.dev/docs/self-hosting).

## What runs

| Service | Role |
|---|---|
| Ingest router | Checks the ingest key and decides which workspace and project the spans belong to |
| OpenTelemetry Collector (contrib) | Batches spans with a persistent on-disk queue and writes them to ClickHouse |
| ClickHouse | Stores spans, one row per invocation for fast search, and hourly rollups |
| API | The HTTP API, the dashboard and the MCP server |

The backend needs no AWS services. It only needs network access to the AWS API if you want it to attach the layer to your functions (auto-trace), and your functions need to reach its ingest endpoint.

## Same features as hosted

- The dashboard, MCP server (including MCP Apps views) and HTTP API.
- Auto-trace through a cross-account role, or attach the layer yourself.
- Workspaces, projects, members and invitations.
- [Alerts](https://ivytrace.dev/features/alerts): Slack and the weekly email digest, turned on with environment variables, plus an `on-error-group-created` hook for your own integrations.
- Retention is yours to choose (`IVY_RETENTION_DAYS`, 30 days by default).

## Sign-in

Ivy uses **OIDC or no auth**, never passwords:

- **With OIDC:** register a client with Keycloak, Auth0, Okta, Entra ID, Authentik, Zitadel or another provider that issues JWT access tokens, and set `IVY_OIDC_ISSUER` and `IVY_OIDC_CLIENT_ID`. Coding agents sign in through the same provider.
- **Without OIDC:** the dashboard and API run open, for setups behind your own authenticating proxy, and the UI shows a permanent "authentication disabled" banner.

Ingest always needs an API key.

## Hooks

Hosted-only behaviour, like billing, lives in **hooks**: executables in a directory, git-hooks style. Self-hosted installs can use the same mechanism, for example `on-error-group-created` to open a ticket, or `publish-cfn-template` for one-click CloudFormation links.

## Hosted or self-hosted?

| Feature | ivytrace.dev | Self-hosted |
|---|---|---|
| Price | Free for 100,000 traces a month, then €5 per million | Free (MIT), plus your server |
| Operations | None | You run and upgrade it |
| Data location | Ivy's hosted service | Your servers |
| Sign-in | Email sign-in, ready to use | Your OIDC provider, or none |
| Features | Same | Same |

You can move between them at any time: point the layer's `IVY_ENDPOINT` and `IVY_API_KEY` somewhere else.

---

Source: https://ivytrace.dev/features/self-hosting · Updated 2026-11-14