cowork-os 0.3.69 → 0.3.70

package/README.md

@@ -55,12 +55,17 @@ Your AI needs a secure home. CoWork OS provides the runtime, security layers, an
 
 ### From npm (CLI Launch)
 
+Use this flow to test like a first-time user in a clean folder:
+
 ```bash
 # Install into a local folder
 mkdir -p /tmp/cowork-run
 cd /tmp/cowork-run
 npm install cowork-os@latest --no-audit --no-fund
 
+# Ensure no previously running CoWork instance is active
+pkill -f '/cowork-os' || true
+
 # Start app
 npx cowork-os
 ```
@@ -69,6 +74,22 @@ You can also install globally and launch directly:
 
 ```bash
 npm install -g cowork-os
+
+# Optional: verify installed version
+npm list -g cowork-os --depth=0
+
+# Ensure no previously running CoWork instance is active
+pkill -f '/cowork-os' || true
+
+cowork-os
+```
+
+If the app opens but shows `vUnknown` or `Error invoking remote method 'app:getVersion'`, you likely connected to an older already-running instance.
+
+Run:
+
+```bash
+pkill -f '/cowork-os' || true
 cowork-os
 ```
 
@@ -117,16 +138,66 @@ The packaged app will be in the `release/` directory.
 
 ### Linux VPS (Headless / Server Mode)
 
-Run CoWork OS without a GUI and manage it remotely via the WebSocket Control Plane (Web UI + CLI):
+If this is your first VPS install, start here (Node-only, no Docker):
+
+1. On your VPS (SSH terminal), connect and verify Node version:
+
+```bash
+ssh user@your-vps
+node -v
+npm -v
+```
+
+`cowork-os` requires Node `>=22.12.0`. If you see `v20`/`v21`, upgrade first:
+
+```bash
+curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
+sudo apt-get install -y nodejs
+node -v
+```
+
+2. Install and start CoWork OS (local install, no sudo needed):
+
+```bash
+mkdir -p ~/cowork-run
+cd ~/cowork-run
+npm init -y >/dev/null
+npm install cowork-os@latest --no-audit --no-fund
+
+export COWORK_IMPORT_ENV_SETTINGS=1
+export OPENAI_API_KEY=your_key_here   # or ANTHROPIC_API_KEY=your_key_here
+npx coworkd-node --print-control-plane-token
+```
+
+Keep this terminal open. It runs the server and prints your Control Plane token.
+
+If you see `sh: 1: tsc: not found` right after `npx coworkd-node`, you are on an older broken npm publish. Upgrade and retry:
+
+```bash
+npm install cowork-os@latest --no-audit --no-fund
+```
+
+3. On your local machine (second terminal), create the SSH tunnel:
+
+```bash
+ssh -N -L 18789:127.0.0.1:18789 user@your-vps
+```
+
+If local port `18789` is busy:
+
+```bash
+ssh -N -L 28789:127.0.0.1:18789 user@your-vps
+```
+
+4. Open the web UI in your browser:
+
+- `http://127.0.0.1:18789/` (or `http://127.0.0.1:28789/` if you used 28789)
+- Paste the token from step 1
+
+For production/persistent setup and Docker/systemd options, use:
 
-- Overview / positioning: `docs/self-hosting.md`
 - Guide: `docs/vps-linux.md`
-- Start (Node-only, no Electron/Xvfb): `node bin/coworkd-node.js`
-- Start (headless Electron): `node bin/coworkd.js`
-- Web UI (via tunnel): `http://127.0.0.1:18789/`
-- Headless creds: set `COWORK_IMPORT_ENV_SETTINGS=1` + `OPENAI_API_KEY`/`ANTHROPIC_API_KEY` (see guide)
-- Docker: `docker compose up --build -d`
-- systemd templates: `deploy/systemd/`
+- Overview: `docs/self-hosting.md`
 
 ---