Skip to content

πŸ™Œ OpenHands: AI-Driven Development

docs: correct outdated cloud-proxy Rule 2 in AGENTS.md (#17663)

Juan Pedro Michelini Jorge13283554b63e
diff --git a/.agents/skills/custom-codereview-guide.md b/.agents/skills/custom-codereview-guide.md
index a51c8fc197..a0dc7e7ffc 100644
--- a/.agents/skills/custom-codereview-guide.md
+++ b/.agents/skills/custom-codereview-guide.md
@@ -85,13 +85,21 @@ runtime-sandbox API.
- `src/api/no-direct-agent-server-calls.test.ts` is the executable source of
truth. Agent Server access must use `@openhands/typescript-client` with options
from `src/api/agent-server-client-options.ts`.
-- Cloud and runtime-sandbox requests must use `callCloudProxy`; runtime requests
- must provide the correct `hostOverride` and authentication mode.
+- Cloud **App-API** requests must use `callCloudProxy` (now a direct browser
+ call, since the SaaS permits CORS for API-key-authenticated requests). Per-
+ conversation **runtime-sandbox** requests are not proxied: they must call the
+ conversation's runtime URL directly via the typed client
+ (`ConversationClient` / `BashClient` / `RemoteWorkspace` / `FileClient`, or a
+ typed wrapper built via `getAgentServerHttpClientOptions`) with its session
+ API key -- the same path local mode uses. Do not route runtime calls through
+ `callCloudProxy` with `hostOverride`: the `/api/cloud-proxy` envelope it relied
+ on was removed from the agent-server (software-agent-sdk #3326) and 405s on
+ current backends.
- Treat changes to the guard's allowlist as architecture changes. Do not copy the
allowlist into this guide.
Submit **COMMENT** if the PR adds raw `fetch`, `axios`, shared `openHands`, or
-low-level HTTP client access to an Agent Server endpoint.
+low-level HTTP client access to an Agent Server or cloud endpoint.
### Agent Server compatibility
diff --git a/AGENTS.md b/AGENTS.md
index aeb17c990f..8dfb70f2d6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -429,44 +429,48 @@ const data = await fetch(`/api/conversations/${id}`);
- `src/api/cloud/proxy.ts` -- the proxy envelope POST itself
- `src/api/main-app-auth.ts` -- the local main-app authentication endpoint
-### Rule 2 -- Cloud backend routes must go through `callCloudProxy`
+### Rule 2 -- Cloud App-API routes must go through `callCloudProxy`
-Any call from the browser to the cloud backend (`app.all-hands.dev`) or a cloud
-runtime sandbox (`*.prod-runtime.all-hands.dev`) **must** go through `callCloudProxy()`
-in `src/api/cloud/proxy.ts`. These origins do not permit CORS from `localhost`;
-`callCloudProxy` POSTs the request envelope to `/api/cloud-proxy` on the local
-agent-server, which forwards it server-side.
+Calls from the browser to the **cloud App API** (`app.all-hands.dev`) -- the
+endpoints that live on the cloud backend host, not a per-conversation runtime
+sandbox -- **must** go through `callCloudProxy()` in `src/api/cloud/proxy.ts`.
+The SaaS now permits CORS for API-key-authenticated browser requests
+(`ApiKeyAwareCORSMiddleware`), so `callCloudProxy` issues these calls **directly**
+from the browser to `backend.host`; it no longer tunnels them through a
+server-side proxy.
```ts
import { callCloudProxy } from "../cloud/proxy";
-// CORRECT -- cloud endpoint
+// CORRECT -- cloud App-API endpoint, called directly with bearer auth
const result = await callCloudProxy<ResponseType>({
backend,
method: "GET",
path: `/api/v1/app-conversations/search?${params}`,
});
-// CORRECT -- cloud runtime sandbox, auth via session key
-const result = await callCloudProxy<ResponseType>({
- backend,
- method: "GET",
- hostOverride: buildHttpBaseUrl(conversationUrl),
- path: `/api/git/changes?path=${path}`,
- authMode: "session-api-key",
- sessionApiKey,
-});
-
-// WRONG -- direct fetch/axios to a cloud host is blocked by CORS in the browser
+// WRONG -- direct axios/fetch to a cloud host bypasses the typed cloud transport
const result = await axios.get(`${backend.host}/api/v1/app-conversations`);
```
+**Runtime-sandbox calls are NOT proxied.** Per-conversation runtime hosts
+(`*.prod-runtime.all-hands.dev`) are reached **directly** with the typed client
+(`ConversationClient` / `BashClient` / `RemoteWorkspace` / `FileClient`, or a
+typed wrapper built via `getAgentServerHttpClientOptions`) pointed at the
+conversation's `conversation_url`, authenticated with its session API key -- the
+same path local mode uses. Do **not** route runtime calls through
+`callCloudProxy` with `hostOverride`: that used to POST an envelope to
+`/api/cloud-proxy` on the local agent-server, but that endpoint was **removed**
+from the agent-server (software-agent-sdk PR #3326) and is absent on the
+SaaS/enterprise backend, so such calls return **405**. If you find a cloud runtime
+branch still using `hostOverride`, migrate it to the direct typed-client path.
+
`callCloudProxy` key options:
- `backend` -- the cloud `Backend` object (provides host and bearer token)
-- `hostOverride` -- override for runtime-sandbox calls; replaces `backend.host`
-- `authMode` -- `"bearer"` (default, cloud) | `"session-api-key"` (runtime sandbox) | `"none"`
-- `sessionApiKey` -- required when `authMode === "session-api-key"`
+- `authMode` -- `"bearer"` (default, cloud App API) | `"none"`
+ (`hostOverride` / `"session-api-key"` is legacy; the `/api/cloud-proxy` envelope
+ it relied on no longer exists -- see above)
Standard cloud/local branch pattern used throughout the service layer: