Security hardening

README.md

@@ -57,6 +57,15 @@ npx stoops run codex --name MyCodex       # their agent
 
 Two humans, two agents, one room.
 
+### Over a private network (Tailscale, LAN)
+
+```bash
+npx stoops --name MyName --expose                     # bind to 0.0.0.0
+npx stoops join http://<host>:7890?token=<token>      # from another machine
+```
+
+`--expose` makes the server reachable beyond localhost. Without it, the server only accepts connections from `127.0.0.1`. The default port is 7890 — use `--port` to change it (e.g. `--port 7891`). You can run multiple rooms on different ports — each is independent with its own participants and tokens. Make sure the port is open in your firewall (`sudo ufw allow 7890`).
+
 ### Watch mode
 
 ```bash
@@ -99,11 +108,11 @@ Share links encode permissions. The host gets admin and member links at startup.
 ## All commands
 
 ```bash
-npx stoops [--name <name>] [--room <name>] [--port <port>] [--share]   # host + join
-npx stoops serve [--room <name>] [--port <port>] [--share]             # server only
-npx stoops join <url> [--name <name>] [--guest]                        # join a room
-npx stoops run claude [--name <name>] [--admin] [-- <args>]            # Claude Code
-npx stoops run codex [--name <name>] [--admin] [-- <args>]             # Codex
+npx stoops [--name <name>] [--room <name>] [--port <port>] [--share] [--expose]  # host + join
+npx stoops serve [--room <name>] [--port <port>] [--share] [--expose]            # server only
+npx stoops join <url> [--name <name>] [--guest]                                  # join a room
+npx stoops run claude [--name <name>] [--admin] [-- <args>]                      # Claude Code
+npx stoops run codex [--name <name>] [--admin] [-- <args>]                       # Codex
 ```
 
 Room state auto-saves. Use `--save file.json` / `--load file.json` for a specific file.
@@ -133,12 +142,59 @@ Room state auto-saves. Use `--save file.json` / `--load file.json` for a specifi
 
 ## Prerequisites
 
-- **Node.js** 18+
+- **Node.js** 20+
 - **tmux** — `brew install tmux` (macOS) / `sudo apt install tmux` (Linux)
 - **Claude Code** — `npm install -g @anthropic-ai/claude-code` (for `run claude`)
 - **Codex** — `npm install -g @openai/codex` (for `run codex`)
 - **cloudflared** — `brew install cloudflared` (optional, for `--share`)
 
+## Security
+
+Localhost-only by default (`--expose` opts in to network access). All API calls use `Authorization: Bearer` tokens. Share links expire after 1 hour, sessions after 24 hours. CORS restricted to localhost and tunnel URL (`--cors-origin` to add more). Rate limiting on joins and messages. Input size limits enforced.
+
+## Run from source
+
+If you're working off a branch or want to run without installing from npm:
+
+```bash
+git clone <repo-url> && cd stoops-cli
+npm install
+npm run build
+```
+
+**Terminal 1 — host a room on your LAN:**
+
+```bash
+npm start -- --name Jordan --room office --expose
+```
+
+You'll see share links printed in the TUI:
+
+```
+admin:  stoops join http://172.16.10.96:7890/?token=<admin-token>
+member: stoops join http://172.16.10.96:7890/?token=<member-token>
+guest:  stoops join http://172.16.10.96:7890/?token=<guest-token>
+```
+
+Send the member link to your team. Admin link gives kick/mute powers. Guest link is read-only.
+
+**Terminal 2 — connect an agent:**
+
+```bash
+npm start -- run claude --name MyClaude
+npm start -- run codex --name MyCodex
+```
+
+Tell the agent the join URL and it connects automatically.
+
+**From another machine — join the room:**
+
+```bash
+npm start -- join http://172.16.10.96:7890/?token=<token> --name Alice
+```
+
+All args after `--` are passed through, so anything from the `npx stoops` examples works the same way with `npm start --`.
+
 ## Contributing
 
 Issues and PRs welcome. See [GitHub Issues](https://github.com/stoops-io/stoops/issues).

package.json

@@ -54,7 +54,8 @@
     "watch": "tsup --watch",
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/cli/index.js"
   },
   "author": "Izzat Alsharif <work@izzatalsharif.com>",
   "license": "MIT",