Add dev-start script for KiloClaw local development (#1093)

evanjacobson · web-flow · commit 53a78742c782 · 2026-03-13T20:24:49.000-06:00
## Summary

- One-command dev environment setup: `./scripts/dev-start.sh`
- Auto-manages `.dev.vars` (creates from example, syncs secrets from
Vercel, refreshes Fly tokens, sets tunnel URL)
- `--display tabs|split|tmux` flag for terminal layout preference
- Persistent config via `.dev-start.conf` (per-worktree or user-global)
- Updated DEVELOPMENT_LOCAL.md to document the script

## Test plan

- [x] Run `./scripts/dev-start.sh` with no `.dev.vars` (should
auto-create)
- [x] Test `--display tabs`, `--display split`, `--display tmux`
- [x] Test `--tunnel-name` with a named tunnel
- [x] Test config file override via `scripts/.dev-start.conf`
diff --git a/kiloclaw/.dev.vars.example b/kiloclaw/.dev.vars.example
@@ -1,27 +1,39 @@
-# Copy this to .dev.vars and fill in your values
-# .dev.vars is gitignored and used by wrangler dev
+# KiloClaw worker secrets (used by wrangler dev).
+# The dev-start script creates .dev.vars from this file on first run.
+#
+# Most values below are working defaults. The script auto-manages:
+#   NEXTAUTH_SECRET, INTERNAL_API_SECRET  (synced from Vercel)
+#   FLY_API_TOKEN                         (auto-created/refreshed)
+#   KILOCODE_API_BASE_URL                 (set from tunnel URL)
+#
+# Values you may need to set manually:
+#   AGENT_ENV_VARS_PRIVATE_KEY            (get from 1Password)
+#   FLY_IMAGE_TAG / FLY_IMAGE_DIGEST / OPENCLAW_VERSION
+#                                         (set by scripts/push-dev.sh,
+#                                          or ask a team member for values)
 
-# Auth
+# Auth (synced automatically from Vercel by the dev-start script)
 NEXTAUTH_SECRET=dev-secret-change-me
 INTERNAL_API_SECRET=dev-internal-secret
+
+# Auth (static defaults — these work as-is for local dev)
 GATEWAY_TOKEN_SECRET=dev-gateway-secret-kiloclaw
 # Override WORKER_ENV to "development" for local development.
 # Production default is set in wrangler.jsonc. This selects the development
 # Fly app naming prefix ("dev-") for per-user app creation.
 WORKER_ENV=development
 
-# Optional: Override KiloCode provider base URL (local dev only)
+# Tunnel URL (set automatically by the dev-start script)
 # OpenClaw's native kilocode provider hardcodes https://api.kilo.ai/api/gateway/.
-# In dev, set this to a Cloudflare tunnel or ngrok URL pointing to your local Next.js app
-# so that Fly machines route model requests through the tunnel instead of production.
-# e.g.: `cloudflared tunnel --url http://localhost:3000`
+# In dev, the script sets this to the Cloudflare tunnel URL pointing to your
+# local Next.js app so Fly machines route model requests through the tunnel.
 # KILOCODE_API_BASE_URL=https://<tunnel>.trycloudflare.com/api/gateway/
 
 # Fly.io Machines API
-# Get an org-scoped token (run: `fly tokens create -o kilo-dev my-dev-token`)
+# Token is auto-created/refreshed by the dev-start script.
 FLY_API_TOKEN=fo1_...
-# Your Fly org slug (run: `fly orgs list`). Use `kilo-dev` for Kilo team
-# members, or `personal` if you're running under your own Fly account.
+# Fly org slug. The dev-start script reads this value for token creation.
+# Use "kilo-dev" for Kilo team members, or "personal" for your own Fly account.
 FLY_ORG_SLUG=kilo-dev
 # Shared Docker image registry app (images are pushed here, referenced by all per-user apps)
 FLY_REGISTRY_APP=kiloclaw-dev
@@ -31,8 +43,7 @@ FLY_REGISTRY_APP=kiloclaw-dev
 # The platform API can override per-user at provision time.
 FLY_REGION=us,eu
 # Docker image tag on registry.fly.io/{FLY_REGISTRY_APP}:{tag}.
-# In dev, use "latest" or run scripts/push-dev.sh which sets a timestamped tag.
-# In production, pin to a version (e.g., v40, sha-abc1234).
+# Set automatically by scripts/push-dev.sh, or use "latest" to start.
 FLY_IMAGE_TAG=latest
 # OpenClaw version (must match the openclaw@x.x.x version in the Dockerfile).
 # Used by the worker to self-register the version → image tag mapping in KV,
@@ -51,6 +62,7 @@ FLY_APP_NAME=kiloclaw-dev
 OPENCLAW_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8795,http://claw.kilosessions.ai
 
 # Encryption (for user secrets)
+# Get the dev version from 1Password (engineering vault). Quote the value.
 # AGENT_ENV_VARS_PRIVATE_KEY=...
 
 # Hyperdrive is configured in wrangler.jsonc, not here.
diff --git a/kiloclaw/.gitignore b/kiloclaw/.gitignore
@@ -162,6 +162,7 @@ dist
 
 .dev.vars*
 !.dev.vars.example
+scripts/.dev-start.conf
 .env*
 !.env.example
 .wrangler/
diff --git a/kiloclaw/DEVELOPMENT_LOCAL.md b/kiloclaw/DEVELOPMENT_LOCAL.md
@@ -55,77 +55,74 @@ app as a kind of image registry for all other apps -- in dev, that app is
 1. Accept the Fly.io org invite(s) from your email (there should be two --
    check spam if you only see one).
 2. Verify with `fly orgs list` -- the dev org should appear.
-3. Create an org-scoped token for dev use (personal tokens also have production
-   access):
+3. Log in to the Fly CLI: `fly auth login`
 
-```bash
-fly tokens create -o kilo-dev my-dev-token
-```
-
-Save this token -- you'll need it for `FLY_API_TOKEN` in `.dev.vars`.
+The dev-start script creates and refreshes Fly API tokens automatically -- you
+don't need to manage tokens manually.
 
 ## Quick Start
 
-```bash
-# 1. Install dependencies (run from monorepo root)
-pnpm install
+One-time prerequisites:
 
-# 2. Copy the example env file (from kiloclaw/)
-cp kiloclaw/.dev.vars.example kiloclaw/.dev.vars
+1. Link the Vercel project (from monorepo root): `vercel link`
+2. Accept Fly.io org invites and `fly auth login` (see above)
 
-# 3. Edit .dev.vars -- see "Environment Variables" below
+Then, from the `kiloclaw/` directory:
 
-# 4. Ensure Next.js has KiloClaw env vars (from monorepo root).
-#    `vercel env pull` includes KILOCLAW_API_URL and
-#    KILOCLAW_INTERNAL_API_SECRET. If you haven't run it yet, see
-#    the root DEVELOPMENT.md for Next.js setup.
+```bash
+./scripts/dev-start.sh
+```
 
-# 5. Start the local database (from monorepo root)
-docker compose -f dev/docker-compose.yml up -d
+The script handles everything: creates `.dev.vars` if missing, pulls Vercel
+env, syncs secrets, validates/refreshes the Fly token, installs dependencies,
+starts the database, runs migrations, starts a Cloudflare tunnel (and captures
+the URL into `.dev.vars`), and launches all three processes.
 
-# 6. Run database migrations (from monorepo root)
-pnpm drizzle migrate
+Open <http://localhost:3000> to use the dashboard.
 
-# 7. Start the tunnel (separate terminal)
-cloudflared tunnel --url http://localhost:3000
-# Copy the tunnel URL into KILOCODE_API_BASE_URL in .dev.vars
+### Display modes
 
-# 8. Start Next.js (separate terminal, from monorepo root)
-pnpm dev
+Control how the three processes are displayed with `--display <mode>`:
 
-# 9. Start the KiloClaw worker (separate terminal, from kiloclaw/)
-pnpm run dev
-```
+| Mode    | Description                                                           |
+| ------- | --------------------------------------------------------------------- |
+| `tabs`  | Separate terminal tabs (default; auto-detects iTerm2 vs Terminal.app) |
+| `split` | Single tab with split panes (requires iTerm2)                         |
+| `tmux`  | tmux session `kiloclaw` (attach with `tmux attach -t kiloclaw`)       |
 
-Each of the three long-running processes (tunnel, Next.js, worker) needs its
-own terminal tab. The Next.js app must run on port 3000 -- other services
-depend on it.
+### Other flags
 
-## Tunnel setup
+| Flag                       | Description                                          |
+| -------------------------- | ---------------------------------------------------- |
+| `--has-controller-changes` | Build and push a new Docker image before starting    |
+| `--tunnel-name <name>`     | Use a named Cloudflare tunnel instead of a quick one |
 
-Use Cloudflare Tunnel (recommended) or ngrok to expose your local Next.js:
+### Script configuration
 
-```bash
-# Cloudflare Tunnel (free, no account needed for quick tunnels)
-cloudflared tunnel --url http://localhost:3000
+Save defaults in a config file so you don't need to pass flags every time.
+The script checks two locations (project-local overrides user-global):
 
-# Or ngrok
-ngrok http 3000
-```
+| Location                            | Scope                       |
+| ----------------------------------- | --------------------------- |
+| `kiloclaw/scripts/.dev-start.conf`  | Per-worktree (gitignored)   |
+| `~/.config/kiloclaw/dev-start.conf` | Shared across all worktrees |
 
-Copy the tunnel URL and set it in `.dev.vars`:
+See `scripts/.dev-start.conf.example` for available options. CLI flags
+override config file values.
 
-```
-KILOCODE_API_BASE_URL=https://<your-tunnel>.trycloudflare.com/api/gateway/
-```
+## Tunnel setup
+
+The dev-start script automatically starts a Cloudflare quick tunnel, captures
+its URL, and writes `KILOCODE_API_BASE_URL` into `.dev.vars`. You generally
+don't need to manage this manually.
 
 ### Free vs named tunnels
 
-- **Free quick tunnel**: hostname changes on every restart of `cloudflared`.
-  Update `.dev.vars` and restart the worker when the URL changes.
+- **Free quick tunnel** (default): hostname changes on every restart. The
+  script handles this automatically.
 - **Named tunnel**: preconfigure in the Cloudflare dashboard for a persistent
-  hostname (e.g., `yourname.devclaw.dev`). Avoids updating the URL on each
-  restart.
+  hostname (e.g., `yourname.devclaw.dev`). Use `--tunnel-name <name>` or set
+  `TUNNEL_NAME` and `TUNNEL_HOSTNAME` in your config file.
 
 ### If the tunnel isn't working
 
@@ -136,71 +133,68 @@ The error manifests in OpenClaw as one of:
 
 If you see either, check:
 
-- `cloudflared` (or ngrok) is running
+- `cloudflared` is running (check its terminal tab/window)
 - `KILOCODE_API_BASE_URL` in `.dev.vars` matches the current tunnel URL
 - The KiloClaw worker was restarted after changing `.dev.vars`
 
 ## Environment Variables
 
-There are two env files to configure:
-
-### 1. `kiloclaw/.dev.vars` (worker secrets)
-
-Copy `.dev.vars.example` and fill in:
+### `kiloclaw/.dev.vars` (worker secrets)
 
-**Auth** -- must match the Next.js app's values:
+The dev-start script creates `.dev.vars` from `.dev.vars.example` on first run
+and automatically manages several values. The table below shows which variables
+are auto-managed and which require manual setup.
 
-| Variable               | Description                                                                 |
-| ---------------------- | --------------------------------------------------------------------------- |
-| `NEXTAUTH_SECRET`      | JWT signing key. Must match the Next.js app's `NEXTAUTH_SECRET`             |
-| `INTERNAL_API_SECRET`  | Platform API key. Must match Next.js `KILOCLAW_INTERNAL_API_SECRET`         |
-| `GATEWAY_TOKEN_SECRET` | HMAC key for per-sandbox gateway tokens. Can be any arbitrary value in dev. |
-| `WORKER_ENV`           | Set to `development`                                                        |
+**Auth:**
 
-`NEXTAUTH_SECRET` and `INTERNAL_API_SECRET` must match the Next.js app's
-values. Pull them from Vercel (`vercel env pull` from the monorepo root) or
-get them from a team member.
+| Variable               | Description                                                                 | Source  | Auto-managed |
+| ---------------------- | --------------------------------------------------------------------------- | ------- | ------------ |
+| `NEXTAUTH_SECRET`      | JWT signing key. Must match the Next.js app's `NEXTAUTH_SECRET`             | Vercel  | Yes          |
+| `INTERNAL_API_SECRET`  | Platform API key. Must match Next.js `KILOCLAW_INTERNAL_API_SECRET`         | Vercel  | Yes          |
+| `GATEWAY_TOKEN_SECRET` | HMAC key for per-sandbox gateway tokens. Can be any arbitrary value in dev. | Example | No           |
+| `WORKER_ENV`           | Set to `development`                                                        | Example | No           |
 
-**Fly.io** -- requires access to the Kilo (dev) org:
+**Fly.io:**
 
-| Variable           | Description                                                                             |
-| ------------------ | --------------------------------------------------------------------------------------- |
-| `FLY_API_TOKEN`    | Fly org token. Generate with `fly tokens create -o kilo-dev my-dev-token`               |
-| `FLY_ORG_SLUG`     | Fly org slug (run `fly orgs list` to find it)                                           |
-| `FLY_REGISTRY_APP` | Shared Fly app that holds Docker images (e.g., `kiloclaw-dev`)                          |
-| `FLY_APP_NAME`     | Legacy fallback app name for existing instances (may be removed in future)              |
-| `FLY_REGION`       | Region priority list, e.g. `us,eu`. Tries US first, falls back to EU, then gives up.    |
-| `FLY_IMAGE_TAG`    | Docker image tag. Set automatically by `scripts/push-dev.sh`, or use `latest` to start. |
-| `FLY_IMAGE_DIGEST` | Docker image digest. Set automatically by `scripts/push-dev.sh`.                        |
-| `OPENCLAW_VERSION` | OpenClaw version in the image. Set automatically by `scripts/push-dev.sh`.              |
+| Variable           | Description                                                                             | Source       | Auto-managed |
+| ------------------ | --------------------------------------------------------------------------------------- | ------------ | ------------ |
+| `FLY_API_TOKEN`    | Fly org token                                                                           | dev-start.sh | Yes          |
+| `FLY_ORG_SLUG`     | Fly org slug (read by script for token creation)                                        | Example      | No           |
+| `FLY_REGISTRY_APP` | Shared Fly app that holds Docker images (e.g., `kiloclaw-dev`)                          | Example      | No           |
+| `FLY_APP_NAME`     | Legacy fallback app name for existing instances (may be removed in future)              | Example      | No           |
+| `FLY_REGION`       | Region priority list, e.g. `us,eu`. Tries US first, falls back to EU, then gives up.    | Example      | No           |
+| `FLY_IMAGE_TAG`    | Docker image tag. Set automatically by `scripts/push-dev.sh`, or use `latest` to start. | push-dev.sh  | Yes          |
+| `FLY_IMAGE_DIGEST` | Docker image digest. Set automatically by `scripts/push-dev.sh`.                        | push-dev.sh  | Yes          |
+| `OPENCLAW_VERSION` | OpenClaw version in the image. Set automatically by `scripts/push-dev.sh`.              | push-dev.sh  | Yes          |
 
 `FLY_IMAGE_TAG`, `FLY_IMAGE_DIGEST`, and `OPENCLAW_VERSION` together control
 what version gets deployed by default for your dev instances. The build script
 auto-updates all three. For initial setup, ask a team member for known-working
 values or use `latest` (if a `latest` tag exists in the registry).
 
-**Tunnel / API** -- so Fly machines can reach your local Next.js:
+**Tunnel / API:**
 
-| Variable                | Description                                                |
-| ----------------------- | ---------------------------------------------------------- |
-| `KILOCODE_API_BASE_URL` | Your tunnel URL + `/api/gateway/` (see tunnel setup above) |
+| Variable                | Description                       | Source       | Auto-managed |
+| ----------------------- | --------------------------------- | ------------ | ------------ |
+| `KILOCODE_API_BASE_URL` | Your tunnel URL + `/api/gateway/` | dev-start.sh | Yes          |
 
-**Encryption** -- for decrypting user-provided secrets:
+**Encryption:**
 
-| Variable                     | Description                                                                                                        |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `AGENT_ENV_VARS_PRIVATE_KEY` | RSA private key (PEM). Get the **dev** version from 1Password (engineering vault). Quote the value in `.dev.vars`. |
+| Variable                     | Description                                                                                                        | Source    | Auto-managed |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------- | ------------ |
+| `AGENT_ENV_VARS_PRIVATE_KEY` | RSA private key (PEM). Get the **dev** version from 1Password (engineering vault). Quote the value in `.dev.vars`. | 1Password | No           |
 
 **Other:**
 
-| Variable                   | Description                                       |
-| -------------------------- | ------------------------------------------------- |
-| `OPENCLAW_ALLOWED_ORIGINS` | Comma-separated origins for WebSocket connections |
+| Variable                   | Description                                       | Source  | Auto-managed |
+| -------------------------- | ------------------------------------------------- | ------- | ------------ |
+| `OPENCLAW_ALLOWED_ORIGINS` | Comma-separated origins for WebSocket connections | Example | No           |
 
-### 2. `.env.local` (Next.js, monorepo root)
+### `.env.local` (Next.js, monorepo root)
 
 The Next.js app also needs these two variables to talk to the KiloClaw worker.
-Both are included in `vercel env pull` (see root `DEVELOPMENT.md`):
+Both are included in `vercel env pull` (run automatically by the dev-start
+script):
 
 | Variable                       | Description                                     |
 | ------------------------------ | ----------------------------------------------- |
@@ -469,9 +463,10 @@ All scripts support overrides via env vars (`IMAGE`, `PORT`, `TOKEN`).
 
 **Fly machine can't reach your Next.js / "models require auth":**
 Check that the tunnel is running and `KILOCODE_API_BASE_URL` in `.dev.vars`
-matches the current tunnel URL. Restart the worker after changing it. Symptoms
-are either silent failure (three dots, then nothing) or "models require
-authentication."
+matches the current tunnel URL. The dev-start script sets this automatically,
+but if the tunnel restarts you'll need to re-run the script or update the URL
+manually and restart the worker. Symptoms are either silent failure (three
+dots, then nothing) or "models require authentication."
 
 **"tag latest unknown manifest":**
 The image tag in `FLY_IMAGE_TAG` doesn't exist in the Fly registry. Get
diff --git a/kiloclaw/scripts/.dev-start.conf.example b/kiloclaw/scripts/.dev-start.conf.example
@@ -0,0 +1,19 @@
+# Dev-start script configuration.
+# CLI flags override these values.
+#
+# Place this file in either location:
+#   ~/.config/kiloclaw/dev-start.conf   (shared across all worktrees)
+#   kiloclaw/scripts/.dev-start.conf    (per-worktree override, gitignored)
+
+# Named Cloudflare tunnel (leave empty for temporary quick tunnel)
+# TUNNEL_NAME=          # tunnel
+# TUNNEL_HOSTNAME=      # tunnel.yourdomain.com
+
+# RSA private key for agent env var encryption (get from 1Password, engineering vault)
+# AGENT_ENV_VARS_PRIVATE_KEY=
+
+# How to display the 3 dev processes:
+#   tabs   — separate terminal tabs (default; auto-detects iTerm2 vs Terminal.app)
+#   split  — single tab with split panes (requires iTerm2)
+#   tmux   — tmux session "kiloclaw"
+DISPLAY_MODE=tabs
diff --git a/kiloclaw/scripts/dev-start.sh b/kiloclaw/scripts/dev-start.sh
