Skip to main content

​
Connect a Remote Docker host

Register a private Docker server, VPS, or cloud VM with Nora, deploy an OpenClaw agent to it over SSH, and verify the complete lifecycle path.
Remote Docker is Nora’s experimental bring-your-own-compute path. The Nora control plane stays on your existing installation while the selected agent containers run on a Docker machine that you own.
Remote Docker is available only on self-hosted Nora. Docker control traffic uses SSH, but the published agent runtime ports use plain HTTP and WebSocket traffic. Keep the Nora services and the remote host on the same trusted private network or encrypted overlay, and never expose the agent port range to the public internet.
For the complete trust model, workspace-sharing behavior, capacity limits, Hermes API path, backup semantics, and safe host-retirement procedure, use the Remote Docker backend reference.

​
Before you start

Prepare the following:
  • a self-hosted Nora control plane with a valid ENCRYPTION_KEY;
  • a Linux server or VM with a running Docker Engine and enough CPU, memory, disk, and image-cache capacity for the agents you plan to run;
  • a stable private hostname or IP address reachable from Nora’s backend-api, worker-provisioner, and, if you use managed backups, worker-backup services;
  • an SSH account that can manage Docker without an interactive password or sudo prompt;
  • a dedicated SSH private key when possible; and
  • remote-host outbound DNS and HTTPS access to the image registries, model providers, and integrations used by the agent.
Docker daemon access is normally root-equivalent. Use a dedicated host and SSH identity where practical, restrict the identity at the network layer, and protect the credential like an administrator secret.
Nora launches Linux container images. A Linux Docker host is the lowest-risk path. Docker Desktop, rootless Docker, macOS, Windows, and non-default Docker contexts are not part of a certified host matrix and require your own end-to-end validation.

​
1. Prove Docker access from the private network

From a machine with the same private route and firewall policy as the Nora services, verify that the intended SSH user reaches the intended Docker daemon without an interactive prompt:
If that command fails, fix SSH authentication or Docker permissions on the remote machine before registering it. Do not work around the failure by exposing an unauthenticated Docker TCP socket. Nora does not install or configure Docker, SSH, Tailscale, WireGuard, registry credentials, or host firewall rules for you.

​
2. Reserve a private agent port range

Remote OpenClaw agents publish their gateway and runtime ports on the registered machine. Remote Hermes uses published runtime and dashboard ports as well. Nora allocates each port independently per registered host from the configured Docker agent range. The default is 19000-19999. You can choose a smaller subrange, but both boundaries must remain inside that envelope:
Allow the configured subrange only from the Nora control-plane and worker addresses. Also allow the configured SSH port from those services. If the SSH address and the address used for agent traffic differ, both paths must be reachable.
Do not add remote-docker to ENABLED_BACKENDS. A registered and successfully tested host is injected dynamically as a concrete execution target such as remote:build-host.
Register each physical Docker daemon only once per Nora control plane. Port reservations are keyed by the registration’s remote:<id>, not by Docker daemon identity, so two registrations that point at the same daemon can reserve the same host port and collide. If separate Nora control planes must share one daemon, assign each control plane a non-overlapping published-port subrange.

​
3. Register the machine

  1. Sign in to Nora and open App -> Remote Hosts (/app/remote-hosts).
  2. Enter a distinctive Label. Nora derives the stable remote:<id> target from it.
  3. Enter the private SSH host, Port, and SSH user.
  4. Leave Gateway address empty when Nora should reach agent ports through the SSH hostname. Otherwise enter the private hostname or IP used for agent traffic. Do not include a scheme or port.
  5. Choose SSH private key or Password authentication. Private-key authentication is preferred.
  6. Select Register host.
Nora encrypts the private key, password, and key passphrase with ENCRYPTION_KEY before storing them. The API never returns the stored secret values. When you edit a host, leave a secret field blank to keep the current value.

​
4. Test and pin the SSH host key

Select Test on the registered host from a network where you can independently trust the endpoint. The first successful test:
  1. opens SSH from backend-api under a 10-second overall probe deadline;
  2. runs docker version --format '{{.Server.Version}}' as the registered user; and
  3. captures and pins the SSH host key presented by the server.
Every later Docker-over-SSH operation requires that stored pin, and Nora also treats a host without a trusted pin as unavailable for active use. A different host key fails closed.
Test is not a deployment smoke test. It does not ask worker-provisioner or worker-backup to connect, pull an image, create a container, allocate a port, check the gateway address, or wait for runtime readiness. Its successful result also has no expiry. Re-run it after SSH, Docker, VPN, firewall, address, credential, or host maintenance.
If an intentional host rebuild or SSH key rotation changes the key, verify the replacement out of band before using Reset SSH pin. Resetting the pin blocks active use until a new Test succeeds. Do not reset trust merely to dismiss an unexplained mismatch.

​
5. Deploy an agent

  1. Add a real model provider under Settings if you have not already done so.
  2. Open Deploy and choose OpenClaw.
  3. Under Execution Target, select the registered host by label and remote:<id>.
  4. Choose the Standard sandbox, configure the agent and resources, then deploy.
  5. Follow the deployment state until the agent reports ready.
The current dashboard lists Remote Docker targets for OpenClaw. The backend also contains an experimental Hermes path, but it currently uses the advanced deployment API rather than the Hermes picker. Follow the Hermes advanced API instructions, which require a session JWT for the deployment. Workspace API keys cannot create, duplicate, redeploy, or roll back Remote Docker placement.

​
6. Verify the full operator loop

Treat the first agent as disposable and verify more than the connection badge:
  • the deployment reaches running and readiness succeeds;
  • Chat, Logs, Terminal, and lifecycle actions work through Nora;
  • restart succeeds without changing the selected remote:<id> target;
  • the remote machine shows the expected Nora-managed container and published ports;
  • the configured agent port range is unreachable from untrusted networks;
  • provider and registry calls work from inside the remote workload;
  • backup and copy-restore succeed if you plan to rely on managed backups; and
  • a successful agent deletion removes the remote container and both Nora-managed volumes. If a volume cannot be removed, Nora reports cleanup failure and keeps the agent record so deletion can be retried after the Docker volume problem is corrected.
Watch the services that perform the actual work:
Inspect the remote Docker host independently:
For a production candidate, also validate credential rotation, host reboot recovery, capacity monitoring, backup restore, and planned host retirement. Remote Docker performs explicit placement; it does not automatically schedule across hosts, fail over, drain, migrate, or enforce aggregate host capacity. Before changing a registration’s Gateway address or Nora’s Docker agent port range, drain and replace its existing agents. Those agents retain their original endpoint and port reservations; a new Test validates only the edited host profile and does not migrate them. Keep the old private route and firewall rules until deletion of the old agents completes. Drain every agent from a user’s owned Remote Docker registrations before deleting that user from Admin. Nora rejects the account deletion while any non-deleted agent—including an agent owned by a workspace member—still references one of those hosts.

​
Troubleshooting fast path

For workspace sharing, grant revocation, cleanup after a missing SSH pin, disk behavior, backups, and the full symptom matrix, continue to the Remote Docker backend reference.