Skip to content

πŸ™Œ OpenHands: AI-Driven Development

fix: use X-Session-API-Key for local automation auth in prompts and RUNTIME_SERVICES (#999)

Tim O'Farrelld0994a6fe1e6
diff --git a/AGENTS.md b/AGENTS.md
index cf096095bb..52d123b12f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -25,7 +25,7 @@
- The block lists URLs **from the agent's point of view**:
- The Agent Server is always reachable as `http://localhost:<port>` from inside the sandbox β€” but that is _you_, not the automation backend.
- Host-side services (ingress, Vite, automation) are reachable as `http://localhost:<port>`.
-- Agents should treat the `<RUNTIME_SERVICES>` block as authoritative: don't hardcode `localhost:8000` for "the automation server", and don't probe random ports trying to discover services. If the block says automation is not running, skip `/api/automation` calls; otherwise use the listed `url_from_agent` + `api_prefix` (default `/api/automation`) and the `X-API-Key: $OPENHANDS_AUTOMATION_API_KEY` header.
+- Agents should treat the `<RUNTIME_SERVICES>` block as authoritative: don't hardcode `localhost:8000` for "the automation server", and don't probe random ports trying to discover services. If the block says automation is not running, skip `/api/automation` calls; otherwise use the listed `url_from_agent` + `api_prefix` (default `/api/automation`) and the `X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY` header.
- The launcher β†’ frontend β†’ suffix plumbing is:
- `scripts/dev-safe.mjs::buildRuntimeServicesInfo()` β€” pure helper that constructs the info object.
- `scripts/dev-with-automation.mjs::buildAutomationRuntimeServicesInfo()` β€” wraps it with automation details; called from both Vite spawn (`startVite`) and the static build (`static-build.mjs`).
@@ -53,7 +53,7 @@ The env var is a JSON string of:
"url_from_agent": "http://localhost:3001"
},
"automation": {
- "description": "OpenHands Automations service. All routes are mounted under '/api/automation'. Authenticate with header 'X-API-Key: $OPENHANDS_AUTOMATION_API_KEY'.",
+ "description": "OpenHands Automations service. All routes are mounted under '/api/automation'. Authenticate with header 'X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY'.",
"url_from_agent": "http://localhost:18001",
"api_prefix": "/api/automation",
"docs_url": "http://localhost:18001/api/automation/docs",
@@ -81,10 +81,10 @@ from your point of view (i.e., as you should curl/fetch them).
* Frontend: http://localhost:3001
Vite dev server hosting the agent-canvas frontend.
* Automation backend: http://localhost:18001
- OpenHands Automations service. All routes are mounted under '/api/automation'. Authenticate with header 'X-API-Key: $OPENHANDS_AUTOMATION_API_KEY'.
+ OpenHands Automations service. All routes are mounted under '/api/automation'. Authenticate with header 'X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY'.
Docs: http://localhost:18001/api/automation/docs
OpenAPI: http://localhost:18001/api/automation/openapi.json
- Auth: header 'X-API-Key: $OPENHANDS_AUTOMATION_API_KEY'
+ Auth: header 'X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY'
Trust this block over guessing: do not assume any other URLs are running.
In particular, http://localhost:18000 inside your sandbox is the Agent Server
diff --git a/__tests__/api/agent-server-adapter.test.ts b/__tests__/api/agent-server-adapter.test.ts
index c82028b565..f628d539d1 100644
--- a/__tests__/api/agent-server-adapter.test.ts
+++ b/__tests__/api/agent-server-adapter.test.ts
@@ -795,7 +795,8 @@ describe("buildRuntimeServicesSystemSuffix", () => {
expect(suffix).toContain("http://localhost:18000");
expect(suffix).toContain("http://localhost:18001");
expect(suffix).toContain("http://localhost:18001/api/automation/docs");
- expect(suffix).toContain("X-API-Key: $OPENHANDS_AUTOMATION_API_KEY");
+ expect(suffix).toContain("X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY");
+ expect(suffix).not.toContain("X-API-Key: $OPENHANDS_AUTOMATION_API_KEY");
expect(suffix).toContain("</RUNTIME_SERVICES>");
// The "don't guess" line should reference the actual agent-server URL
// for this stack, not a hardcoded port. The assertion anchors on the URL
diff --git a/scripts/dev-safe.mjs b/scripts/dev-safe.mjs
index 322a63d1eb..c85d40fc78 100644
--- a/scripts/dev-safe.mjs
+++ b/scripts/dev-safe.mjs
@@ -782,7 +782,7 @@ export function buildRuntimeServicesInfo(options) {
description:
"OpenHands Automations service. All routes are mounted under " +
`'${apiPrefix}'. Authenticate with header ` +
- `'X-API-Key: $${authEnvVar}'.`,
+ `'X-Session-API-Key: $${authEnvVar}'.`,
url_from_agent: baseUrl,
api_prefix: apiPrefix,
docs_url: `${baseUrl}${apiPrefix}/docs`,
diff --git a/src/api/agent-server-adapter.ts b/src/api/agent-server-adapter.ts
index 075cf39431..d8ee2e36fc 100644
--- a/src/api/agent-server-adapter.ts
+++ b/src/api/agent-server-adapter.ts
@@ -199,8 +199,10 @@ export function buildRuntimeServicesSystemSuffix(): string | undefined {
lines.push(` OpenAPI: ${automation.openapi_url}`);
}
if (automation.auth_env_var) {
+ // X-Session-API-Key is the local convention shared by the agent-server
+ // and automation backend (see openhands-automation auth.py).
lines.push(
- ` Auth: header 'X-API-Key: $${automation.auth_env_var}'`,
+ ` Auth: header 'X-Session-API-Key: $${automation.auth_env_var}'`,
);
}
} else {
diff --git a/src/components/features/automations/recommended-automations-launcher.tsx b/src/components/features/automations/recommended-automations-launcher.tsx
index 5ab90710b4..9d457d5850 100644
--- a/src/components/features/automations/recommended-automations-launcher.tsx
+++ b/src/components/features/automations/recommended-automations-launcher.tsx
@@ -73,7 +73,7 @@ export function buildAutomationPrompt(
"**Which API to use:** Create this automation using the **local** OpenHands Automations API that is running alongside this agent.",
"- Read the Automation backend URL from the `<RUNTIME_SERVICES>` block in your system context.",
"- Endpoint path: `POST /api/automation/v1/preset/prompt`",
- "- Auth: `X-API-Key: $OPENHANDS_AUTOMATION_API_KEY`",
+ "- Auth: `X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY`",
"- If no local Automation backend is listed in `<RUNTIME_SERVICES>`, stop and ask me to start the full local automation stack instead of using any remote/cloud automation API.",
].join("\n");
}