feat(computer): add secure VPS parity and companion uptime

apps/docs/content/docs/computers/cloud-and-vps.mdx

@@ -6,7 +6,7 @@ icon: Cloud
 
 ## Box cloud computer
 
-Add a Box API key in App Settings to provision an isolated hosted Linux desktop. The computer can sleep and wake, and supported sessions provide a live viewer for temporary human control.
+Add a Box API key in App Settings to provision an isolated hosted Linux desktop. The computer can sleep and wake, and supported sessions provide a live viewer for temporary human control. Trial accounts automatically retry creation with the provider's shorter auto-stop ceiling when required.
 
 Box is a third-party paid service after its trial. OpenMausBot stores the configured credential locally and does not expose it to the renderer.
 
@@ -24,3 +24,7 @@ docker -H ssh://my-vps info
 The SSH user needs Docker access, which is root-equivalent on that server. Use a dedicated VPS and firewall inbound traffic to SSH only.
 
 The managed container publishes no ports, has no host mounts, and is checked before every attach. Its filesystem should be treated as disposable; move important results out before deleting or upgrading the container.
+
+**Take control** opens the VPS desktop inside OpenMausBot through a temporary SSH tunnel. noVNC remains on the container's private bridge network; only a random loopback port is opened on your computer, and the tunnel closes with the viewer.
+
+Auto reuses an already-ready VPS without changing its lifecycle. To let Auto create or wake this bot's managed container, enable **Start VPS automatically** for that bot. This permission is off by default. When neither the VPS nor a local fallback is available, OpenMausBot shows the exact VPS failure instead of silently omitting computer tools.

apps/docs/content/docs/mobile/ios-companion.mdx

@@ -12,7 +12,7 @@ The native iOS companion is a thin client. Your computer remains the only machin
 - List bots and rooms, read paged transcripts, send messages, and interrupt work
 - Answer approvals and questions, including narrow always-allow grants
 - Search, manage tasks, react, share, and navigate message versions
-- Follow resumable live updates and optionally view a bot's cloud computer
+- Follow resumable live updates and optionally view a bot's managed Box cloud computer. The loopback-only VPS SSH viewer currently opens in the desktop app.
 
 ## Pairing
 
@@ -27,6 +27,8 @@ The computer stores only a digest of the device token. Revoking the phone from d
 
 There is no hosted OpenMausBot relay. Bonjour does not cross Tailscale, so remote connections use manual address entry.
 
+Your computer must remain on, awake, and running OpenMausBot. In desktop Companion Settings, **Keep this computer awake** can prevent system sleep while Companion is enabled; it is off by default, allows the screen to turn off, and may use more battery. A sleeping or powered-off computer cannot be reached without a future hosted relay.
+
 ## Security boundary
 
 The companion sidecar uses a default-deny route allowlist. Provider keys, pairing administration, Local VM lifecycle, webhook secrets, team import/export, and internal peer-agent routes remain unreachable from the phone.

companion/src/proxy.ts

