Inkeep Agents Docker Compose for Optional Local Dev

Warning

These Docker Compose configurations are for local development and testing only. Please review carefully before using in a production environment.

Automated setup (recommended)

If you're working with the Inkeep Agents monorepo or a quickstart project created with npx @inkeep/create-agents, run:

pnpm setup-dev:optional

This clones this repo into .optional-services/ in your project, starts all services, generates credentials, and writes env vars to your .env. See the main repo docs for details.

Lifecycle commands:

• pnpm optional:stop — stop optional services
• pnpm optional:status — show service status
• pnpm optional:reset — remove all data and re-run setup

If you used the automated setup, you can skip the manual steps below.

Direct invocation

If you cloned this repo manually and want to use the setup script directly:

CALLER_ENV_FILE=/path/to/your/project/.env ./scripts/setup.sh
./scripts/setup.sh --stop
./scripts/setup.sh --status

CALLER_ENV_FILE tells the script where to write service URLs and API keys. Required for setup and --reset; optional for --stop and --status.

---

Services overview

This setup provides 4 service profiles for local development with the Inkeep Agents Framework:

1. Nango

Inkeep Agents uses Nango to store credentials.

• Nango Server: localhost:3050
• Nango Connect UI: localhost:3051

2. SigNoz

SigNoz is the underlying service to view Spans and Traces in the Inkeep Manage UI.

• SigNoz UI: localhost:3080
• OTLP gRPC: localhost:4317
• OTLP HTTP: localhost:4318

3. OTEL Collector

A standalone OpenTelemetry Collector that forwards traces to multiple destinations. The Inkeep Agents API sends traces to the OTEL Collector, which then forwards them to SigNoz and Jaeger.

• OTLP gRPC: localhost:14317
• OTLP HTTP: localhost:14318

4. Jaeger

An optional tool to view traces from the Inkeep Agents Framework.

• Jaeger UI: localhost:16686
• OTLP gRPC: localhost:24317
• OTLP HTTP: localhost:24318

---

Manual setup

Use these steps if you're running this repo standalone (without pnpm setup-dev:optional).

1. Clone this repository

Clone as .optional-services/ (matching the automated setup default) or any directory you prefer.

2. Configure environment variables

Run this command to autogenerate a .env file from the template .env.docker.example:

./scripts/generate-env-from-example.sh

Optionally, pre-generate a Nango secret key (avoids retrieving it from the dashboard later):

_hex=$(openssl rand -hex 16) && \
  nango_key=$(echo "$_hex" | sed 's/^\(.\{8\}\)\(.\{4\}\).\(.\{3\}\).\(.\{3\}\)\(.\{12\}\)$/\1-\2-4\3-a\4-\5/') && \
  echo "NANGO_SECRET_KEY_DEV=$nango_key" >> .env && \
  echo "Nango secret key: $nango_key (add this as NANGO_SECRET_KEY in your agents .env)"

3. Start

docker compose up -d

4. Retrieve NANGO_SECRET_KEY

If you set NANGO_SECRET_KEY_DEV in step 2, use that value as NANGO_SECRET_KEY in your agents .env.

Otherwise, retrieve it from the Nango dashboard:

• Open Nango at http://localhost:3050
• Navigate to Environment Settings and copy the Secret Key

5. Create SIGNOZ_API_KEY

• Open SigNoz at http://localhost:3080
• Create an account on first login
• Navigate to Settings → Account Settings → API Keys → New Key
• Create a new API key with at least the Viewer role

---

Updating

docker compose stop
docker compose rm -f
docker compose pull
docker compose up -d --remove-orphans

---

License

This project is licensed under the Apache License 2.0.

This repository includes third-party configuration files under their own licenses (MIT, ELv2). See NOTICE for details.