feat: unified local dev setup with optional services

.gitignore

@@ -53,6 +53,9 @@ yarn-error.log*
 next-env.d.ts
 local.db
 
+# Optional local dev services (cloned by pnpm setup-dev:optional)
+.optional-services/
+
 .ipc-hosted-tools/
 .hosted-tools/
 

agents-docs/content/community/contributing/overview.mdx

@@ -44,7 +44,7 @@ This will:
 - 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.
+`pnpm setup-dev` is idempotent — safe to re-run after pulling changes, resetting your database, or switching branches.
 </Tip>
 
 Add API keys for the AI providers you want to use in the root `.env` or `~/.inkeep/config`. `ANTHROPIC_API_KEY` is required.
@@ -100,16 +100,16 @@ inkeep push
 
 # 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:
+Set up all optional local services — Nango (credential store), SigNoz (traces), OTEL Collector, and Jaeger — with one command:
 
 ```bash
 pnpm setup-dev:optional
 ```
 
-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.
+This clones [`agents-optional-local-dev`](https://github.com/inkeep/agents-optional-local-dev) into `.optional-services/`, starts services via Docker Compose, and writes the required env vars to your `.env`. Restart `pnpm dev` to pick up the new variables.
 
-- **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.
+- **Traces**: Open `http://localhost:3080` for SigNoz. See [Traces](/get-started/traces) for details.
+- **Credentials**: Create a credential in the Visual Builder using Nango Store. See [Nango](/typescript-sdk/credentials/nango) for details.
 
 <Snippet file="setup-dev-optional-lifecycle.mdx" />
 

agents-docs/content/get-started/traces.mdx

@@ -96,19 +96,19 @@ Run the following from your project root:
 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)
+This:
+- Clones [`agents-optional-local-dev`](https://github.com/inkeep/agents-optional-local-dev) into `.optional-services/` 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:
+Restart your dev server after setup completes:
 
 ```bash
 pnpm dev
 ```
 
-Open SigNoz at `http://localhost:3080` to view traces. Jaeger is also available at `http://localhost:16686`.
+Open SigNoz at `http://localhost:3080` to view traces. Jaeger is available at `http://localhost:16686`.
 
 <Snippet file="setup-dev-optional-lifecycle.mdx" />
 
@@ -130,8 +130,8 @@ If you prefer manual setup:
 Clone the Inkeep optional local development services repository:
 
 ```bash
-git clone https://github.com/inkeep/agents-optional-local-dev
-cd agents-optional-local-dev
+git clone https://github.com/inkeep/agents-optional-local-dev .optional-services
+cd .optional-services
 ```
 
 #### Step 2: Start SigNoz Services

agents-docs/content/typescript-sdk/credentials/nango.mdx

@@ -46,19 +46,19 @@ Run the following from your project root:
 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)
