BYO VPS computer backend: integrate, harden, and document #118

companion/src/wire.ts

@@ -10,14 +10,23 @@
 // point this becomes a no-op rather than a lie, which is the right way for a
 // sidecar to depend on someone else's API: assume nothing, and be correct
 // either way.
+//
+// `sshAlias` is the same story with a different payload: the harness's config
+// status echoes the self-hosted VPS alias — a label naming one of the user's
+// servers — inside `vps`, on both GET /api/config and the `config` SSE frame.
+// The phone only ever renders configured-or-not, so it gets exactly that:
+// `{configured: true}` survives, the host label does not.
+
+/** Keys that are the harness's business, never a device's. */
+const WITHHELD_KEYS = new Set(["resumeCursors", "sshAlias"]);
 
-/** Recursively drop `resumeCursors`, wherever it appears. */
+/** Recursively drop the withheld keys, wherever they appear. */
 export function scrub<T>(value: T): T {
   if (Array.isArray(value)) return value.map(scrub) as unknown as T;
   if (value && typeof value === "object") {
     const out: Record<string, unknown> = {};
     for (const [key, inner] of Object.entries(value as Record<string, unknown>)) {
-      if (key === "resumeCursors") continue;
+      if (WITHHELD_KEYS.has(key)) continue;
       out[key] = scrub(inner);
     }
     return out as T;

companion/test/wire.test.ts

@@ -30,6 +30,21 @@ describe("scrub", () => {
     });
   });
 
