Openhands on Alwaldend

OpenHands

Mon, 01 Jan 0001 00:00:00 +0000

OpenHands deploys as separate components because each owns a distinct responsibility and trust boundary:

Component	Responsibility
Agent Canvas	Browser client for conversations, files, settings, backends, automations
Agent Server	Runs conversations, agents, tools, and workspace operations
Automation Server	Stores schedules and triggers, tracks runs, dispatches conversations

The agent server runs directly on the host with the service account’s permissions. Its workspace is a working directory; operating-system account permissions define its access to the host. Treat the agent server host as trusted infrastructure.

OpenHands automation

Mon, 01 Jan 0001 00:00:00 +0000

Runs the OpenHands automation server natively from a uv-managed virtual environment. It stores schedules and event triggers, tracks run lifecycle, and dispatches conversations to the agent server.

The automation server is not a sandbox. It records which agent server should run a dispatched conversation and hands that work to AUTOMATION_AGENT_SERVER_URL; setting that variable selects the agent server’s local mode, which uses a persistent local agent server instead of managed OpenHands Cloud sandboxes.

OpenHands canvas

Mon, 01 Jan 0001 00:00:00 +0000

Runs the OpenHands Agent Canvas browser client from the published npm package. The service listens on loopback port openhands_canvas_port; TLS, the public hostname, and routing to the agent server and automation API belong to the deployment’s Traefik role.

The service runs the package’s scripts/static-server.mjs directly with Node, an explicit loopback host, and the package’s build/ directory. It serves the browser client without starting an agent server, an automation server, or the npm launcher’s additional ingress process. Agent Canvas owns no conversation or automation state and executes no tools.

OpenHands canvas UI compatibility module

Mon, 01 Jan 0001 00:00:00 +0000

tools/canvas_ui_tool.py from OpenHands/OpenHands at tag v1.18.0 (commit 9120ff6cbbe23640f0e475661e5a9c9729cdbf1f). The OpenHands Agent Canvas launchers import it into the agent server through --import-modules canvas_ui_tool.

It is required because the automation preset builds its agent with a finish_tool_response_schema, which registers the SDK’s builtin FinishTool only inside the preset’s own process while advertising it to the agent server as openhands.sdk.tool.builtins.finish. That SDK module does not self-register, so every automation-dispatched remote conversation fails to resolve FinishTool unless the compatibility module registers it in the agent server process first.

Openhands server

Mon, 01 Jan 0001 00:00:00 +0000

Runs the OpenHands agent server natively from a uv-managed virtual environment. It hosts conversations, executes tools, and streams events for Agent Canvas. The service binds loopback only; TLS and external reachability belong to the calling deployment.

Set openhands_server_secure to true to require a session API key. The unsecured mode omits the session key and is only appropriate where the loopback boundary is trusted.

The caller can set openhands_server_install_packages to false and install openhands_server_packages through its host-specific package workflow. OSTree hosts use the shared dev_vm package entry point and must boot into a deployment containing those dependencies before installing the service. They also set openhands_server_service_path under /etc/systemd/system.