feat: add setup script and Nango secret key env override

.env.docker.example

@@ -5,7 +5,7 @@ COMPOSE_PROFILES=nango,signoz,otel-collector,jaeger
 # Once set, it cannot be changed without losing existing encrypted data
 NANGO_ENCRYPTION_KEY=<REPLACE_WITH_NANGO_ENCRYPTION_KEY>
 
-# Optional: Pre-set the Nango API secret key (generate with: openssl rand -hex 16)
+# Optional: Pre-set the Nango API secret key (must be a valid UUID v4)
 # When set, this overrides the auto-generated key in the Nango database.
 # The automated setup script (pnpm setup-dev:optional) sets this automatically.
 # NANGO_SECRET_KEY_DEV=

README.md

@@ -12,12 +12,12 @@ If you're working with the [Inkeep Agents](https://github.com/inkeep/agents) mon
 pnpm setup-dev:optional
 ```
 
-This clones this repo, starts all services, generates credentials, and wires env vars to your `.env` automatically. The monorepo ships a thin bootstrap shim that delegates to [`scripts/setup.sh`](scripts/setup.sh) in this repo. See the [main repo docs](https://github.com/inkeep/agents) for details.
+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](https://github.com/inkeep/agents) for details.
 
 Lifecycle commands:
 - `pnpm optional:stop` — stop optional services
 - `pnpm optional:status` — show service status
-- `pnpm optional:reset` — nuke data and re-setup from scratch
+- `pnpm optional:reset` — remove all data and re-run setup
 
 If you used the automated setup, you can skip the manual steps below.
 
@@ -31,7 +31,7 @@ CALLER_ENV_FILE=/path/to/your/project/.env ./scripts/setup.sh
 ./scripts/setup.sh --status
 ```
 
-`CALLER_ENV_FILE` tells the script where to write service URLs and API keys. It is required for `setup` and `--reset`, but optional for `--stop` and `--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`.
 
 ---
 
@@ -69,6 +69,8 @@ Use these steps if you're running this repo standalone (without `pnpm setup-dev:
 
 ### 1. Clone this repository
 
+Clone as `.optional-services/` (matching the automated setup default) or any directory you prefer.
+
 ### 2. Configure environment variables
 
 ```bash
@@ -81,12 +83,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"
 ```
 
-Optionally, generate a Nango API secret key (so you don't need to retrieve it from the dashboard later):
+Optionally, pre-generate a Nango secret key (avoids retrieving it from the dashboard later):
+
 ```bash
-nango_key=$(openssl rand -hex 16) && \
+_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)"
 ```

nango-instructions.md

@@ -1,8 +1,8 @@
 ## Nango: Setup and Configuration
 
-> **Note:** If you used the automated setup (`pnpm setup-dev:optional` from the [agents](https://github.com/inkeep/agents) monorepo), Nango is already configured and the API key is written to your `.env`. The steps below are for manual setup or troubleshooting.
+> **Note:** If you used `pnpm setup-dev:optional`, Nango is already configured. The steps below are for manual setup or troubleshooting.
 
-This guide covers how to configure the Inkeep Agents Framework to work with the self-hosted Nango instance.
+This guide covers configuring the Inkeep Agents Framework to use the self-hosted Nango instance.
 
 ### 1) Start Nango
 
@@ -27,18 +27,19 @@ docker compose up -d
 
 ### 2) Configure the framework to use Nango
 
-Once Nango is running, configure the framework to connect to your local instance.
+Once Nango is running, configure the framework to connect to it.
 
-**Important:** Use real credentials from your Nango dashboard (no placeholders). The framework rejects `your_nango_secret_key`.
+**Important:** Use real credentials from your Nango dashboard. The framework rejects placeholder values like `your_nango_secret_key`.
 
 #### Get your Nango API Key
 
 **Option A — Pre-set via environment variable (recommended):**
 
-Generate a key and add it to your `.env` before starting Docker:
+Generate a key and add it to `.env` before starting Docker:
 
 ```bash
-nango_key=$(openssl rand -hex 16) && \
+_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"
 ```
@@ -100,11 +101,8 @@ docker compose up -d nango-server
 
 **Reset Nango data:**
 ```bash
-# Stop services
-docker compose down
-
-# Remove Nango data (caution: this deletes all configurations and connections)
-docker volume rm agents-optional-local-dev_nango-db
+# Stop services and remove all data volumes (caution: deletes all configurations and connections)
+docker compose down -v
 
 # Restart
 docker compose up -d

scripts/setup.sh

@@ -189,7 +189,9 @@ cmd_setup() {
     set_env_var "$COMPANION_ENV" "NANGO_SECRET_KEY_DEV" "$EXISTING_NANGO_KEY"
     echo -e "  ${GREEN}✓${NC} Re-using existing NANGO_SECRET_KEY"
   else
-    NANGO_KEY="$(openssl rand -hex 16)"
+    # Nango validates keys as UUID v4. Generate one portably (openssl + sed).
+    _hex="$(openssl rand -hex 16)"
+    NANGO_KEY="$(echo "$_hex" | sed 's/^\(.\{8\}\)\(.\{4\}\).\(.\{3\}\).\(.\{3\}\)\(.\{12\}\)$/\1-\2-4\3-a\4-\5/')"
     set_env_var "$COMPANION_ENV" "NANGO_SECRET_KEY_DEV" "$NANGO_KEY"
     set_env_var "$ENV_FILE" "NANGO_SECRET_KEY" "$NANGO_KEY"
     echo -e "  ${GREEN}✓${NC} Generated NANGO_SECRET_KEY"