+  it("withholds the VPS host label but keeps the configured signal", () => {
+    // GET /api/config and the `config` SSE frame echo the VPS SSH alias — a
+    // label naming one of the user's servers. The phone renders
+    // configured-or-not, so that is all it may receive.
+    const status = {
+      box: { configured: false },
+      vps: { configured: true, sshAlias: "prod-vps" },
+    };
+    const cleaned = scrub(status);
+
+    expect(JSON.stringify(cleaned)).not.toContain("sshAlias");
+    expect(JSON.stringify(cleaned)).not.toContain("prod-vps");
+    expect(cleaned).toEqual({ box: { configured: false }, vps: { configured: true } });
+  });
+
   it("leaves values it does not own alone", () => {
     expect(scrub(null)).toBe(null);
     expect(scrub(42)).toBe(42);

docs/byo-vps.md

@@ -0,0 +1,111 @@
+# Bring Your Own VPS
+
+OpenMausBot can turn a Linux server you already own into a bot's computer. The agent process stays on your
+machine; Docker's own SSH transport reaches the daemon on the VPS, and each bot gets one managed, hardened
+Cua container there — a Linux desktop it can see and control. SSH is the only credential involved and the
+only surface exposed: OpenMausBot never opens a port on the VPS, never stores a key or password, and never
+runs an agent remotely.
+
+## What works
+
+- A per-bot Linux desktop in a managed container on your VPS, driven through the official Cua tools.
+- Live screen preview in the Computer panel and in transcripts, same as a Box.
+- Explicit **Cloud** with the **Self-hosted VPS** backend provisions or starts the container; **Auto** only
+  reuses one that is already running and verified.
+
+Deliberately not offered: an interactive desktop tunnel. There is no "Open desktop" for a VPS bot — the
+container publishes no ports, so there is nothing to tunnel to, by design.
+
+## Prerequisites
+
+- **Locally:** a `docker` CLI, version 18.09 or newer (that is when `docker -H ssh://` shipped). The Docker
+  daemon does not need to run locally — only the CLI is used.
+- **On the VPS:** a running Docker daemon (`dockerd`) on x86_64 Linux.
+- **The SSH user** must be in the `docker` group on the VPS, so `docker info` works without sudo.
+
+Be clear-eyed about that last point: membership in the `docker` group is root-equivalent on that machine.
+Anyone who can talk to the daemon can mount the host filesystem into a container. Using this feature means
+trusting the VPS — and whoever else can reach its Docker daemon — completely. Give bots a dedicated server,
+not one that also holds things you would not hand to the agent.
+
+## The required SSH config alias
+
+OpenMausBot connects only through a named alias in your `~/.ssh/config` — you type the alias into
+App Settings → Connections, nothing else. The alias block is load-bearing, not a convenience: every bot
+action becomes a `docker exec` over SSH, and without multiplexing each one pays a full SSH handshake; without
+keepalives and a connect timeout, a VPS that drops off the network hangs the bot's turn instead of failing it.
+Set the block up like this:
+
+```
+Host my-vps
+  HostName 203.0.113.7
+  User deploy
+  IdentityFile ~/.ssh/id_ed25519
+  ControlMaster auto
+  ControlPath ~/.ssh/cm-%r@%h-%p
+  ControlPersist 60m
+  ServerAliveInterval 15
+  ServerAliveCountMax 3
+  ConnectTimeout 10
+```
+
+- `ControlMaster`/`ControlPath`/`ControlPersist` — every action is a docker-over-SSH exec; multiplexing turns
+  per-command connects into milliseconds over one persistent connection.
+- `ServerAliveInterval`/`ServerAliveCountMax`/`ConnectTimeout` — a dropped VPS must fail fast (under a
+  minute, and ten seconds to connect), not hang a turn waiting on a dead TCP session.
+
+**Host key first, by hand.** Connect once manually before pointing OpenMausBot at the alias:
+
+```sh
+ssh my-vps true
+```
+
+That puts the host key in `known_hosts` on your terms. The app never auto-accepts a host key — an alias whose
+host is unknown simply fails until you have done this once.
+
+## Security
+
+- **No public ports.** The managed container is created with no published ports, and OpenMausBot refuses to
+  use a container that publishes any — the check runs before every attach, not just at creation.
+- **Firewall the VPS to SSH only**, ideally from your IP. Nothing OpenMausBot does needs any other inbound
+  port open, so anything else open is pure attack surface.
+- **Nothing sensitive is stored.** The only thing OpenMausBot persists is the alias name itself
+  (`~/.openmausbot/config.json`); keys, passphrases, and agent state stay with SSH. The alias is also kept
+  off paired phones — the companion reports configured-or-not, never the name.
+- The container itself runs hardened: capabilities dropped, private network/IPC/cgroup namespaces, no host
+  mounts, and memory/CPU/pid limits. A container missing any of that — including one someone created under
+  the managed name — is refused, not repaired.
+
+## Container lifecycle
+
+Each bot owns one container on the VPS, named `openmausbot-vps-<bot>-<hash>` — stable across restarts and
+independent of the bot's display name.
+
+- **Provision** (choosing **Cloud** for the bot, or the panel's button): builds the pinned Cua image on the
+  VPS if needed, creates the container if missing, starts it if stopped, and waits until the desktop answers.
+- **Start** only wakes an existing stopped container; it never creates one.
+- **Sleep** stops the container. The VPS stops spending CPU on it; the filesystem stays put.
+- **Remove** is yours, done by hand when a bot no longer needs the server:
+  `docker -H ssh://my-vps rm -f <container>`. OpenMausBot never deletes a container on its own.
+
+What survives what: sleep/start preserves the container's filesystem; removal — including the recreate that
+follows a Cua image upgrade, since a container pinned to an old image is refused rather than reused — wipes
+it. Treat the container filesystem as **disposable**: anything a bot must keep should leave the VPS (pushed,
+uploaded, or pasted back into chat) before the container is removed.
+
+A bot set to **Auto** never touches this lifecycle. It attaches only when the container is already running
+and verified; otherwise it behaves as if no cloud computer existed.
+
+## Troubleshooting
+
+Work up the same path the app takes, cheapest signal first:
+
+1. **The alias works by hand:** `ssh my-vps true` returns silently. A password prompt means the key/agent is
+   not set up; a host-key prompt means the first manual connect has not happened yet.
+2. **Docker over SSH reaches the daemon:** `docker -H ssh://my-vps info` prints server details. A permission
+   error means the SSH user is not in the `docker` group.
+3. **Provision:** choose **Cloud** with the **Self-hosted VPS** backend in the bot's Computer panel. The
+   first provision pulls and builds the Cua image on the VPS, which can take minutes; later ones are fast.
+4. **Read the status states.** The panel surfaces exactly what the server found, in check order: alias not
+   configured → daemon unreachable → image missing → container missing / stopped → container unmanaged or
+   unsafe (ports, mounts, hardening) → desktop not ready. Each message names the step to fix.

docs/linux-desktop.md

@@ -1,7 +1,8 @@
 # Ubuntu Desktop
 
 OpenMausBot has an Ubuntu 24.04 LTS x86_64 desktop beta. The Electron package embeds the harness server, so
-installed builds do not require Node, pnpm, Swift, or a terminal at runtime.
+installed builds do not require Node, pnpm, Swift, or a terminal at runtime. For giving a bot the same kind
+of Linux desktop on your own server instead of this machine, see [byo-vps.md](byo-vps.md).
 
 ## What works
 

ios/App/ComputerView.swift

@@ -61,7 +61,10 @@ struct ComputerView: View {
             }
         }
         .safeAreaInset(edge: .bottom) {
-            if current.computer == "cloud" {
+            // A VPS-backed bot is "cloud" too, but the server refuses to mint
+            // an interactive desktop for it — no button beats a dead one. An
+            // older harness never sends cloudBackend, so nil keeps the button.
+            if current.computer == "cloud" && current.cloudBackend != "vps" {
                 VStack(spacing: 8) {
                     if let desktopError {
                         Text(desktopError)

ios/Sources/CompanionCore/Models.swift

@@ -153,6 +153,10 @@ public struct Bot: Codable, Hashable, Identifiable, Sendable {
     public var autoApprove: Bool?
     public var alwaysAllow: [String]?
     public var computer: String?
+    /// Which cloud computer backs `computer == "cloud"`. Absent (older
+    /// harnesses included) means the hosted Box; "vps" means the user's own
+    /// server, which has no interactive desktop to offer a phone.
+    public var cloudBackend: String?
     public var speakReplies: Bool?
     public var voice: String?
     public var mascotExpression: String?

ios/Tests/CompanionCoreTests/DecodingTests.swift

@@ -56,6 +56,34 @@ final class DecodingTests: XCTestCase {
         XCTAssertNil(fleet.bots.first?.hasMore)
     }
 
+    func testDecodesTheCloudBackendAndItsAbsence() throws {
+        // The cloud-desktop button hides on cloudBackend == "vps", so both
+        // sides of that gate must decode: a harness that sends the field, and
+        // an older one that has never heard of it (nil keeps the button).
+        let json = """
+        {
+          "bots": [
+            {
+              "id":"b1","threadId":"t1","name":"Scout","title":"","description":"",
+              "notifications":true,"color":"green","unread":false,
+              "modelSelection":{"instanceId":"i1","model":"m1"},"createdAt":1,
+              "computer":"cloud","cloudBackend":"vps"
+            },
+            {
+              "id":"b2","threadId":"t2","name":"Rio","title":"","description":"",
+              "notifications":true,"color":"blue","unread":false,
+              "modelSelection":{"instanceId":"i1","model":"m1"},"createdAt":2,
+              "computer":"cloud"
+            }
+          ],
+          "groups": []
+        }
+        """
+        let fleet = try JSONDecoder().decode(Fleet.self, from: Data(json.utf8))
+        XCTAssertEqual(fleet.bots.first?.cloudBackend, "vps")
+        XCTAssertNil(fleet.bots.last?.cloudBackend)
+    }
+
     func testOneMalformedBotDoesNotHideTheRestOfTheFleet() throws {
         let json = """
         {

scripts/bundle-server.mjs

@@ -29,6 +29,7 @@ const ENTRY_POINTS = [
   "index.ts",
   "computer-proxy.ts",
   "container-mcp.ts",
+  "vps-container-mcp.ts",
   "permission-proxy.ts",
   "connector-proxy.ts",
   "drivers/agents-proxy.ts",

server/branching.test.ts

@@ -187,6 +187,12 @@ posixOnly("conversation branching e2e (fake ACP fleet)", () => {
       expect((await api("POST", `/api/bots/${created.id}/messages`, { text: "first try" })).status).toBe(202);
       await waitFor(async () => (await getBot(created.id)).busy === true, "the hung turn to start");
 
+      const backendBefore = (await getBot(created.id)).cloudBackend;
+      const backendChange = await api("PATCH", `/api/bots/${created.id}`, { cloudBackend: "vps" });
+      expect(backendChange.status).toBe(409);
+      expect(backendChange.body.error).toContain("stop the active turn");
+      expect((await getBot(created.id)).cloudBackend).toBe(backendBefore);
+
       // a second send while busy queues (steer-queue) — never a parallel
       // turn: the words land in the transcript, the live turn keeps running
       const parallel = await api("POST", `/api/bots/${created.id}/messages`, { text: "sneaky second" });

server/cloud-backend.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  CLOUD_BACKEND_CHANGE_ERROR,
+  VPS_ALIAS_CHANGE_ERROR,
+  cloudBackendChangeError,
+  vpsAliasChangeError,
+} from "./cloud-backend.ts";
+
+describe("cloud backend switching", () => {
+  const activeTurnCases: Array<[string, boolean, boolean]> = [
+    ["a busy bot", true, false],
+    ["an active VPS thread", false, true],
+  ];
+
+  it.each(activeTurnCases)("rejects changes during %s", (_reason, busy, activeVpsThread) => {
+    expect(cloudBackendChangeError(busy, activeVpsThread)).toBe(CLOUD_BACKEND_CHANGE_ERROR);
+  });
+
+  it("allows changes while idle", () => {
+    expect(cloudBackendChangeError(false, false)).toBeNull();
+  });
+
+  it("keeps an active VPS turn on its original SSH host", () => {
+    expect(vpsAliasChangeError("old-vps", "new-vps", true)).toBe(VPS_ALIAS_CHANGE_ERROR);
+    expect(vpsAliasChangeError("old-vps", "old-vps", true)).toBeNull();
+    expect(vpsAliasChangeError("old-vps", "new-vps", false)).toBeNull();
+  });
+});

server/cloud-backend.ts

@@ -0,0 +1,10 @@
+export const CLOUD_BACKEND_CHANGE_ERROR = "stop the active turn before changing the cloud backend";
+export const VPS_ALIAS_CHANGE_ERROR = "stop the active VPS turn before changing the SSH config alias";
+
+export function cloudBackendChangeError(botBusy: boolean, activeVpsThread: boolean): string | null {
+  return botBusy || activeVpsThread ? CLOUD_BACKEND_CHANGE_ERROR : null;
+}
+
+export function vpsAliasChangeError(currentAlias: string | null, nextAlias: string | null, activeVpsThread: boolean): string | null {
+  return activeVpsThread && currentAlias !== nextAlias ? VPS_ALIAS_CHANGE_ERROR : null;
+}

server/config.test.ts

@@ -2,8 +2,10 @@ import { describe, expect, it } from "vitest";
 
 import {
   instanceConfigs,
+  isValidSshAlias,
   parseConfigPatch,
   parseStoredConfig,
+  vpsSshAlias,
   withInstanceCli,
   type AppConfig,
 } from "./config.ts";
@@ -27,6 +29,17 @@ describe("configuration boundaries", () => {
     expect(() => parseConfigPatch({ opencodeGo: { apiKey: 42 } })).toThrow("opencodeGo.apiKey");
     expect(() => parseConfigPatch({ profile: [] })).toThrow("profile");
   });
+
+  it("accepts only a simple VPS SSH config alias and exposes no credentials", () => {
+    expect(isValidSshAlias("production-vps")).toBe(true);
+    expect(isValidSshAlias("prod; reboot")).toBe(false);
+    expect(() => parseConfigPatch({ vps: { sshAlias: "prod; reboot" } })).toThrow("vps.sshAlias");
+    expect(parseConfigPatch({ vps: { sshAlias: "production-vps" } })).toEqual({
+      vps: { sshAlias: "production-vps" },
+    });
+    expect(vpsSshAlias({ vps: { sshAlias: "production-vps" } })).toBe("production-vps");
+    expect(vpsSshAlias({ vps: { sshAlias: "-bad" } })).toBeNull();
+  });
 });
 
 describe("default fleet", () => {

server/config.ts

@@ -11,6 +11,31 @@ import type { InstanceConfigMap } from "./contracts.ts";
 import { parseJson, schemaIssue, type JsonObject, type JsonValue } from "./schema.ts";
 
 const optionalText = z.string().optional();
+const SSH_ALIAS = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
+
+export function isValidSshAlias(value: unknown): value is string {
+  return typeof value === "string" && SSH_ALIAS.test(value);
+}
+
+/** Keep the persisted VPS shape deliberately smaller than an SSH connection. */
+export function normalizeVpsConfig(raw: unknown): { sshAlias?: string } {
+  if (raw === undefined || raw === null) return {};
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("vps must be an object containing an SSH config alias");
+  }
+  const alias = (raw as Record<string, unknown>).sshAlias;
+  if (alias === undefined || alias === "") return {};
+  if (!isValidSshAlias(alias)) {
+    throw new Error("vps.sshAlias must be a simple SSH config alias (letters, numbers, dot, dash, or underscore)");
+  }
+  return { sshAlias: alias };
+}
+
+const vpsConfigSchema = z.object({
+  sshAlias: z.string().refine((value) => value === "" || isValidSshAlias(value), {
+    message: "must be a simple SSH config alias",
+  }).optional(),
+});
 const instanceConfigSchema = z.object({
   driver: z.string().min(1),
   displayName: optionalText,
@@ -26,6 +51,7 @@ const appConfigSchema = z.object({
    * are non-secret local identifiers used to reuse one Composio Session. */
   composio: z.object({ apiKey: optionalText, userId: optionalText, sessionId: optionalText }).optional(),
   box: z.object({ token: optionalText }).optional(),
+  vps: vpsConfigSchema.optional(),
   /** OpenCode Go key; persisted write-only and passed only to its child. */
   opencodeGo: z.object({ apiKey: optionalText }).optional(),
   /** Voice credentials and the selected voice id. */
@@ -41,6 +67,8 @@ export interface AppConfig {
   xai?: { key?: string; url?: string };
   composio?: { apiKey?: string; userId?: string; sessionId?: string };
   box?: { token?: string };
+  /** A named host from the user's SSH config. Authentication stays with SSH. */
+  vps?: { sshAlias?: string };
   opencodeGo?: { apiKey?: string };
   tts?: { key?: string; voice?: string };
   profile?: { name?: string; email?: string };
@@ -62,6 +90,10 @@ export function parseConfigPatch(value: JsonValue): ConfigPatch {
   return parsed.data;
 }
 
+export function vpsSshAlias(cfg: AppConfig): string | null {
+  return isValidSshAlias(cfg.vps?.sshAlias) ? cfg.vps.sshAlias : null;
+}
+
 // OMB_DATA_DIR isolates test/soak rigs from the user's real fleet.
 export const DATA_DIR = process.env.OMB_DATA_DIR ?? join(homedir(), ".openmausbot");
 const LEGACY_DATA_DIR = join(homedir(), ".opengrokbot");
@@ -117,6 +149,7 @@ export function saveConfig(patch: Partial<AppConfig>): void {
     Object.assign(merged, section);
     disk[key] = merged;
   }
+  if (checkedPatch.vps !== undefined) disk.vps = normalizeVpsConfig(checkedPatch.vps);
   if (checkedPatch.instances) {
     const currentInstances = jsonObjectSchema.safeParse(disk.instances);
     const diskInstances: JsonObject = currentInstances.success ? currentInstances.data : {};