@tsconfigdotjson/vibe-os 0.1.0 → 0.2.0

package/README.md

@@ -46,6 +46,7 @@ edit, no `sshd_config` change, and no root.
 - [Deploying on a VPS](#deploying-on-a-vps)
   - [What the box needs](#what-the-box-needs)
   - [Install](#install)
+  - [Setup](#setup)
   - [Behind Tailscale](#behind-tailscale)
   - [Firewall](#firewall)
   - [Running it as a service](#running-it-as-a-service)
@@ -55,6 +56,8 @@ edit, no `sshd_config` change, and no root.
 - [Security](#security)
 - [CLI reference](#cli-reference)
 - [Development](#development)
+  - [Building from source](#building-from-source)
+  - [Releasing](#releasing)
 - [Project status](#project-status)
 - [Contributing](#contributing)
 - [License](#license)
@@ -66,50 +69,31 @@ edit, no `sshd_config` change, and no root.
 ### Try it locally
 
 ```bash
-docker compose up --build
+docker run --rm -p 127.0.0.1:8080:80 -e VIBE_OS_NO_TOKEN=1 ghcr.io/tsconfigdotjson/vibe-os
 open http://localhost:8080
 ```
 
-A blank Debian box with sshd, dtach and git, which is the same shape as a fresh
-VPS. The compose file turns the token off so the URL above just works, and
-publishes the port on loopback only, because a vibe-os with no token is a shell
-for anyone who can reach it.
-
-### Or point an agent at a VPS
-
-You have an agent. Give it SSH access to a fresh box and this:
-
-> Set up vibe-os (https://github.com/tsconfigdotjson/vibe-os) on this VPS.
->
-> 1. Create a non-root user with sudo if I am logged in as root, and do the rest
->    as that user. vibe-os hands out shells as whoever runs it.
-> 2. Install the prerequisites: `openssh-server`, `openssh-client`, `dtach`,
->    `git`, and `gh`. Install Claude Code with the standalone installer from
->    https://claude.ai/install.sh, not npm.
-> 3. Install Tailscale, run `tailscale up`, and tell me the tailnet address.
-> 4. Build the binary. If you have Bun locally, `bun run compile` and copy
->    `dist/bin/vibe-os-linux-x64` to `/usr/local/bin/vibe-os`. Otherwise clone
->    the repo on the box, install Bun, and run `bun install && bun run build`.
-> 5. Run `vibe-os doctor` and then `sudo vibe-os doctor`. Fix what they report
->    before continuing. Do not skip this.
-> 6. Install the service: `sudo vibe-os install-service --port 7681 --host
->    127.0.0.1 --token`. Run that with sudo from the user account, not as root.
-> 7. Put HTTPS in front: `sudo tailscale serve --bg 7681`.
-> 8. Close the box down with ufw: allow in on `tailscale0`, allow `41641/udp`,
->    default deny incoming, then enable. Confirm you can still reach the box
->    over the tailnet in a second session before enabling it.
-> 9. Turn off SSH password authentication by writing
->    `PasswordAuthentication no` to `/etc/ssh/sshd_config.d/01-hardening.conf`.
->    That file has to sort before `50-cloud-init.conf`, which sets it to yes.
->    Run `sshd -t` before reloading.
-> 10. Run `sudo vibe-os doctor` one more time and paste the output, along with
->     the URL and token from `journalctl -u vibe-os`.
->
-> Tell me what you are about to run before you run anything that opens a port
-> or changes sshd.
-
-Read what it proposes before you let it run. Step 8 can lock you out of the box
-if the tailnet is not actually working yet.
+A blank Debian box with sshd, dtach and git, the same shape as a fresh VPS. The
+token is off, so the port is on loopback only: a vibe-os with no token is a
+shell for anyone who can reach it. The image has no harness, so profiles open a
+shell; from a clone, `docker compose up --build` adds Claude Code.
+
+### Or set up a VPS
+
+On a fresh Debian or Ubuntu box, as any user with sudo (or as root, which
+creates one):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/tsconfigdotjson/vibe-os/main/install.sh | sh
+vibe-os setup
+```
+
+`setup` runs the same checks as `doctor` and offers to fix each one, printing
+every command before it runs it. See [Setup](#setup) for what it does.
+
+For an agent with SSH access to the box, the prompt is one line:
+
+> Install vibe-os with `curl -fsSL https://raw.githubusercontent.com/tsconfigdotjson/vibe-os/main/install.sh | sh`, then run `vibe-os setup --yes` and show me its output.
 
 ---
 
@@ -418,11 +402,14 @@ invocation, so without it a profile opens a shell and does nothing else.
 ### Install
 
 ```bash
-bun run compile              # writes dist/bin/vibe-os-linux-{x64,arm64}
-scp dist/bin/vibe-os-linux-x64 you@host:/usr/local/bin/vibe-os
-ssh you@host 'chmod +x /usr/local/bin/vibe-os'
+curl -fsSL https://raw.githubusercontent.com/tsconfigdotjson/vibe-os/main/install.sh | sh
 ```
 
+It installs the latest [release](https://github.com/tsconfigdotjson/vibe-os/releases)
+for Linux x64, Linux arm64 or Apple Silicon to `/usr/local/bin` (or
+`~/.local/bin` without sudo), after checking its SHA-256. Set `VIBE_OS_VERSION`
+to pin a tag, or `VIBE_OS_INSTALL_DIR` to choose the directory.
+
 The binary carries the whole app, including the 20MB SSH WASM runtime. No Bun,
 Node or npm on the target.
 
@@ -446,6 +433,53 @@ sudo vibe-os doctor     # adds the sshd and firewall checks
 `doctor` evaluates the flags it is given and cannot see a systemd unit, so pass
 the same flags the service uses to get a true answer.
 
+### Setup
+
+```bash
+vibe-os setup
+```
+
+Each step checks first and skips itself when there is nothing to do, so running
+it again on a configured box changes nothing. In order:
+
+1. **User.** As root, it offers to create a user with passwordless sudo and
+   root's SSH keys, then stops so you can log in as them and run it again.
+2. **Prerequisites.** `openssh-server`, `openssh-client`, `dtach`, `git`,
+   `curl` and optionally `gh`, through apt, dnf, yum, pacman or zypper.
+3. **sshd**, enabled and started if nothing answers on port 22.
+4. **Harnesses.** Claude Code, then optionally Hermes and Cursor.
+5. **Tailscale**, installed and brought up (it prints a login URL).
+6. **The service**, on `127.0.0.1:7681` with a generated token kept in
+   `~/.vibe-os/config.json`. An installed unit is left alone unless you pass a
+   different `--port` or `--host`.
+7. **`tailscale serve --bg 7681`**, for HTTPS on the tailnet.
+8. **SSH hardening.** Writes `01-hardening.conf` to turn off password logins,
+   runs `sshd -t` and reloads. Skipped if your user has no SSH key yet.
+9. **Firewall**, with ufw: allow the tailnet and `41641/udp`, deny the rest.
+10. **`doctor`**, run with sudo, then the URL with `?token=`.
+
+The firewall step can lock you out, so before enabling ufw it arms a systemd
+timer that disables it again in five minutes. Setup then waits for you to
+confirm from a **new** session over the tailnet:
+
+```bash
+ssh <user>@<machine>.<tailnet>.ts.net vibe-os confirm-firewall
+```
+
+If that never arrives, ufw turns itself off. Your provider's firewall is
+separate; leave `41641/udp` open there.
+
+| flag | |
+| --- | --- |
+| `-y`, `--yes` | take the default answer to every question |
+| `--firewall` | with `--yes`, do the firewall step too (it is skipped otherwise) |
+| `--hermes`, `--cursor` | install those harnesses too |
+| `--user <name>` | as root, the user to create |
+| `--port`, `--host` | where the service listens (default `7681`, `127.0.0.1`) |
+
+With `--yes`, an agent runs the firewall confirmation from a second SSH
+connection while setup waits in the first.
+
 ### Behind Tailscale
 
 The recommended setup. You stop needing to bind port 80, and you stop needing
@@ -681,12 +715,8 @@ accept that `gh` will not work.
 ### Updating a running box
 
 ```bash
-bun run build && bun scripts/compile.ts linux-x64
-scp dist/bin/vibe-os-linux-x64 you@host:/tmp/vibe-os
-ssh you@host 'sudo systemctl stop vibe-os \
-  && sudo mv /tmp/vibe-os /usr/local/bin/vibe-os \
-  && sudo chmod +x /usr/local/bin/vibe-os \
-  && sudo systemctl start vibe-os'
+curl -fsSL https://raw.githubusercontent.com/tsconfigdotjson/vibe-os/main/install.sh | sh
+sudo systemctl restart vibe-os
 ```
 
 Nothing is lost by that restart. Two things it does not pick up:
@@ -758,6 +788,8 @@ in a session could otherwise ask what you last copied.
 | `vibe-os` / `vibe-os start` | serve the UI and the SSH bridge |
 | `vibe-os attach [window]` | attach this terminal to a window's session |
 | `vibe-os doctor` | check this machine is ready, and say what is missing |
+| `vibe-os setup` | fix what `doctor` finds, asking before each change |
+| `vibe-os confirm-firewall` | tell a waiting `setup` the tailnet still gets in |
 | `sudo vibe-os install-service` | write and enable a systemd unit |
 | `sudo vibe-os install-browser` | run one Chrome on a virtual display |
 | `vibe-os connect-hermes` | point Hermes' browser tools at that Chrome |
@@ -810,6 +842,9 @@ in a session could otherwise ask what you last copied.
 --no-vnc-password   serve the display with no authentication
 ```
 
+`setup` takes the [flags above](#setup) as well as `--port`, `--host`,
+`--workspace` and `--state-dir`, which it passes to the service.
+
 `connect-hermes` takes one:
 
 ```
@@ -854,6 +889,32 @@ step of its own.
 its SHA-256 verified before extraction. To move it, set `SSHTERM_VERSION`, run
 `bun run fetch-wasm`, and copy the checksum it prints into `PINNED`.
 
+### Building from source
+
+```bash
+bun install && bun run build
+bun scripts/compile.ts linux-x64     # or linux-arm64, darwin-arm64; none for all
+scp dist/bin/vibe-os-linux-x64 you@host:/tmp/vibe-os
+ssh you@host 'sudo install -m 0755 /tmp/vibe-os /usr/local/bin/vibe-os'
+```
+
+### Releasing
+
+Bump `version` in `package.json`, merge, then tag the merge commit:
+
+```bash
+git tag v0.2.0 && git push origin v0.2.0
+```
+
+The tag must match `package.json`. The workflow publishes the binaries with
+`SHA256SUMS` as a GitHub Release, pushes `ghcr.io/tsconfigdotjson/vibe-os`, and
+publishes `@tsconfigdotjson/vibe-os` to npm with provenance, through npm's
+[trusted publishing](https://docs.npmjs.com/trusted-publishers). A hyphenated
+tag such as `v0.2.0-rc.1` is a prerelease: the installer skips it, and npm gets
+it under the `next` dist-tag rather than `latest`.
+
+### Icons
+
 App icons are generated from `public/icon.svg`:
 
 ```bash
@@ -867,8 +928,7 @@ rsvg-convert -w 512 -h 512 public/icon-maskable.svg -o public/icon-maskable-512.
 
 ## Project status
 
-Usable and in daily use, but young. No release binaries are published yet, so
-build one or run the container.
+Usable and in daily use, but young.
 
 Everything in [Deploying on a VPS](#deploying-on-a-vps) has been walked end to
 end on a fresh OVHcloud VPS on Ubuntu 26.04, behind Tailscale, serving HTTPS.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tsconfigdotjson/vibe-os",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A coding desktop in the browser, on a box you own. Git worktrees per piece of work, terminals that survive a reload, and SSH that runs in the tab.",
   "type": "module",
   "license": "MIT",

package/server/assets.generated.ts

@@ -26,7 +26,7 @@ import a18 from "../dist/web/wasm_exec.js" with { type: 'file' };
 import a19 from "../dist/web/wasm_exec.js.br" with { type: 'file' };
 import a20 from "../dist/web/wasm_exec.js.gz" with { type: 'file' };
 
-export const BUILD_ID = "754753f62b6b";
+export const BUILD_ID = "4784e0916592";
 
 export const EMBEDDED: Record<string, string> = {
   "/apple-touch-icon.png": a0,

package/server/cli.ts

@@ -43,6 +43,7 @@ import { startServer } from "./index.ts";
 import { color, describeError, log } from "./log.ts";
 import { reapLeaks } from "./reaper.ts";
 import { ENTRY, FETCH_WASM, IS_COMPILED } from "./runtime.ts";
+import { confirmFirewall, runSetup } from "./setup.ts";
 
 const run = promisify(execFile);
 const BUN = process.execPath;
@@ -56,6 +57,7 @@ const HELP = `
     vibe-os [start]              serve the UI and the SSH bridge
     vibe-os attach [window]      attach a real terminal to a window's session
     vibe-os doctor               check this machine is ready
+    vibe-os setup                fix what doctor finds, asking first
     vibe-os install-service      write and enable a systemd unit (needs root)
     vibe-os install-browser      run one Chrome on a virtual display (needs root)
     vibe-os connect-hermes       point Hermes' browser tools at that Chrome
@@ -113,6 +115,14 @@ const HELP = `
 
   ${color.bold("doctor")}
     --reap              kill processes that outlived their workspace or session
+
+  ${color.bold("setup")}
+    -y, --yes           take the default answer to every question
+    --firewall          close the box to all but the tailnet with ufw; needed
+                        with --yes, which otherwise leaves the firewall alone
+    --hermes            install Hermes too (asked otherwise, default no)
+    --cursor            install Cursor too (asked otherwise, default no)
+    --user <name>       as root: the user to create and run vibe-os as
 `;
 
 function version(): string {
@@ -810,6 +820,10 @@ export async function main(argv: string[]): Promise<number> {
       if (values.reap) await reapLeaks(config);
       return printChecks(await runDoctor(config));
     }
+    case "setup":
+      return runSetup(config, values);
+    case "confirm-firewall":
+      return confirmFirewall(config);
     case "install-service":
       return installService(config, argv);
     case "install-browser":

package/server/config.ts

@@ -93,6 +93,11 @@ export const OPTION_SPEC = {
   // doctor only, same reasoning as the install-browser block below: parseArgs
   // is strict, so a flag it has never heard of is an error.
   reap: { type: "boolean" as const },
+  // setup only, for the same reason.
+  yes: { type: "boolean" as const, short: "y" },
+  firewall: { type: "boolean" as const },
+  hermes: { type: "boolean" as const },
+  cursor: { type: "boolean" as const },
   // install-browser only. Kept here because parseArgs is strict, and a flag it
   // has never heard of is an error rather than something a subcommand can read.
   geometry: { type: "string" as const },
@@ -151,6 +156,24 @@ export function parseCliArgs(argv: string[]): {
   return { values: values as RawOptions, positionals };
 }
 
+/**
+ * The user this process runs as.
+ *
+ * Bun's `os.userInfo().username` comes from `$USER`, and reads "unknown" when
+ * that is unset, which `docker exec`, cron and some `su` invocations all do.
+ * `id` asks the passwd database for the real uid instead.
+ */
+async function currentUser(): Promise<string> {
+  const name = os.userInfo().username;
+  if (name && name !== "unknown") return name;
+  try {
+    const { stdout } = await run("id", ["-un"], { timeout: 5_000 });
+    return stdout.trim() || name;
+  } catch {
+    return name;
+  }
+}
+
 async function hasDtach(): Promise<boolean> {
   try {
     // dtach exits non-zero with no mode, so its usage text is the liveness
@@ -334,7 +357,7 @@ export async function resolveConfig(values: RawOptions): Promise<Config> {
       process.env.VIBE_OS_SSH_ADVERTISE ??
       undefined,
     user: userName(
-      values.user ?? process.env.VIBE_OS_USER ?? os.userInfo().username,
+      values.user ?? process.env.VIBE_OS_USER ?? (await currentUser()),
       "user",
     ),
     stateDir,

package/server/doctor.ts

@@ -26,6 +26,7 @@ import {
 } from "./browser.ts";
 import type { Config } from "./config.ts";
 import {
+  CLAUDE_INSTALL,
   CURSOR_INSTALL,
   discoverCursor,
   discoverHermes,
@@ -161,7 +162,7 @@ const fatal = (label: string, detail: string, fix?: string): Check => ({
   fatal: true,
 });
 
-function probeTcp(
+export function probeTcp(
   host: string,
   port: number,
   timeout = 2000,
@@ -473,6 +474,25 @@ export async function homeFor(user: string): Promise<string | null> {
   }
 }
 
+/**
+ * `sshd -T` output as a map.
+ *
+ * sshd -T lowercases keywords and prints repeated ones on their own lines;
+ * joining preserves multi-value keywords like allowusers.
+ */
+export function parseSshdConfig(stdout: string): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const line of stdout.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const space = trimmed.indexOf(" ");
+    const key = space === -1 ? trimmed : trimmed.slice(0, space);
+    const value = space === -1 ? "" : trimmed.slice(space + 1);
+    map.set(key, map.has(key) ? `${map.get(key)} ${value}` : value);
+  }
+  return map;
+}
+
 /**
  * sshd's effective configuration, evaluated for the user who will log in.
  *
@@ -491,18 +511,7 @@ async function sshdEffectiveConfig(
         ["-T", "-C", `user=${user},host=localhost,addr=127.0.0.1`],
         { timeout: 10_000, maxBuffer: 4 * 1024 * 1024 },
       );
-      const map = new Map<string, string>();
-      for (const line of stdout.split("\n")) {
-        const trimmed = line.trim();
-        if (!trimmed) continue;
-        const space = trimmed.indexOf(" ");
-        // sshd -T lowercases keywords and prints repeated ones on their own
-        // lines; joining preserves multi-value keywords like allowusers.
-        const key = space === -1 ? trimmed : trimmed.slice(0, space);
-        const value = space === -1 ? "" : trimmed.slice(space + 1);
-        map.set(key, map.has(key) ? `${map.get(key)} ${value}` : value);
-      }
-      return map;
+      return parseSshdConfig(stdout);
     } catch {
       // not this path, or not root — try the next
     }
@@ -641,7 +650,7 @@ export async function runDoctor(config: Config): Promise<Check[]> {
       : bad(
           "claude",
           "not on PATH — profiles using the Claude harness fall back to a shell",
-          "curl -fsSL https://claude.ai/install.sh | bash",
+          CLAUDE_INSTALL,
         ),
   );
 
@@ -671,8 +680,10 @@ export async function runDoctor(config: Config): Promise<Check[]> {
     );
   } else {
     const mine = os.homedir();
+    // Root is checking on someone's behalf (`sudo vibe-os doctor`, or the end
+    // of setup), not running the server, so where its own home is says nothing.
     checks.push(
-      home === mine
+      home === mine || process.getuid?.() === 0
         ? ok("login user", `${user} (${home})`)
         : bad(
             "login user",

package/server/harness.ts

@@ -110,6 +110,7 @@ const UVX_PATHS = [`${home}/.local/bin/uvx`, "/usr/local/bin/uvx"];
  * one when there is nothing to configure. Both used to be about to grow their
  * own copy of a URL that has to be right.
  */
+export const CLAUDE_INSTALL = "curl -fsSL https://claude.ai/install.sh | bash";
 export const HERMES_INSTALL =
   "curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash";
 export const UV_INSTALL = "curl -LsSf https://astral.sh/uv/install.sh | sh";