π OpenHands: AI-Driven Development
fix: persist OH_SECRET_KEY to secret-key.txt in dev mode, same as Docker (#957)
Tim O'Farrell95b6d7a23e07
diff --git a/AGENTS.md b/AGENTS.mdindex 079647e3b0..7810816da9 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -412,14 +412,14 @@ When adding code that needs a new string, decide up front which rule it falls un- `OH_AGENT_SERVER_LOCAL_PATH` β absolute path to a local `software-agent-sdk` checkout. Runs the local checkout via `uvx` with `--with-editable` for `openhands-sdk`/`openhands-tools`/`openhands-workspace` and `--reinstall` for `openhands-agent-server`, so SDK edits are picked up on restart. Highest precedence.- `OH_AGENT_SERVER_GIT_REF` β git commit SHA or branch name (takes precedence over version)- `OH_AGENT_SERVER_VERSION` β specific PyPI version (e.g., "1.24.0")- - `OH_SECRET_KEY` β secret key for settings encryption; uses a static default for local dev since it's needed for reading persisted encrypted values across restarts+ - `OH_SECRET_KEY` β secret key for settings encryption; auto-generated and persisted to `~/.openhands/agent-canvas/secret-key.txt` on first run (same file Docker uses), ensuring dev mode and Docker share the same key when both mount the same `~/.openhands` directory. Override with the env var to pin a specific key.- `SESSION_API_KEY` / `OH_SESSION_API_KEYS_0` / `VITE_SESSION_API_KEY` β session API key for agent-server authentication; auto-generated using `crypto.randomBytes(32)` if not set, passed to both agent-server (`OH_SESSION_API_KEYS_0`) and frontend (`VITE_SESSION_API_KEY`)- Default: released PyPI version `1.24.0` for agent-server SDK libraries- Security: `scripts/dev-safe.mjs` and `scripts/dev-with-automation.mjs` auto-generate random API keys when needed and persist the defaults so static builds, localStorage, and restarted services stay in sync:- `SESSION_API_KEY` β 64-character hex (256-bit) for agent-server API authentication; persisted at `~/.openhands/agent-canvas/session-api-key.txt` unless overridden via env var- `AUTOMATION_LOCAL_API_KEY` β 64-character hex for automation backend auth; persisted at `~/.openhands/agent-canvas/automation-api-key.txt` unless overridden- - `OH_SECRET_KEY` β kept as a static default because it's used for encrypting/decrypting persisted settings values and needs consistency across restarts+ - `OH_SECRET_KEY` β 64-character hex (256-bit) for settings encryption; persisted at `~/.openhands/agent-canvas/secret-key.txt` unless overridden via env var. Same file used by `docker/entrypoint.sh`, so dev mode and Docker share the same key automatically.- `scripts/dev-safe.mjs` should fail fast if `uvx` cannot be spawned (for example missing PATH entries).- `npm run dev` runs the full local stack via `uvx` (agent-server + automation backend + Vite dev server + ingress proxy) with no Docker dependency. `npm run dev:static` does the same but serves a production build of the frontend instead of the Vite dev server.- `scripts/dev-with-automation.mjs` runs the full stack: agent-server, automation backend (both via uvx), frontend server, and ingress proxy. It defaults to Vite when run directly, supports `--static` for an existing build, and supports `--dynamic` so wrappers that default static can opt back into Vite. Uses a standalone ingress proxy (`scripts/ingress.mjs`) to route traffic:@@ -429,7 +429,7 @@ When adding code that needs a new string, decide up front which rule it falls un- Environment variables: `PORT` (ingress port, default: 8000), `OH_AUTOMATION_GIT_REF` (git ref, overrides default version), `OH_AUTOMATION_VERSION` (default: `1.0.0a3`), `AUTOMATION_LOCAL_API_KEY` (optional, use a fixed key; default: persisted generated key), `OH_AUTOMATION_API_KEY_PATH` (override the persisted default key path)- `scripts/check-sdk-version-sync.mjs` checks the released `openhands-automation` package against `versions.automationSdk` in `config/defaults.json`; that value may intentionally lag `versions.agentServer` while automation has not yet published a matching release.- Access points: `http://localhost:8000/` (main UI), `http://localhost:8000/api/automation/docs` (API docs)- - Security: `AUTOMATION_LOCAL_API_KEY` defaults to a generated key persisted across restarts because static frontend builds bake it into `VITE_AUTOMATION_API_KEY`. Set the env var explicitly to rotate or pin it. The cipher key (`OH_SECRET_KEY`) keeps a static default for local dev since it's used for encrypting/decrypting persisted settings values.+ - Security: `AUTOMATION_LOCAL_API_KEY` defaults to a generated key persisted across restarts because static frontend builds bake it into `VITE_AUTOMATION_API_KEY`. Set the env var explicitly to rotate or pin it. The cipher key (`OH_SECRET_KEY`) is persisted at `~/.openhands/agent-canvas/secret-key.txt` (same file used by `docker/entrypoint.sh`); both modes share the same key automatically when using the same `~/.openhands` directory.- `scripts/ingress.mjs` is a standalone HTTP reverse proxy that can be used independently to route traffic to multiple backends based on URL path prefix.- `scripts/dev-safe.mjs` (now `npm run dev:minimal`) runs just agent-server + Vite without automation.- Vite dev mode can black-screen on first load with `504 Outdated Optimize Dep` if core client-entry deps are not prebundled; keep `react`, `react/jsx-runtime`, `react-dom/client`, and `react-router/dom` in `optimizeDeps.include`.@@ -528,13 +528,13 @@ When adding code that needs a new string, decide up front which rule it falls un- ESLint config (flat, ESLint 9): the project uses `eslint.config.js` (not `.eslintrc`) and runs on `[email protected]`, not 10. The constraint pinning us below 10 is `[email protected]`, which still calls `context.getFilename()` at rule-load time β that API was removed in ESLint 10 and `@eslint/compat`'s `fixupPluginRules` does NOT shim it. Don't try to bump eslint past 9 until eslint-plugin-react ships a v10-compatible release. Import rules come from `eslint-plugin-import-x` (the maintained fork of `eslint-plugin-import`) but are registered under both `import-x/` and `import/` prefixes via `plugins: { import: importXPlugin, ... }` so existing `// eslint-disable-next-line import/...` directives keep working. `linterOptions.reportUnusedDisableDirectives` is set to `"warn"` (not "off") so stale airbnb-era disable comments still surface in lint output without failing CI. The TS-overrides block has an `ignores: ["src/hooks/query/query-keys.ts"]` so the `no-restricted-syntax` rule banning raw `["settings", ...]` query keys doesn't fire on the file that defines the helpers themselves. No `.npmrc` / `legacy-peer-deps` flag is needed β all our plugins declare ESLint 9 peer compatibility.-- **Centralized config**: `config/defaults.json` is the single source of truth for version pins (agent-server, automation, automation SDK), port defaults, persistence paths, package names, and the dev secret key. All consumers read from this file:+- **Centralized config**: `config/defaults.json` is the single source of truth for version pins (agent-server, automation, automation SDK), port defaults, persistence paths, and package names. All consumers read from this file:- JS scripts (`dev-safe.mjs`, `dev-with-automation.mjs`, `check-sdk-version-sync.mjs`) read it via `JSON.parse(readFileSync(...))`.- Docker: a `config-gen` build stage converts the JSON to `/opt/agent-canvas/defaults.env` (shell-sourceable); `entrypoint.sh` sources it at startup.- CI workflow: a `Read defaults from config/defaults.json` step uses `node -p` to extract values into `$GITHUB_OUTPUT`.- Dockerfile ARG defaults are kept as fallbacks for local `docker build` without the CI workflow; CI always passes `--build-arg` overrides from the JSON.- To bump a version, edit `config/defaults.json` only β the JS scripts, Docker build, and CI workflow all derive their values from it.-- Docker all-in-one image: `.github/workflows/docker.yml` builds and publishes `ghcr.io/openhands/agent-canvas` β a combined image that bundles the agent-server (from `ghcr.io/openhands/agent-server`), the automation server (`openhands-automation` via pip), and the agent-canvas frontend (static build). The Dockerfile lives at `docker/Dockerfile`, the entrypoint at `docker/entrypoint.sh`. The workflow structure mirrors the SDK repo's `server.yml`: a `build-and-push-image` matrix job (2 Γ arch: amd64 on `ubuntu-24.04`, arm64 on `ubuntu-24.04-arm`) pushes arch-suffixed tags, then `merge-manifests` creates multi-arch manifests via `docker buildx imagetools create`, then `consolidate-build-info` aggregates artifacts, and `update-pr-description` updates the PR body (using `<!-- AGENT_CANVAS_DOCKER_START -->` / `<!-- AGENT_CANVAS_DOCKER_END -->` markers). The workflow triggers on push to main, `v*` tags (releases), PRs, and `workflow_dispatch`. On release tags it also pushes semver tags (e.g. `1.2.3`, `1.2`, `1`, `latest`). Fork PRs are skipped (no GHCR auth). The image exposes port 8000 as a unified entry point: `/api/automation/*` β automation (:18001), `/api/*` β agent-server (:18000), `/*` β static frontend. The Dockerfile accepts a `VITE_APP_ENV` build arg (default empty β staging PostHog key); the CI workflow passes `VITE_APP_ENV=production` only for tagged releases (`refs/tags/v*`), so PR and main-branch images use the staging key while release images use the production key, matching the `build:lib` npm path. The entrypoint auto-generates **both** the session API key and `OH_SECRET_KEY` (persisted to `~/.openhands/agent-canvas/session-api-key.txt` and `secret-key.txt` respectively) when none is provided, so the image runs secure by default. Users can override either via env var (`OH_SECRET_KEY`, `SESSION_API_KEY` / `OH_SESSION_API_KEYS_0`). Unlike `scripts/dev-safe.mjs` (which uses a static default secret key for local dev convenience), the Docker entrypoint never falls back to a known default.+- Docker all-in-one image: `.github/workflows/docker.yml` builds and publishes `ghcr.io/openhands/agent-canvas` β a combined image that bundles the agent-server (from `ghcr.io/openhands/agent-server`), the automation server (`openhands-automation` via pip), and the agent-canvas frontend (static build). The Dockerfile lives at `docker/Dockerfile`, the entrypoint at `docker/entrypoint.sh`. The workflow structure mirrors the SDK repo's `server.yml`: a `build-and-push-image` matrix job (2 Γ arch: amd64 on `ubuntu-24.04`, arm64 on `ubuntu-24.04-arm`) pushes arch-suffixed tags, then `merge-manifests` creates multi-arch manifests via `docker buildx imagetools create`, then `consolidate-build-info` aggregates artifacts, and `update-pr-description` updates the PR body (using `<!-- AGENT_CANVAS_DOCKER_START -->` / `<!-- AGENT_CANVAS_DOCKER_END -->` markers). The workflow triggers on push to main, `v*` tags (releases), PRs, and `workflow_dispatch`. On release tags it also pushes semver tags (e.g. `1.2.3`, `1.2`, `1`, `latest`). Fork PRs are skipped (no GHCR auth). The image exposes port 8000 as a unified entry point: `/api/automation/*` β automation (:18001), `/api/*` β agent-server (:18000), `/*` β static frontend. The Dockerfile accepts a `VITE_APP_ENV` build arg (default empty β staging PostHog key); the CI workflow passes `VITE_APP_ENV=production` only for tagged releases (`refs/tags/v*`), so PR and main-branch images use the staging key while release images use the production key, matching the `build:lib` npm path. The entrypoint auto-generates **both** the session API key and `OH_SECRET_KEY` (persisted to `~/.openhands/agent-canvas/session-api-key.txt` and `secret-key.txt` respectively) when none is provided, so the image runs secure by default. Users can override either via env var (`OH_SECRET_KEY`, `SESSION_API_KEY` / `OH_SESSION_API_KEYS_0`). `scripts/dev-safe.mjs` uses the same `secret-key.txt` file, so dev mode and Docker share the same key when both use the same `~/.openhands` directory.- Spec files live under `specs/`. Spec IDs are stable β never renumber. Mark deprecated specs with ~~strikethrough~~. Tag implementation code and tests with `// @spec BM-002 β Short title` comments so specs are grep-able across the codebase (`grep -rn '@spec BM-' src/ __tests__/`). Place the comment on the line immediately above the relevant code block or test. When multiple tests cover the same spec, use `it.each` if the test structure is identical.diff --git a/config/defaults.json b/config/defaults.jsonindex 4cdc336272..83db90b46a 100644--- a/config/defaults.json+++ b/config/defaults.json@@ -30,9 +30,5 @@"automation": "openhands-automation","tools": "openhands-tools","workspace": "openhands-workspace"- },-- "defaults": {- "secretKey": "openhands-dev-secret-key-change-in-prod"}}diff --git a/scripts/dev-safe.mjs b/scripts/dev-safe.mjsindex b8ca3d46fb..dd98b2d382 100644--- a/scripts/dev-safe.mjs+++ b/scripts/dev-safe.mjs@@ -42,7 +42,6 @@ const LOCAL_AGENT_SERVER_SUBDIRS = ["openhands-tools","openhands-workspace",];-const DEFAULT_SECRET_KEY = SHARED_DEFAULTS.defaults.secretKey;const DEFAULT_AGENT_SERVER_VERSION = SHARED_DEFAULTS.versions.agentServer;const FRONTEND_REQUIRED_BINS = ["cross-env", "react-router"];@@ -70,6 +69,20 @@ export const DEFAULT_SESSION_API_KEY_PATH = path.join("session-api-key.txt",);+// Where the OH_SECRET_KEY is persisted so dev mode and Docker mode share the+// same encryption key when both use ~/.openhands as their state directory.+// docker/entrypoint.sh reads and writes this same file, so whichever mode runs+// first generates the key and the other picks it up automatically.+//+// To rotate the key, delete this file and restart both modes. To pin a key+// explicitly, export OH_SECRET_KEY β that takes precedence over the file.+export const DEFAULT_SECRET_KEY_PATH = path.join(+ homedir(),+ ".openhands",+ "agent-canvas",+ "secret-key.txt",+);+// Cache so repeated lookups within a single process return the same key,// keyed by file path so tests can use temp paths in isolation.const persistedApiKeyCache = new Map();@@ -568,8 +581,14 @@ function buildConfigFromPorts(ports, cwd, env) {);const conversationsPath = path.join(stateDir, "conversations");const workspacesPath = path.join(stateDir, "workspaces");- // Use provided secret key or default for local development- const secretKey = env.OH_SECRET_KEY || DEFAULT_SECRET_KEY;+ // Use provided secret key, or read/generate one persisted to+ // ~/.openhands/agent-canvas/secret-key.txt. Persisting ensures dev mode+ // and Docker mode share the same encryption key when they mount the same+ // ~/.openhands directory (docker/entrypoint.sh reads/writes the same file).+ const secretKeyPath =+ env.OH_SECRET_KEY_PATH || DEFAULT_SECRET_KEY_PATH;+ const secretKey =+ env.OH_SECRET_KEY || getOrCreatePersistedApiKey(secretKeyPath, "secret");// Use provided session API key or fall back to a key persisted to// ~/.openhands/agent-canvas/session-api-key.txt. Persisting on disk keeps// the agent-server, the Vite-baked VITE_SESSION_API_KEY, and any@@ -899,7 +918,7 @@ async function main() {const secretKeySource = process.env.OH_SECRET_KEY? "custom (from OH_SECRET_KEY)"- : "default (for local development)";+ : `persisted (${process.env.OH_SECRET_KEY_PATH || DEFAULT_SECRET_KEY_PATH})`;const sessionKeySource =process.env.SESSION_API_KEY ||