From 124d6699cdc2d6b49f8b83039a895cdd561dc906 Mon Sep 17 00:00:00 2001 From: Nick Gomez Date: Mon, 16 Feb 2026 12:41:36 -0800 Subject: [PATCH 1/3] docs: update README, env example, and Nango instructions - README.md: add automated setup section, fix .env filename, fix sed placeholder, fix docker compose v2 syntax, document NANGO_SECRET_KEY_DEV generation step - .env.docker.example: add NANGO_SECRET_KEY_DEV with usage comment, clarify dashboard creds are only used when auth enabled - nango-instructions.md: fix .env filename, fix sed syntax for macOS, fix volume name, remove legacy app paths, add env var override as recommended key retrieval method, add automated setup note Co-Authored-By: Claude Opus 4.6 --- README.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 917b75e..ed8483d 100644 --- a/README.md +++ b/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,10 +83,11 @@ cp .env.docker.example .env && \ -e "s||$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) && \ echo "NANGO_SECRET_KEY_DEV=$nango_key" >> .env && \ From 5cb92ba7910d38f1401c625417c40a6facac9492 Mon Sep 17 00:00:00 2001 From: Nick Gomez Date: Mon, 16 Feb 2026 18:39:06 -0800 Subject: [PATCH 2/3] fix: generate UUID v4 Nango keys and update .optional-services placement refs Nango validates secret keys as UUID v4. Updated key generation in setup.sh, README, and nango-instructions to use openssl+sed formatting instead of raw hex. Updated README to reference .optional-services/ as the default clone target. Replaced hardcoded docker volume rm with portable docker compose down -v. Co-Authored-By: Claude Opus 4.6 --- .env.docker.example | 2 +- README.md | 3 ++- nango-instructions.md | 10 ++++------ scripts/setup.sh | 4 +++- 4 files changed, 10 insertions(+), 9 deletions(-) diff --git a/.env.docker.example b/.env.docker.example index 89f2043..324371e 100644 --- a/.env.docker.example +++ b/.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= -# 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= diff --git a/README.md b/README.md index ed8483d..5fefebf 100644 --- a/README.md +++ b/README.md @@ -89,7 +89,8 @@ cp .env.docker.example .env && \ 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)" ``` diff --git a/nango-instructions.md b/nango-instructions.md index 82275dc..1a44041 100644 --- a/nango-instructions.md +++ b/nango-instructions.md @@ -38,7 +38,8 @@ Once Nango is running, configure the framework to connect to your local instance Generate a key and add it to your `.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 diff --git a/scripts/setup.sh b/scripts/setup.sh index cf64fcc..9b24f46 100755 --- a/scripts/setup.sh +++ b/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" From aa93e21b39e3ac46d08962ba2fc4f47f268af2ff Mon Sep 17 00:00:00 2001 From: Nick Gomez Date: Mon, 16 Feb 2026 19:52:50 -0800 Subject: [PATCH 3/3] docs: tighten prose in README and Nango instructions Co-Authored-By: Claude Opus 4.6 --- nango-instructions.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/nango-instructions.md b/nango-instructions.md index 1a44041..f3df49c 100644 --- a/nango-instructions.md +++ b/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,15 +27,15 @@ 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 _hex=$(openssl rand -hex 16) && \