inkeep · nick-inkeep · Feb 17, 2026 · Feb 16, 2026 · Feb 16, 2026 · Feb 16, 2026
diff --git a/.env.example b/.env.example
@@ -43,6 +43,9 @@ OPENAI_API_KEY=
 GOOGLE_GENERATIVE_AI_API_KEY=
 
 # ============ THIRD PARTY SERVICES ============
+# Optional services (Nango, SigNoz, OTEL, Jaeger) are auto-configured by `pnpm setup-dev:optional`.
+# You only need to set these manually if using cloud-hosted services.
+
 # Nango (for MCP OAuth integrations)
 NANGO_SECRET_KEY=
 NANGO_SERVER_URL=http://localhost:3050

diff --git a/AGENTS.md b/AGENTS.md
@@ -7,6 +7,9 @@ This file provides guidance for AI coding agents (Claude Code, Cursor, Codex, Am
 ### Build & Development
 - **Build**: `pnpm build` (root) or `turbo build`
 - **Dev**: `pnpm dev` (root) or navigate to package and run `pnpm dev`
+- **Setup (core)**: `pnpm setup-dev` — core DBs (Doltgres, Postgres, SpiceDB), env config, migrations, admin user
+- **Setup (optional services)**: `pnpm setup-dev:optional` — Nango + SigNoz + OTEL + Jaeger (run `setup-dev` first)
+- **Optional services lifecycle**: `pnpm optional:stop` | `pnpm optional:status` | `pnpm optional:reset`
 - **Lint**: `pnpm lint` (check) or `pnpm lint:fix` (auto-fix) or `pnpm check:fix` (Biome fix)
 - **Format**: `pnpm format` (auto) or `pnpm format:check` (verify)
 - **Typecheck**: `pnpm typecheck`

diff --git a/agents-docs/_snippets/setup-dev-optional-lifecycle.mdx b/agents-docs/_snippets/setup-dev-optional-lifecycle.mdx
@@ -0,0 +1 @@
+Use `pnpm optional:status` to check service health, `pnpm optional:stop` to stop optional services, or `pnpm optional:reset` to start fresh.
diff --git a/agents-docs/_snippets/setup-dev-optional-prereq.mdx b/agents-docs/_snippets/setup-dev-optional-prereq.mdx
@@ -0,0 +1,3 @@
+<Note>
+  Run `pnpm setup-dev` first to set up core databases and migrations. `setup-dev:optional` only starts optional services.
+</Note>
diff --git a/agents-docs/content/community/contributing/environment-configuration.mdx b/agents-docs/content/community/contributing/environment-configuration.mdx
@@ -39,13 +39,13 @@ This hierarchy allows for flexible configuration management across different sce
 
 ### 1. Basic Local Development
 
-For simple local development with a single repository copy:
+For local development, `pnpm setup-dev` creates your `.env` and initializes databases. You only need to add your AI provider API keys:
 
 ```bash
-# Copy the template
-cp .env.example .env
+# Run setup (creates .env, starts databases, runs migrations)
+pnpm setup-dev
 
-# Edit .env with your configuration
+# Add your API keys to .env
 vim .env
 
 # Start development
@@ -66,4 +66,4 @@ Ensure all required variables are set in your deployment environment. The applic
 
 ### Database connection issues
 
-- For SQLite: Make sure youu are using an absolute path to the db file
+- For SQLite: Make sure you are using an absolute path to the db file
diff --git a/agents-docs/content/community/contributing/overview.mdx b/agents-docs/content/community/contributing/overview.mdx
@@ -28,7 +28,7 @@ cd agents
 
 ### Step 2: Run the setup script
 
-For first-time setup, run:
+Ensure Docker Desktop (or Docker daemon) is running, then run:
 
 ```bash
 pnpm setup-dev
@@ -41,6 +41,11 @@ This will:
 - Add `.env` to `.gitignore` if needed
 - Install dependencies
 - Start Doltgres (manage) + Postgres (runtime) + SpiceDB (authorization) via `docker-compose.dbs.yml` and run migrations
+- Create the admin user for auto-login (`pnpm db:auth:init`)
+
+<Tip>
+`pnpm setup-dev` is idempotent — safe to re-run after pulling new changes, resetting your database, or switching branches. It will apply any new migrations without breaking existing state.
+</Tip>
 
 Add API keys for the AI providers you want to use in the root `.env` or `~/.inkeep/config`. `ANTHROPIC_API_KEY` is required.
 
@@ -93,28 +98,27 @@ inkeep push
   style={{ border: "1px solid #e1e5e9" }}
 />
 
-# Set up live traces
+# Set up optional services (traces + credentials)
+
+A single command sets up all optional local services — Nango (credential store), SigNoz (trace viewer), OTEL Collector, and Jaeger:
+
+```bash
+pnpm setup-dev:optional
+```
 
-For full instructions, see [Traces](/get-started/traces). Short version:
+This automatically clones the [`agents-optional-local-dev`](https://github.com/inkeep/agents-optional-local-dev) companion repo, starts all services via Docker Compose, and wires the required env vars to your `.env`. Restart `pnpm dev` to pick up the new variables.
 
-- For local SigNoz, clone `agents-optional-local-dev` and run `docker-compose --profile signoz up -d`.
-- Set `SIGNOZ_URL`, `SIGNOZ_API_KEY`, and `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` in the root `.env` (see `.env.example`).
-- Restart `pnpm dev`, then open `http://localhost:3080` to view traces.
+- **Traces**: Open `http://localhost:3080` to view traces in SigNoz. See [Traces](/get-started/traces) for full instructions.
+- **Credentials**: Create a credential in the Visual Builder (Credentials tab) using Nango Store. See [Use Nango as a credential store](/typescript-sdk/credentials/nango) for full instructions.
+
+<Snippet file="setup-dev-optional-lifecycle.mdx" />
 
 <Image
   src="/images/live-traces.png"
   alt="Live traces showing"
   style={{ border: "1px solid #e1e5e9" }}
 />
 
-# Set up credentials
-
-For Nango setup (cloud or local), follow [Use Nango as a credential store](/typescript-sdk/credentials/nango). Short version:
-
-- Set `NANGO_SECRET_KEY` in the root `.env`.
-- For local Nango, start services from `agents-optional-local-dev` (`docker-compose --profile nango up -d`) and set `NANGO_SERVER_URL` / `PUBLIC_NANGO_CONNECT_BASE_URL` as needed (see `.env.example`).
-- Restart `pnpm dev`, then create a credential in the Visual Builder (Credentials tab).
-
 # Development Workflow
 
 ### Conductor

diff --git a/agents-docs/content/deployment/(docker)/aws-ec2.mdx b/agents-docs/content/deployment/(docker)/aws-ec2.mdx
@@ -42,12 +42,16 @@ cd inkeep-external-services
 
 Run this command to autogenerate a `.env` file:
 ```bash
-cp .env.example .env && \
-  encryption_key=$(openssl rand -base64 32) && \
+cp .env.docker.example .env && \
+  nango_encryption_key=$(openssl rand -base64 32) && \
+  nango_dashboard_password=$(openssl rand -base64 8) && \
   tmp_file=$(mktemp) && \
-  sed "s|<REPLACE_WITH_BASE64_256BIT_ENCRYPTION_KEY>|$encryption_key|" .env > "$tmp_file" && \
+  sed \
+    -e "s|<REPLACE_WITH_NANGO_ENCRYPTION_KEY>|$nango_encryption_key|" \
+    -e "s|<REPLACE_WITH_NANGO_DASHBOARD_PASSWORD>|$nango_dashboard_password|" \
+    .env > "$tmp_file" && \
   mv "$tmp_file" .env && \
-  echo "Docker environment file created with auto-generated encryption key"
+  echo "Docker environment file created with auto-generated NANGO_ENCRYPTION_KEY and NANGO_DASHBOARD_PASSWORD"
 ```
 
 Nango requires a `NANGO_ENCRYPTION_KEY`. Once you create this, it cannot be edited.

diff --git a/agents-docs/content/deployment/(docker)/docker-local.mdx b/agents-docs/content/deployment/(docker)/docker-local.mdx
@@ -19,12 +19,16 @@ cd inkeep-external-services
 
 Run this command to autogenerate a `.env` file:
 ```bash
-cp .env.example .env && \
-  encryption_key=$(openssl rand -base64 32) && \
+cp .env.docker.example .env && \
+  nango_encryption_key=$(openssl rand -base64 32) && \
+  nango_dashboard_password=$(openssl rand -base64 8) && \
   tmp_file=$(mktemp) && \
-  sed "s|<REPLACE_WITH_BASE64_256BIT_ENCRYPTION_KEY>|$encryption_key|" .env > "$tmp_file" && \
+  sed \
+    -e "s|<REPLACE_WITH_NANGO_ENCRYPTION_KEY>|$nango_encryption_key|" \
+    -e "s|<REPLACE_WITH_NANGO_DASHBOARD_PASSWORD>|$nango_dashboard_password|" \
+    .env > "$tmp_file" && \
   mv "$tmp_file" .env && \
-  echo "Docker environment file created with auto-generated encryption key"
+  echo "Docker environment file created with auto-generated NANGO_ENCRYPTION_KEY and NANGO_DASHBOARD_PASSWORD"
 ```
 
 Nango requires a `NANGO_ENCRYPTION_KEY`. Once you create this, it cannot be edited.

diff --git a/agents-docs/content/deployment/(docker)/gcp-compute-engine.mdx b/agents-docs/content/deployment/(docker)/gcp-compute-engine.mdx
@@ -58,12 +58,16 @@ cd inkeep-external-services
 
 Run this command to autogenerate a `.env` file:
 ```bash
-cp .env.example .env && \
-  encryption_key=$(openssl rand -base64 32) && \
+cp .env.docker.example .env && \
+  nango_encryption_key=$(openssl rand -base64 32) && \
+  nango_dashboard_password=$(openssl rand -base64 8) && \
   tmp_file=$(mktemp) && \
-  sed "s|<REPLACE_WITH_BASE64_256BIT_ENCRYPTION_KEY>|$encryption_key|" .env > "$tmp_file" && \
+  sed \
+    -e "s|<REPLACE_WITH_NANGO_ENCRYPTION_KEY>|$nango_encryption_key|" \
+    -e "s|<REPLACE_WITH_NANGO_DASHBOARD_PASSWORD>|$nango_dashboard_password|" \
+    .env > "$tmp_file" && \
   mv "$tmp_file" .env && \
-  echo "Docker environment file created with auto-generated encryption key"
+  echo "Docker environment file created with auto-generated NANGO_ENCRYPTION_KEY and NANGO_DASHBOARD_PASSWORD"
 ```
 
 Nango requires a `NANGO_ENCRYPTION_KEY`. Once you create this, it cannot be edited.

diff --git a/agents-docs/content/deployment/(docker)/hetzner.mdx b/agents-docs/content/deployment/(docker)/hetzner.mdx
@@ -47,12 +47,16 @@ cd inkeep-external-services
 
 Run this command to autogenerate a `.env` file:
 ```bash
-cp .env.example .env && \
-  encryption_key=$(openssl rand -base64 32) && \
+cp .env.docker.example .env && \
+  nango_encryption_key=$(openssl rand -base64 32) && \
+  nango_dashboard_password=$(openssl rand -base64 8) && \
   tmp_file=$(mktemp) && \
-  sed "s|<REPLACE_WITH_BASE64_256BIT_ENCRYPTION_KEY>|$encryption_key|" .env > "$tmp_file" && \
+  sed \
+    -e "s|<REPLACE_WITH_NANGO_ENCRYPTION_KEY>|$nango_encryption_key|" \
+    -e "s|<REPLACE_WITH_NANGO_DASHBOARD_PASSWORD>|$nango_dashboard_password|" \
+    .env > "$tmp_file" && \
   mv "$tmp_file" .env && \
-  echo "Docker environment file created with auto-generated encryption key"
+  echo "Docker environment file created with auto-generated NANGO_ENCRYPTION_KEY and NANGO_DASHBOARD_PASSWORD"
 ```
 
 Nango requires a `NANGO_ENCRYPTION_KEY`. Once you create this, it cannot be edited.

diff --git a/agents-docs/content/get-started/traces.mdx b/agents-docs/content/get-started/traces.mdx
@@ -86,16 +86,46 @@ OTEL_EXPORTER_OTLP_TRACES_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
 
 ## Option 2: Local SigNoz Setup
 
+### Automated Setup (Recommended)
+
+<Snippet file="setup-dev-optional-prereq.mdx" />
+
+Run the following from your project root:
+
+```bash
+pnpm setup-dev:optional
+```
+
+This automatically:
+- Clones the [`agents-optional-local-dev`](https://github.com/inkeep/agents-optional-local-dev) companion repo (if not already present)
+- Starts SigNoz, OTEL Collector, Jaeger, and [Nango](/typescript-sdk/credentials/nango) via Docker Compose
+- Registers a SigNoz admin account and creates an API key
+- Writes all required env vars to your `.env`
+
+After setup completes, restart your dev server:
+
+```bash
+pnpm dev
+```
+
+Open SigNoz at `http://localhost:3080` to view traces. Jaeger is also available at `http://localhost:16686`.
+
+<Snippet file="setup-dev-optional-lifecycle.mdx" />
+
+### Manual Setup
+
 <Video
   src="https://www.youtube.com/watch?v=DWuL4AeRzAA&t=3s"
   title="Local SigNoz Setup steps"
 />
 
-### Prerequisites
+If you prefer manual setup:
+
+#### Prerequisites
 
 - Docker installed on your machine
 
-### Step 1: Clone the Optional Services Repository
+#### Step 1: Clone the Optional Services Repository
 
 Clone the Inkeep optional local development services repository:
 
@@ -104,12 +134,12 @@ git clone https://github.com/inkeep/agents-optional-local-dev
 cd agents-optional-local-dev
 ```
 
-### Step 2: Start SigNoz Services
+#### Step 2: Start SigNoz Services
 
 Run the following command to start SigNoz and related services:
 
 ```bash
-docker-compose --profile signoz up -d
+docker compose --profile signoz up -d
 ```
 
 This will start:
@@ -121,7 +151,7 @@ This will start:
 
 When you visit `http://localhost:3080`, you can sign up with your desired credentials.
 
-### Step 3: Configure Environment Variables
+#### Step 3: Configure Environment Variables
 
 In your **root project directory** (e.g., `my-agents`), update your `.env` file:
 
@@ -130,9 +160,9 @@ In your **root project directory** (e.g., `my-agents`), update your `.env` file:
 SIGNOZ_URL=http://localhost:3080
 SIGNOZ_API_KEY=your-signoz-api-key
 
-# IMPORTANT: Comment out the OTEL Configuration
-# OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://ingest.us.signoz.cloud:443/v1/traces
-# OTEL_EXPORTER_OTLP_TRACES_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
+# Local SigNoz OTEL endpoint (port 4318 — the SigNoz collector)
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces
+OTEL_SERVICE_NAME=inkeep-agents
 ```
 
 To get your SigNoz API key:
@@ -143,7 +173,7 @@ To get your SigNoz API key:
    - Choose any role (Admin, Editor, or Viewer) - Viewer is sufficient for observability
    - Set the expiration field to "No Expiry" to prevent the key from expiring
 
-### Step 4: Verify Setup
+#### Step 4: Verify Setup
 
 1. Restart your Inkeep agents:
 

diff --git a/agents-docs/content/guides/upgrading.mdx b/agents-docs/content/guides/upgrading.mdx
@@ -30,6 +30,10 @@ pnpm upgrade-agents
 
 This will update all the packages to the latest version and migrate your database schema to the latest version.
 
+<Note>
+Your Docker databases must be running before upgrading. If they aren't running, run `pnpm setup-dev` first, then run `pnpm upgrade-agents`.
+</Note>
+
 ### Troubleshooting:
 
 If you encounter migration errors during the upgrade, this indicates a breaking schema change. You'll need to reset your database:

diff --git a/agents-docs/content/troubleshooting.mdx b/agents-docs/content/troubleshooting.mdx
@@ -73,6 +73,18 @@ If your agent stops mid-conversation, it may have hit a configured stopWhen limi
 
 See [Configuring StopWhen](/typescript-sdk/agent-settings#configuring-stopwhen) for more details.
 
+## Local environment not starting
+
+If `pnpm dev` fails or services aren't reachable, the most common cause is that `pnpm setup-dev` hasn't been run (or Docker containers have stopped).
+
+**How to fix:**
+
+1. Ensure Docker Desktop (or Docker daemon) is running
+2. Run `pnpm setup-dev` — this is idempotent and will start any stopped databases, apply pending migrations, and ensure the admin user exists
+3. Run `pnpm dev` again
+
+For the [quickstart template](/get-started/quick-start), the same applies: run `pnpm setup-dev` from the workspace root before `pnpm dev`.
+
 ## Check service logs (local development)
 
 When running `pnpm dev` from your [quickstart workspace](/quick-start/start-development), you will see an interactive terminal interface. This interface allows you to inspect the logs of each [running service](/quick-start/start-development#service-ports). You can navigate between services using the up and down arrow keys.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Use `pnpm optional:status` to check service health, `pnpm optional:stop` to stop optional services, or `pnpm optional:reset` to start fresh.