+This:
+- Clones [`agents-optional-local-dev`](https://github.com/inkeep/agents-optional-local-dev) into `.optional-services/` if not already present
 - Starts Nango, [SigNoz](/get-started/traces), OTEL Collector, and Jaeger via Docker Compose
-- Generates a Nango secret key and wires it to your `.env` (or re-uses an existing key if already configured)
+- Generates a Nango secret key and writes it to your `.env` (re-uses an existing key if already set)
 - Sets `NANGO_SERVER_URL`, `PUBLIC_NANGO_SERVER_URL`, and `PUBLIC_NANGO_CONNECT_BASE_URL`
 
-After setup completes, restart your dev server:
+Restart your dev server after setup completes:
 
 ```bash
 pnpm dev
 ```
 
-Then create a new credential in the [Visual Builder](/visual-builder/tools/credentials) using Nango Store as the credential store.
+Then create a credential in the [Visual Builder](/visual-builder/tools/credentials) using Nango Store.
 
 <Video src="/videos/create-nango-credential.mp4" />
 
@@ -71,13 +71,13 @@ If you prefer manual setup:
 #### Step 1: Clone the optional services repository
 
 ```bash
-git clone https://github.com/inkeep/agents-optional-local-dev
-cd agents-optional-local-dev
+git clone https://github.com/inkeep/agents-optional-local-dev .optional-services
+cd .optional-services
 ```
 
-#### Step 2: Configure the companion `.env`
+#### Step 2: Configure the `.optional-services/.env`
 
-Nango requires an encryption key for credential storage. Generate a `.env` file:
+Nango requires an encryption key for credential storage. Create the `.env` from the template:
 
 ```bash
 cp .env.docker.example .env && \
@@ -89,14 +89,14 @@ cp .env.docker.example .env && \
     -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 NANGO_ENCRYPTION_KEY and NANGO_DASHBOARD_PASSWORD"
+  echo ".env created with auto-generated NANGO_ENCRYPTION_KEY and NANGO_DASHBOARD_PASSWORD"
 ```
 
 <Warning>Once set, `NANGO_ENCRYPTION_KEY` cannot be changed without losing existing encrypted data.</Warning>
 
 #### Step 3: Start Nango Services
 
-Inside the `agents-optional-local-dev` repository, run the following command:
+Inside `.optional-services`, start Nango:
 
 ```bash
 docker compose --profile nango up -d
@@ -109,7 +109,7 @@ docker compose --profile nango up -d
 
 #### Step 5: Configure your root `.env` file
 
-In your **root project directory** (not inside the `agents-optional-local-dev` repository), update your `.env` file:
+In your **root project directory** (not inside `.optional-services/`), update your `.env` file:
 
 ```bash
 NANGO_SECRET_KEY=your_nango_secret_key
@@ -118,15 +118,15 @@ PUBLIC_NANGO_SERVER_URL=http://localhost:3050
 PUBLIC_NANGO_CONNECT_BASE_URL=http://localhost:3051
 ```
 
-Restart your dev server to load the new environment variables:
+Restart your dev server:
 
 ```bash
 pnpm dev
 ```
 
-#### Step 6: Create a new credential in the Visual Builder using Nango
+#### Step 6: Create a credential in the Visual Builder
 
-Create a new credential in the [Visual Builder](/visual-builder/tools/credentials) using Nango Store as the credential store.
+Create a credential in the [Visual Builder](/visual-builder/tools/credentials) using Nango Store.
 
 <Video src="/videos/create-nango-credential.mp4" />
 

create-agents-template/.gitignore

@@ -39,6 +39,9 @@ Thumbs.db
 coverage/
 .nyc_output/
 
+# Optional local dev services (cloned by pnpm setup-dev:optional)
+.optional-services/
+
 # Temporary files
 *.tmp
 *.temp

create-agents-template/scripts/setup-optional.sh

@@ -12,15 +12,15 @@
 #   sh scripts/setup-optional.sh --no-update  Skip pulling latest companion changes
 #
 # Environment:
-#   OPTIONAL_SERVICES_DIR  Override companion repo location (default: ../agents-optional-local-dev)
+#   OPTIONAL_SERVICES_DIR  Override companion repo location (default: .optional-services/)
 
 set -e
 
 GREEN='\033[0;32m'; YELLOW='\033[1;33m'; RED='\033[0;31m'; NC='\033[0m'
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-COMPANION_DIR="${OPTIONAL_SERVICES_DIR:-$REPO_ROOT/../agents-optional-local-dev}"
+COMPANION_DIR="${OPTIONAL_SERVICES_DIR:-$REPO_ROOT/.optional-services}"
 COMPANION_SCRIPT="$COMPANION_DIR/scripts/setup.sh"
 
 # Check if --no-update was passed (consumed here, passed through as no-op)

scripts/setup-optional.sh

@@ -12,15 +12,15 @@
 #   sh scripts/setup-optional.sh --no-update  Skip pulling latest companion changes
 #
 # Environment:
-#   OPTIONAL_SERVICES_DIR  Override companion repo location (default: ../agents-optional-local-dev)
+#   OPTIONAL_SERVICES_DIR  Override companion repo location (default: .optional-services/)
 
 set -e
 
 GREEN='\033[0;32m'; YELLOW='\033[1;33m'; RED='\033[0;31m'; NC='\033[0m'
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-COMPANION_DIR="${OPTIONAL_SERVICES_DIR:-$REPO_ROOT/../agents-optional-local-dev}"
+COMPANION_DIR="${OPTIONAL_SERVICES_DIR:-$REPO_ROOT/.optional-services}"
 COMPANION_SCRIPT="$COMPANION_DIR/scripts/setup.sh"
 
 # Check if --no-update was passed (consumed here, passed through as no-op)