This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Specifications

1 - Infra openhands

1.1 - OpenHands infrastructure

Describe the checked-in OpenHands component deployment, host boundaries, ingress routing, and Vault secret references. These requirements describe desired configuration and do not establish live deployment or service health.

The deployment SHALL run Agent Canvas, the agent server, and the automation server as distinct components, because each owns a different responsibility. The agent server SHALL run natively with its service account’s host permissions. The deployment documentation SHALL identify those permissions as the execution boundary and the workspace as its working directory.

  • WHEN a reader inspects the deployment
  • THEN the canvas serves the browser client, the agent server runs conversations and workspace operations, and the automation server stores schedules and dispatches conversations
  • AND the documentation states that the agent server acts with its service account’s permissions on its host

infra/vault/tf SHALL declare the src_infra_openhands AppRole through a module under infra/vault/tf/approle_src_infra_openhands/, including its entity, group, SSH host-key signing role for openhands.alwaldend.com, and server PKI role for the component hostnames. The AppRole SHALL receive only the secrets, SSH, and certificate policies it needs, and the component SHALL authenticate with it rather than a shared or administrative identity.

  • WHEN the Vault configuration is evaluated
  • THEN the AppRole, SSH role, and server PKI role are declared in the AppRole module and referenced by the shared identity groups
  • AND the component’s al.lua selects that AppRole by name

tf_setup SHALL create the canvas, secured agent server, and automation server VMs in the src_infra_openhands Xen Orchestra resource set. Each VM SHALL derive its hostname, address, and MAC from one record in dnsconfig.json. Ansible SHALL deploy the components natively, without containers.

  • WHEN a new component is added
  • THEN one record in dnsconfig.json owns its name and static address
  • AND the provisioning vms map references that record prefix

Component roles SHALL install and run their services on loopback and SHALL NOT declare their own ingress. The deployment SHALL expose them through the shared Traefik role with per-component dynamic configuration.

  • WHEN a component host is deployed
  • THEN the shared traefik role writes its dynamic configuration
  • AND the component role itself declares no router, entry point, or certificate resolver
  • WHEN the canvas service starts
  • THEN the package’s static server serves the packaged browser assets on the declared loopback address
  • AND it starts no agent server, automation server, or additional proxy

The deployment SHALL document configuring the browser backend with the canvas origin and shared session key. The canvas origin SHALL proxy the backend API paths to the agent server and automation server ahead of the frontend route. Backend targets SHALL use site-local hostnames, and downstream routers SHALL accept the forwarded canvas Host header.

  • WHEN the browser uses the canvas origin as its configured backend and requests an automation or agent server API path
  • THEN Traefik forwards it to the matching backend service
  • AND the browser issues no cross-origin request
  • AND the inter-service hop selects the downstream router without traversing the public ingress

The component SHALL declare the public canvas.openhands.alwaldend.com CNAME and the site-local canvas backend address consumed by its ingress service entry. Canvas integration SHALL satisfy the existing ingress routing and client-authentication requirements.

  • WHEN the OpenHands DNS and ingress service declarations are inspected
  • THEN the public canvas CNAME selects the shared ingress and the service entry selects the component’s site-local backend address
  • AND the integration uses the ingress owner’s existing TLS policy

Secret values SHALL be stored in Vault and referenced only by path, environment variable name, or plugin label. The component al.lua SHALL inject them through the repository’s injector plugin, and tasks that could reveal them SHALL use no_log. The session API key SHALL be shared by the agent server, the automation server, and the browser because all three authenticate the same X-Session-API-Key value.

  • WHEN the deployment reads the session key, secret key, or automation KV secret
  • THEN it receives them from the injected environment rather than committed files
  • AND the environment file that receives them is written with no_log

The unsecured agent server SHALL be owned and deployed by the host project that owns its host, not by the OpenHands VM package. It SHALL bind to loopback, receive no session API key, and add no ingress or firewall exposure of its own.

  • WHEN a reader inspects the unsecured agent server deployment
  • THEN the host project’s inventory, playbook, group variables, and secret injection declare it
  • AND the OpenHands Ansible inventory contains only the three VM components

2 - Owned dns

2.1 - owned-dns Specification

Define OpenHands DNS management through the owner’s tf_setup root, including canonical declarations, scoped credentials, and offline source checks before adopting live records.

The tf_setup root SHALL consume this owner’s canonical dnsconfig.json through the shared DNS Terraform module, preserving declared record identities and views. DNS resources SHALL default to disabled before adoption and SHALL default to enabled in the reviewed adoption revision. Adoption SHALL bind existing records to their exact provider identities and SHALL preserve their declared attributes. Existing-record adoption SHALL contain no DNS record additions, changes, replacements, or deletions. Verified missing declarations MAY be provisioned through an exact additions-only DNS plan that preserves every existing record and excludes non-DNS managed-resource changes. After deployment, default DNS reconciliation SHALL retain the bindings and preserve unrelated provider records.

  • WHEN the checked-in root is evaluated with default inputs before adoption
  • THEN it reads this owner’s declaration and disables managed DNS records
  • AND the package contains the module and declaration inputs
  • WHEN the reviewed adoption revision is evaluated with default inputs after adoption
  • THEN it reads this owner’s declaration and enables managed DNS records
  • AND the package contains the module and declaration inputs
  • WHEN the owner’s existing records are adopted through its scoped DNS wrappers
  • THEN Terraform binds the records to their exact provider identities
  • AND their declared values, attributes, and views remain unchanged
  • AND the reviewed adoption plan contains no DNS additions, changes, replacements, or deletions
  • WHEN the adopted root plans with default inputs and unchanged declarations and provider records
  • THEN the plan retains the adopted bindings and contains no DNS additions, changes, replacements, or deletions
  • AND unrelated provider records remain unchanged
  • WHEN fresh complete provider inventories prove the owner’s declared records are absent and conflict-free
  • THEN the reviewed DNS plan creates only those declared missing records
  • AND existing provider identities and attributes remain unchanged
  • AND a subsequent DNS plan contains no changes

The dns.plan, dns.show, and dns.apply wrappers SHALL select dns=1 through the repository AL flow using src_infra_openhands, and operate on module.dns and its dependencies in the existing tf_setup root and Vault HTTP backend. Apply SHALL consume the reviewed saved plan. Ordinary VM setup SHALL retain its tf=setup and xoa_login=1 labels, XO authentication, and existing backend paths. Secret values SHALL remain in injected variables. Real DNS credentials and Vault policy grants SHALL be prerequisites for operational DNS calls. RouterOS DNS credentials SHALL remain isolated from unrelated RouterOS resources. Successful scoped DNS execution SHALL not establish VM or service health. The package SHALL expose a format test that does not authenticate to Vault or contact DNS providers.

  • WHEN the package format test executes
  • THEN it checks the packaged Terraform configuration without live credentials
  • AND existing non-DNS authentication and backend paths remain unchanged
  • WHEN the scoped DNS wrapper selects dns=1
  • THEN it selects DNS credential injection through the owner AppRole and existing backend without starting XO login
  • AND the targeted plan and saved-plan apply cover DNS and its dependencies, without establishing VM or service health
  • AND disabled DNS resources do not imply offline provider configuration