* feat(dev): surface dev-stack runtime services in agent system prompt
Add a structured 'runtime services' info object that the dev launchers
(`dev:safe`, `dev:automation`, `dev:docker`, and the published
`agent-canvas` binary) propagate to the frontend via
`VITE_RUNTIME_SERVICES_INFO`. The frontend renders it into a
`<RUNTIME_SERVICES>` markdown block and attaches it as
`AgentContext.system_message_suffix` on every `POST /api/conversations`.
This means agents start each conversation knowing exactly what services
exist in the current dev stack (ingress URL, automation backend URL +
`/api/automation` prefix, auth header, etc.), instead of having to probe
or — worse — assume `localhost:8000` is the automation server when it is
actually the Agent Server they are running inside of.
URLs are written from the agent's point of view: dockerless modes use
`localhost`, `dev:docker` uses `host.docker.internal`. When automation
isn't running in the current mode (e.g. `dev:safe`), the block says so
explicitly so agents know to skip `/api/automation` calls.
Co-authored-by: openhands <openhands@all-hands.dev>
* fix(runtime-services): address review feedback on PR #503
- Validate required `agentServerPort` in `buildRuntimeServicesInfo`;
previously a missing port baked `http://localhost:undefined` into
the agent's system prompt.
- Skip the automation entry when the supplied `automation` object has
no `port` (e.g. a bare `{}` from a misconfigured launcher).
- Rename the JSON service key from `vite` to `frontend` and add a
`kind: "vite" | "static"` discriminator + mode-aware description,
so static-build dev stacks (`dev:docker`, the published binary, ...)
no longer surface a misleading "Vite dev server" line in the agent
system prompt. The renderer still accepts the legacy `vite` key.
- Anchor the "don't guess" warning to the actual agent-server URL from
runtime info instead of hardcoded `localhost:8000`, since the
agent-server uses different ports across dev modes (18000 in
dev:safe, 8000 in dev:docker, ...).
- Plumb `frontendKind` through `buildAutomationRuntimeServicesInfo`
and stamp `config.frontendKind` in `dev-with-automation.mjs::main`
so both Vite spawn and static-build paths describe the frontend
correctly.
- Expand AGENTS.md with the JSON schema of `VITE_RUNTIME_SERVICES_INFO`
and a concrete example of the rendered `<RUNTIME_SERVICES>` block.
- Tests: assert the new URL-in-warning behavior, the new `frontend` /
legacy `vite` rendering, the `agentServerPort`-required guard, the
`automation: {}` skip, and the legacy `vitePort` alias.
Co-authored-by: openhands <openhands@all-hands.dev>
---------
Co-authored-by: openhands <openhands@all-hands.dev>
* feat: update SDK to 1.22.0 and add CI version sync check
- Update DEFAULT_AGENT_SERVER_VERSION from 1.21.1 to 1.22.0 in dev-safe.mjs
- Update SDK version references in AGENTS.md
- Add scripts/check-sdk-version-sync.mjs to verify automation project uses
matching SDK versions for openhands-sdk, openhands-tools, openhands-workspace,
and openhands-agent-server
- Add .github/workflows/sdk-version-sync.yml CI workflow with:
- Path-filtered PR/push triggers for version-related file changes
- repository_dispatch triggers (sdk-version-check, sdk-release) for
external repos to notify when SDK deps change
- workflow_dispatch with optional version override
- Scheduled runs every 6 hours to catch upstream changes
- PyPI version checking support (--check-pypi flag)
The check script supports:
- EXPECTED_SDK_VERSION env var override for CI triggers
- --check-pypi flag to also display latest PyPI versions
- --help for usage documentation
To trigger from external repos (e.g., OpenHands/automation or SDK repo):
curl -X POST -H "Authorization: token \$GITHUB_TOKEN" \\
https://api.github.com/repos/OpenHands/agent-canvas/dispatches \\
-d '{"event_type": "sdk-version-check"}'
* fix: check released PyPI version instead of GitHub main branch
The SDK version sync check now fetches dependencies from the released
openhands-automation package on PyPI (version specified by
DEFAULT_AUTOMATION_VERSION in dev-with-automation.mjs) rather than
fetching pyproject.toml from the GitHub main branch.
This ensures we're checking the actual released version that users
would install, not the development version on main.
* fix: address review feedback for SDK version sync check
- Add env var overrides for automation package name and version
- Add retry logic with exponential backoff for PyPI API failures
- Add semantic version normalization for comparing versions
- Fix repository_dispatch to use client_payload.version
- Improve regex to handle parenthesized dependency formats
- Add comprehensive test coverage for helper functions
* fix: add type casts for dynamic module import in tests
* chore: update automation version to 1.0.0a2
- Update DEFAULT_AUTOMATION_VERSION in dev-with-automation.mjs
- Update AGENTS.md documentation
- Update test expectation
---------
Co-authored-by: openhands <openhands@all-hands.dev>
* fix: move TMUX_TMPDIR to /tmp to avoid socket errors on mounted volumes
Some filesystems (NFS, CIFS, certain FUSE/overlay mounts used by Docker
bind-mounts) do not support Unix domain sockets. When TMUX_TMPDIR pointed
to ~/.openhands/agent-canvas/tmux/ inside a container, tmux failed with:
error connecting to .../tmux-10001/openhands (Operation not supported)
Move tmux socket directory to /tmp/openhands-agent-canvas-tmux which is
always on a local/tmpfs filesystem that supports Unix sockets. Tmux
sockets are ephemeral and don't need persistence across restarts.
Co-authored-by: openhands <openhands@all-hands.dev>
* refactor: drop explicit TMUX_TMPDIR from dev-docker.mjs, use system default
Per review feedback — the container's default TMUX_TMPDIR (/tmp) already
supports Unix domain sockets, so there's no need to set it explicitly.
Co-authored-by: openhands <openhands@all-hands.dev>
---------
Co-authored-by: openhands <openhands@all-hands.dev>
Both `npm run dev` (Docker) and `npm run dev:dangerously-dockerless`
previously generated a fresh random SESSION_API_KEY per process. The
key was passed to the agent-server (OH_SESSION_API_KEYS_0) and to Vite
(VITE_SESSION_API_KEY), but the frontend's `openhands-backends`
localStorage entry was seeded only on the very first load. After a
single restart, the persisted entry's `apiKey` no longer matched the
agent-server, leading to 401s until the user manually edited the
backend.
Fix this by giving `buildSafeDevConfig` a stable default:
- `getOrCreatePersistedSessionApiKey()` reads / creates
`~/.openhands/agent-canvas/session-api-key.txt` (mode 0600). The
in-memory cache is keyed by path so tests can use `mkdtemp` paths.
- `OH_SESSION_API_KEY_PATH` env var overrides the file location
(used by tests; can also be used to pin in unusual setups).
- Existing env overrides (SESSION_API_KEY / OH_SESSION_API_KEYS_0 /
VITE_SESSION_API_KEY) still take precedence.
Because dev:docker and dev:dangerously-dockerless both flow through
the shared `buildSafeDevConfig`, they automatically pick up the
same persisted key and stay in sync with the Vite-baked
VITE_SESSION_API_KEY.
On the frontend, `readStoredBackends` now also re-seeds the default
Local backend when storage parses to `[]` or contains only invalid
entries (previously only `null` triggered seeding). This is safe now
that the persisted key keeps the seed valid across restarts.
Tests:
- New `getOrCreatePersistedSessionApiKey` tests covering creation,
reuse, whitespace trimming, and empty-file regeneration.
- New `buildSafeDevConfig` / `buildConfig` tests covering the
on-disk fallback, restart parity (dev:docker vs
dev:dangerously-dockerless), and env-override precedence.
- New backend-registry storage tests covering re-seed on missing,
empty, and all-invalid storage states.
- Existing tests that previously hit the real
`~/.openhands/agent-canvas/session-api-key.txt` were updated to
use isolated `OH_SESSION_API_KEY_PATH` temp dirs.
Co-authored-by: openhands <openhands@all-hands.dev>
* feat: add dynamic port allocation with preferred port fallback
Implement dynamic port allocation for dev entrypoint scripts to gracefully
handle port conflicts. When a preferred port is busy, the system automatically
finds an alternative available port.
Changes:
- Add findFreePort() and findFreePorts() utilities to dev-safe.mjs
- Add buildSafeDevConfigAsync() for async config with dynamic allocation
- Update dev-with-automation.mjs to use async buildConfig with dynamic ports
- Update dev-static.mjs to use async buildConfig
- Add strictPort: true to vite.config.ts to fail-fast on conflicts
- Update tests for async buildConfig
The utilities try the preferred/default ports first, falling back to
OS-assigned ports only when needed. This preserves predictable defaults
while gracefully handling port conflicts.
Closes#222
* fix: address review feedback - add max retry, document race condition, improve tests
- Add max retry count (100 attempts) to port allocation loop to prevent
infinite loops
- Fix findFreePort to handle preferredPort=0 correctly by skipping the
port check and going straight to OS assignment
- Document race condition limitation in findFreePort JSDoc (accepted
limitation with guidance on handling EADDRINUSE)
- Clarify JSDoc for buildSafeDevConfig vs buildSafeDevConfigAsync with
clear guidance on when to use each
- Remove misleading 'must be after prereq check' comment
- Add comprehensive tests for findFreePort, findFreePorts, and
buildSafeDevConfigAsync using actual port blocking
- Improve buildConfig tests with port uniqueness verification and
fallback tests using high ports
- Use high ports (19xxx range) in tests to avoid conflicts with
system services
Co-authored-by: openhands <openhands@all-hands.dev>
---------
Co-authored-by: openhands <openhands@all-hands.dev>
- Change agent-server SDK default from git main to PyPI 1.21.1
- Change automation default from git main to PyPI 1.0.0a1
- Pin all SDK packages (agent-server, tools, workspace) to same version
- Keep ability to override with OH_AGENT_SERVER_GIT_REF/OH_AUTOMATION_GIT_REF
- Update tests and AGENTS.md documentation
Co-authored-by: openhands <openhands@all-hands.dev>
Mirrors the dev:automation backend stack (agent-server + automation +
ingress) but serves a production frontend build through a small static
server instead of Vite. Designed for use over flaky / high-RTT links
where Vite's ~1000 ESM module fetches make full reloads painfully slow:
hashed assets are now sent with public/immutable cache headers, so an
SPA reload is ~1 round-trip (304 on index.html) and zero asset fetches.
scripts/static-server.mjs: combined static-file server + reverse proxy.
A drop-in for sirv-cli that additionally proxies the same prefixes Vite
proxies in dev (/api, /api/automation, /sockets, /server_info, /alive,
/health, /ready) so hitting :3001 directly behaves like Vite's dev
server — without it, sirv-cli's --single fallback turns /server_info
into the SPA shell whenever a tunnel exposes the static port instead of
the ingress port. Caches /assets/* immutable, index.html no-cache,
weak ETags.
scripts/dev-static.mjs: orchestrator that builds the frontend, then
spawns agent-server, automation, static-server, and the existing
ingress with the same route table as dev-with-automation.
scripts/dev-safe.mjs: add isPortBusy() and
releaseStaleConversationLeases() helpers. The agent-server tags each
conversation directory with an owner_lease.json keyed to a per-process
owner_instance_id (45 s TTL, heartbeat-renewed) and skip-loads any
conversation whose lease is held by a different instance. If the
previous agent-server died ungracefully — or you restart inside the
TTL window — every existing conversation becomes invisible to the new
instance until the leases age out. dev:static now port-checks for a
live agent-server (aborts on conflict), then unlinks stale leases so
conversations created by npm run dev are immediately visible.
Co-authored-by: openhands <openhands@all-hands.dev>
* feat: multi-backend support with cloud SaaS proxy routing
* feat: route conversation export through cloud proxy on cloud backends
* fix: route conversation delete through cloud proxy on cloud backends
* fix: forward settings diffs verbatim through cloud proxy save
* fix: surface cloud-aware settings sub-pages and gate local-only routes
* fix: route secrets settings through cloud proxy on cloud backends
* fix: route conversation stop runtime through cloud proxy on cloud backends
* fix: re-expose planning agent UI for cloud backends and route plan file reads through cloud proxy
* fix: route Display Cost runtime fetch through cloud proxy and ungate local metrics without session API key
* fix: handle WAITING_FOR_SANDBOX task status from cloud backends to prevent UI crash
* fix: re-expose Public Share in conversation menu for cloud backends
* fix: redirect to home when switching backends from a conversation page
* fix: hide cloud orgs the API key can't access in backend selector
* feat: support running multiple local agent-servers with shared persistence
* fix: lint
* fix: failing tests
The openhands-agent-server package exposes an executable named
'agent-server', not 'openhands-agent-server'. When using PyPI versions
(either specific or latest), we need to use the --from syntax:
uvx --from openhands-agent-server agent-server
This fixes the error:
An executable named 'openhands-agent-server' is not provided by
package 'openhands-agent-server'.
Use 'uvx --from openhands-agent-server agent-server' instead.
Fixes#117
Co-authored-by: openhands <openhands@all-hands.dev>
Add a new exported function that builds the environment variables object
for spawning the agent-server process. This allows downstream consumers
(e.g., the automation service) to use the same env vars without
duplicating the mapping logic.
When new env vars are added or existing ones are renamed, downstream
consumers will automatically inherit the changes by using this helper.
Refactored main() to use the new helper internally.
Closes#118
Co-authored-by: openhands <openhands@all-hands.dev>
* feat: use agent server APIs for settings persistence
- Replace localStorage with HTTP API for settings storage
- Use `X-Expose-Secrets: encrypted` header for GET /api/settings
to receive encrypted secrets (not exposing raw values)
- Use `secrets_encrypted: true` in start conversation payload
- Add `getSettingsForConversation()` to build encrypted settings
payload for conversation start endpoint
- Update secrets service to use /api/settings/secrets endpoints
- Add mock handlers for settings and secrets API endpoints
- Update tests for new API-based settings flow
This integrates with software-agent-sdk PR #3060
(feat/encrypted-secrets-in-transit) which adds server-side
encryption support for secrets in transit.
Co-authored-by: openhands <openhands@all-hands.dev>
* fix: update test mocks for encrypted settings API and add OH_SECRET_KEY support
- Update use-create-conversation-metadata.test.ts to mock getSettingsForConversation()
which is now called by buildStartConversationRequestWithEncryptedSettings
- Skip flaky onOpen websocket test that times out intermittently in CI
- Add OH_SECRET_KEY environment variable support in dev-safe.mjs:
- Uses default key for local development
- Can be overridden via OH_SECRET_KEY environment variable
- Logs secret key source at startup
Co-authored-by: openhands <openhands@all-hands.dev>
* docs: update AGENTS.md for settings API and OH_SECRET_KEY
Co-authored-by: openhands <openhands@all-hands.dev>
* fix: update secrets service to use agent-server API routes
Changes:
- Update SecretsService to use /api/settings/secrets endpoints instead of /api/v1/secrets
- Simplify secrets-service.types.ts to remove unused pagination types
- Update use-get-secrets hook to do client-side filtering (agent-server doesn't support pagination)
- Update mock handlers to only use agent-server API routes
- Update secrets-settings test to mock getSecrets instead of searchSecrets
- Remove pageSize option from useSearchSecrets since agent-server doesn't paginate
The agent-server API routes (per SDK PR #3060):
- GET /api/settings/secrets - List secrets (names/descriptions only)
- GET /api/settings/secrets/{name} - Get secret value
- PUT /api/settings/secrets - Upsert secret
- DELETE /api/settings/secrets/{name} - Delete secret
Co-authored-by: openhands <openhands@all-hands.dev>
* docs: update AGENTS.md for secrets API routes
- Document the agent-server secrets CRUD routes in MSW handlers list
- Update git provider token persistence note to reflect server-side storage
Co-authored-by: openhands <openhands@all-hands.dev>
* fix: update secret name validation to match agent-server requirements
- Change pattern from '^\S*$' (no whitespace) to '^[a-zA-Z][a-zA-Z0-9_]{0,63}$'
- Add title prop to SettingsInput component for validation error messages
- Secret names must: start with letter, contain only letters/numbers/underscores, be 1-64 chars
Co-authored-by: openhands <openhands@all-hands.dev>
* feat: include custom secrets in conversation requests via LookupSecret
Custom secrets configured in Settings > Secrets are now automatically
included in conversation start requests. Instead of exposing secret values
to the frontend, we use LookupSecret entries that point to the agent-server
endpoint /api/settings/secrets/{name}. The agent-server fetches the actual
values at runtime.
Changes:
- Add LookupSecret interface to agent-server-adapter.ts
- Add customSecrets option to StartConversationOptions
- Build LookupSecret entries for each custom secret in buildStartConversationRequest
- Update buildStartConversationRequestWithEncryptedSettings to fetch and include
custom secrets list from SecretsService.getSecrets()
- Include X-Session-API-Key header in LookupSecret when configured
This ensures secrets never touch the frontend in plaintext while still
making them available to conversations.
Co-authored-by: openhands <openhands@all-hands.dev>
* fix: address review comments - no localStorage fallback, retry logic, SDK docs
Review feedback addressed:
1. secrets-service.ts: Server storage MUST succeed before updating localStorage
- addGitProvider now stores to server FIRST, only updates localStorage on success
- createSecret/updateSecret/deleteSecret now throw on failure (no silent returns)
- Added retry logic with exponential backoff for all API calls
2. settings-service.api.ts: No silent fallback for encrypted settings
- getSettingsForConversation now throws if encrypted fetch fails
- Conversations should not start with broken/redacted credentials
- Added retry logic with exponential backoff
3. AGENTS.md: Document SDK dependency
- Settings persistence APIs require SDK PR #3060
- Until released, npm run dev defaults to main branch
- Documented git provider storage design (server + localStorage)
4. dev-safe.mjs: Default to SDK main branch
- Added DEFAULT_GIT_REF='main' constant
- npm run dev now uses main until settings APIs are released
- TODO comment to update once released
Note: Git provider tokens still use localStorage for frontend git API calls
(repo search, branches), but MUST succeed on server first.
Co-authored-by: openhands <openhands@all-hands.dev>
* fix: update server secret when only host changes
When updating just the host (empty token), the server secret's description
must also be updated to keep metadata in sync. Previously, only localStorage
was updated, violating the 'server storage must succeed first' principle.
Now the host-only update path also calls createSecret() to update the
server secret's description before updating localStorage.
Co-authored-by: openhands <openhands@all-hands.dev>
---------
Co-authored-by: openhands <openhands@all-hands.dev>
* feat: use uvx for temporary agent-server installation in dev mode
- Replace direct agent-server CLI invocation with uvx temporary install
- Add OH_AGENT_SERVER_VERSION env var for specific PyPI versions
- Add OH_AGENT_SERVER_GIT_REF env var for git commits/branches
- Auto-install uv in .openhands/setup.sh if not present
- Update documentation (README, DEVELOPMENT.md, AGENTS.md)
- Add comprehensive tests for buildAgentServerCommand()
This removes the requirement to permanently install agent-server via
'uv tool install'. Users only need uv installed, and npm run dev will
automatically download and run the appropriate agent-server version.
Co-authored-by: openhands <openhands@all-hands.dev>
* fix: use subdirectory syntax for git ref in uvx monorepo
The software-agent-sdk is a uv workspace monorepo with packages in
subdirectories (openhands-agent-server/, openhands-tools/, etc.).
When installing from git, uvx requires the #subdirectory= fragment to
specify which package to install from the workspace.
Tested with: OH_AGENT_SERVER_GIT_REF=main npm run dev
Co-authored-by: openhands <openhands@all-hands.dev>
---------
Co-authored-by: openhands <openhands@all-hands.dev>
Add actionable dev-safe output when agent-server is missing, including README and uv installation guidance, and update tests plus quickstart docs.
Co-authored-by: openhands <openhands@all-hands.dev>