@@ -116,7 +116,13 @@ const sendJson = (res: ServerResponse, status: number, body: unknown): void => {
  * is the sidecar's credential and means nothing to the harness, and hop-by-hop
  * headers are by definition not ours to relay. */
 const forwardHeaders = (req: IncomingMessage): Record<string, string> => {
-  const out: Record<string, string> = { accept: String(req.headers.accept ?? "*/*") };
+  const out: Record<string, string> = {
+    accept: String(req.headers.accept ?? "*/*"),
+    // Lets a response whose URL is intentionally loopback-only (the VPS SSH
+    // viewer) fail before opening a tunnel a phone cannot reach. This header
+    // carries no authority; it only narrows behavior at the harness.
+    "x-openmausbot-companion": "1",
+  };
   const contentType = req.headers["content-type"];
   if (contentType) out["content-type"] = String(contentType);
   // Last-Event-ID is how a reconnecting client asks for the gap. Dropping it

companion/test/proxy-response.test.ts

@@ -24,6 +24,7 @@ let harness: Server;
 let sidecar: Server;
 let sidecarPort = 0;
 let cloudDesktopAccess = true;
+let companionMarker = "";
 /** What the stub harness answers with next. Set per test. */
 let respond: (res: ServerResponse) => void = (res) => res.end();
 
@@ -43,7 +44,10 @@ const device = async (path = "/api/bots", method = "GET"): Promise<{ status: num
 };
 
 beforeAll(async () => {
-  harness = createServer((_req, res) => respond(res));
+  harness = createServer((req, res) => {
+    companionMarker = String(req.headers["x-openmausbot-companion"] ?? "");
+    respond(res);
+  });
   const harnessPort = await listen(harness);
 
   sidecar = createServer(
@@ -82,6 +86,7 @@ describe("preparing a harness response for a device", () => {
     const { status, text } = await device("/api/bots/b1/computer/join", "POST");
     expect(status).toBe(200);
     expect(JSON.parse(text).joinUrl).toBe("https://desktop.example/session/fresh");
+    expect(companionMarker).toBe("1");
   });
 
   it("never forwards a body it could not scrub", async () => {

docs/byo-vps.md

@@ -3,18 +3,18 @@
 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.
+only surface exposed: OpenMausBot never opens a public port on the VPS, never stores your SSH key or
+passphrase, 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.
+- Explicit **Cloud** with the **Self-hosted VPS** backend provisions or starts the container. **Auto** reuses
+  a ready container by default; an off-by-default **Start VPS automatically** switch lets that bot prepare
+  or wake its managed container when needed.
+- Interactive **Take control** through a temporary SSH tunnel. The app binds noVNC only to a random
+  `127.0.0.1` port on your computer, closes the tunnel with the viewer, and never publishes VNC on the VPS.
 
 ## Prerequisites
 
@@ -66,7 +66,8 @@ 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.
+  use a container that publishes any — the check runs before every attach, not just at creation. Live view
+  reaches the container's private bridge address through SSH and is loopback-only on your computer.
 - **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
@@ -93,8 +94,10 @@ follows a Cua image upgrade, since a container pinned to an old image is refused
 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.
+A bot set to **Auto** is lifecycle-read-only by default. It attaches only when the container is already
+running and verified. If no local fallback exists, the turn now explains why the VPS was unavailable instead
+of silently running without a computer. Enable **Start VPS automatically** per bot to let Auto prepare or wake
+that bot's managed container; the switch is deliberately off by default.
 
 ## Troubleshooting
 

docs/ios-companion.md

@@ -18,12 +18,18 @@ The first version includes:
   state.
 - Approvals and questions, including narrow “always allow” grants.
 - Resumable SSE, streamed reply text, reconnect hydration, and an opt-in live
-  computer view.
+  Box computer view. The loopback-only VPS SSH viewer remains desktop-only.
 - Markdown rendering and Keychain storage for the device token.
 
 It is foreground-only. Push notifications, background delivery, voice, App
 Store release automation, and a hosted relay are not part of this version.
 
+The Mac must be running OpenMausBot and must not be asleep. Companion Settings
+offers an off-by-default **Keep this computer awake** switch that prevents
+system sleep while Companion is on; the display may still turn off. Without a
+hosted relay, a sleeping or powered-off Mac cannot receive phone requests or
+run its local routines.
+
 ## Runtime architecture
 
 ```text

electron/companion.mjs

@@ -54,25 +54,35 @@ const entryPoint = (resourcesPath) =>
 
 const settingsFile = () => path.join(app.getPath("userData"), "companion-settings.json");
 
-/** Whether the user left the companion on. Anything unreadable is "off" —
- * the flag opens a network listener, so it fails closed. */
-export function companionEnabledAtRest() {
+function companionSettings() {
   try {
-    return JSON.parse(fs.readFileSync(settingsFile(), "utf8"))?.enabled === true;
+    const parsed = JSON.parse(fs.readFileSync(settingsFile(), "utf8"));
+    return { enabled: parsed?.enabled === true, keepAwake: parsed?.keepAwake === true };
   } catch {
-    return false;
+    return { enabled: false, keepAwake: false };
   }
 }
 
+/** Whether the user left the companion on. Anything unreadable is "off" —
+ * the flag opens a network listener, so it fails closed. */
+export function companionEnabledAtRest() {
+  return companionSettings().enabled;
+}
+
+export function companionKeepAwakeAtRest() {
+  return companionSettings().keepAwake;
+}
+
 /** Remember the toggle's position. Written via temp-and-rename so a crash
  * mid-write cannot leave a truncated file; a failed write costs auto-start
  * on the next launch, never the toggle itself. */
-export function rememberCompanionEnabled(enabled) {
+function rememberCompanionSettings(patch) {
   const file = settingsFile();
   const temporary = `${file}.${process.pid}.tmp`;
   try {
+    const next = { ...companionSettings(), ...patch };
     fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(temporary, JSON.stringify({ enabled }, null, 2));
+    fs.writeFileSync(temporary, JSON.stringify(next, null, 2));
     fs.renameSync(temporary, file);
   } catch {
     try {
@@ -83,6 +93,15 @@ export function rememberCompanionEnabled(enabled) {
   }
 }
 
+
+export function rememberCompanionEnabled(enabled) {
+  rememberCompanionSettings({ enabled });
+}
+
+export function rememberCompanionKeepAwake(keepAwake) {
+  rememberCompanionSettings({ keepAwake });
+}
+
 /** Ask the sidecar's own control server, which is the same API the standalone
  * page uses. Short timeout: this is loopback, and a spinner in Settings that
  * never resolves is worse than an error. */
@@ -245,15 +264,18 @@ async function stop() {
 /** Everything the panel renders. Shaped so "off" is a complete answer rather
  * than an absence — the panel should never have to guess. */
 export async function companionState() {
+  const keepAwake = companionKeepAwakeAtRest();
   if (!proc) {
-    return { enabled: false, port: COMPANION_PORT, devices: [], pairing: null, ...(lastError ? { error: lastError } : {}) };
+    const state = { enabled: false, keepAwake, port: COMPANION_PORT, devices: [], pairing: null };
+    if (lastError) state.error = lastError;
+    return state;
   }
   try {
     const state = await control("GET", "/state");
-    return { enabled: true, ...state };
+    return { enabled: true, keepAwake, ...state };
   } catch {
     // running but unreachable: report it rather than claiming health
-    return { enabled: true, port: COMPANION_PORT, devices: [], pairing: null, error: "the companion is not responding" };
+    return { enabled: true, keepAwake, port: COMPANION_PORT, devices: [], pairing: null, error: "the companion is not responding" };
   }
 }
 

electron/main.mjs

@@ -1,4 +1,4 @@
-import { app, BrowserWindow, clipboard, desktopCapturer, dialog, ipcMain, Menu, nativeImage, safeStorage, screen, session, shell, systemPreferences, utilityProcess } from "electron";
+import { app, BrowserWindow, clipboard, desktopCapturer, dialog, ipcMain, Menu, nativeImage, powerSaveBlocker, safeStorage, screen, session, shell, systemPreferences, utilityProcess } from "electron";
 import { createRequire } from "node:module";
 import fs from "node:fs";
 import path from "node:path";
@@ -283,15 +283,29 @@ const LOG_DIR = app.getPath("logs");
 let logStream = null;
 import {
   companionEnabledAtRest,
+  companionKeepAwakeAtRest,
   companionPairing,
   companionCloudDesktopAccess,
   companionRevoke,
   companionState,
   rememberCompanionEnabled,
+  rememberCompanionKeepAwake,
   startCompanion,
   stopCompanion,
 } from "./companion.mjs";
 
+let companionPowerBlocker = null;
+
+function syncCompanionKeepAwake(companionEnabled, keepAwake) {
+  const shouldBlock = companionEnabled && keepAwake;
+  if (shouldBlock && companionPowerBlocker === null) {
+    companionPowerBlocker = powerSaveBlocker.start("prevent-app-suspension");
+  } else if (!shouldBlock && companionPowerBlocker !== null) {
+    if (powerSaveBlocker.isStarted(companionPowerBlocker)) powerSaveBlocker.stop(companionPowerBlocker);
+    companionPowerBlocker = null;
+  }
+}
+
 function slog(line) {
   try {
     if (!logStream) {
@@ -966,7 +980,13 @@ ipcMain.handle("skill-recorder:save", (_event, payload) => saveSkillRecording(pa
 // The renderer gets these five and nothing else: it can turn the companion
 // on and off, look at it, open or cancel a pairing window, and remove a
 // device. It cannot reach the sidecar's control port itself.
-ipcMain.handle("companion:state", () => companionState());
+ipcMain.handle("companion:state", async () => {
+  const state = await companionState();
+  // The panel polls this state, so a sidecar that exited on its own releases
+  // the blocker within one poll instead of keeping the computer awake forever.
+  syncCompanionKeepAwake(state.enabled && !state.error, state.keepAwake === true);
+  return state;
+});
 ipcMain.handle("companion:start", async () => {
   const state = await startCompanion({
     resourcesPath: process.resourcesPath,
@@ -977,12 +997,21 @@ ipcMain.handle("companion:start", async () => {
   // one would greet every launch with the same error for a toggle the panel
   // showed as off.
   if (state.enabled && !state.error) rememberCompanionEnabled(true);
+  syncCompanionKeepAwake(state.enabled && !state.error, state.keepAwake === true);
   return state;
 });
-ipcMain.handle("companion:stop", () => {
+ipcMain.handle("companion:stop", async () => {
   rememberCompanionEnabled(false);
+  syncCompanionKeepAwake(false, false);
   return stopCompanion();
 });
+ipcMain.handle("companion:keep-awake", async (_event, enabled) => {
+  const keepAwake = Boolean(enabled);
+  rememberCompanionKeepAwake(keepAwake);
+  const state = await companionState();
+  syncCompanionKeepAwake(state.enabled && !state.error, keepAwake);
+  return companionState();
+});
 ipcMain.handle("companion:pairing", (_event, open) => companionPairing(Boolean(open)));
 ipcMain.handle("companion:cloud-desktop", (_event, deviceId, allowed) =>
   companionCloudDesktopAccess(deviceId, Boolean(allowed)),
@@ -1169,7 +1198,9 @@ app.whenReady().then(async () => {
   // (the panel shows the error) rather than retrying; and it never delays
   // the window.
   if (serverReady && companionEnabledAtRest()) {
-    void startCompanion({ resourcesPath: process.resourcesPath, harnessPort: SERVER_PORT, log: slog });
+    void startCompanion({ resourcesPath: process.resourcesPath, harnessPort: SERVER_PORT, log: slog }).then((state) => {
+      syncCompanionKeepAwake(state.enabled && !state.error, companionKeepAwakeAtRest());
+    });
   }
   const win = createWindow();
   // Registration is optional network work. Start it only after the local
@@ -1225,6 +1256,7 @@ app.on("before-quit", (e) => {
   // the sidecar holds a socket that is reachable from off this machine —
   // it should not outlive the window by even a moment
   void stopCompanion();
+  syncCompanionKeepAwake(false, false);
   // a live dictation session runs its own helper child that holds the mic —
   // stop it here so quitting never orphans a recording process
   if (nativeActions.appleSpeech) stopSpeech();

electron/preload.cjs

@@ -27,6 +27,7 @@ contextBridge.exposeInMainWorld("ogb", {
     state: () => ipcRenderer.invoke("companion:state"),
     start: () => ipcRenderer.invoke("companion:start"),
     stop: () => ipcRenderer.invoke("companion:stop"),
+    keepAwake: (enabled) => ipcRenderer.invoke("companion:keep-awake", enabled),
     pairing: (open) => ipcRenderer.invoke("companion:pairing", open),
     cloudDesktop: (deviceId, allowed) => ipcRenderer.invoke("companion:cloud-desktop", deviceId, allowed),
     revoke: (deviceId) => ipcRenderer.invoke("companion:revoke", deviceId),