docs: refresh docs and add tunnel usage guide (#666)

Add a new tunnels page with verified, up-to-date CLI examples Remove deprecated `--daemon` usage and clarify QR/password behavior Add docs validation tooling and docs-source workflow for packaging and sync
2026-03-15 03:30:35 +02:00
parent 1f8e875357
commit 75c90d955c
14 changed files with 549 additions and 0 deletions
@@ -0,0 +1,25 @@
+---
+title: OpenChamber Docs
+description: Setup and operating guide for OpenChamber across web, desktop, and VS Code.
+---
+
+# OpenChamber Docs
+
+OpenChamber is the visual workspace around OpenCode.
+
+Use these docs to:
+
+- install the right surface for your workflow
+- expose OpenChamber safely for remote use
+- customize appearance and troubleshoot common issues
+
+## Read this first
+
+- [Install](/install/)
+- [Quickstart](/quickstart/)
+- [Tunnels](/tunnels/)
+- [Troubleshooting](/troubleshooting/)
+
+## What OpenChamber is for
+
+OpenChamber is for the parts of AI coding that benefit from a control room: branching sessions, reviewing diffs, managing terminals, watching tool progress, running project actions, and keeping the full board visible while the agent works.
@@ -0,0 +1,33 @@
+---
+title: Install
+description: Install OpenChamber for desktop, web, or VS Code.
+---
+
+# Install
+
+OpenChamber has three main surfaces:
+
+- desktop app for macOS
+- CLI-hosted web app with installable PWA
+- VS Code extension
+
+## Prerequisite
+
+Install [OpenCode](https://opencode.ai) first.
+
+## Web + PWA
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/openchamber/openchamber/main/scripts/install.sh | bash
+openchamber --ui-password be-creative-here
+```
+
+Then open the URL printed by the CLI (usually `http://localhost:3000`).
+
+## Desktop
+
+Download the latest desktop build from the GitHub releases page or the OpenChamber download page.
+
+## VS Code
+
+Install from the VS Code Marketplace and sign into your usual OpenCode workflow.
@@ -0,0 +1,22 @@
+---
+title: Quickstart
+description: Start OpenChamber quickly and choose the right surface for the task.
+---
+
+# Quickstart
+
+## Fastest path
+
+1. Install OpenCode.
+2. Install OpenChamber CLI.
+3. Run `openchamber --ui-password be-creative-here`.
+4. Open the web UI on your machine.
+5. If needed, start a tunnel and scan the QR code from your phone.
+
+Use a strong UI password, especially if you plan to expose the instance remotely.
+
+## Which surface should I use?
+
+- use **desktop** for macOS-heavy daily driver workflows
+- use **web** for remote access and mobile review
+- use **VS Code** for editor-native sessions beside code
@@ -0,0 +1,30 @@
+---
+title: Themes
+description: Customize OpenChamber with built-in and user-defined themes.
+---
+
+# Themes
+
+OpenChamber supports built-in themes and custom theme JSON files.
+
+## Add a custom theme
+
+1. Create the themes directory:
+
+```bash
+mkdir -p ~/.config/openchamber/themes
+```
+
+2. Add your JSON file to that directory (for example `my-theme.json`).
+3. Open OpenChamber, then go to **Settings -> Theme -> Reload themes**.
+4. Pick your theme from the dropdown.
+
+## Theme location
+
+- macOS/Linux: `~/.config/openchamber/themes/`
+
+## Full JSON format reference
+
+Use the full format guide in the main repo docs:
+
+- [`docs/CUSTOM_THEMES.md`](https://github.com/openchamber/openchamber/blob/main/docs/CUSTOM_THEMES.md)
@@ -0,0 +1,30 @@
+---
+title: Troubleshooting
+description: Common setup and runtime issues with quick fixes.
+---
+
+# Troubleshooting
+
+## OpenChamber command exits or fails to start
+
+- confirm Node.js `>=20`
+- run `openchamber --version`
+- reinstall latest CLI if needed
+
+## Web UI is not reachable
+
+- check server logs with `openchamber logs`
+- verify active port (default `3000`)
+- open `http://localhost:3000` directly first before testing tunnel links
+
+## Remote/tunnel link does not work
+
+- run `openchamber tunnel status --all`
+- restart tunnel from the same instance/port
+- regenerate connect link if previous token was already used
+
+## VS Code extension does not connect
+
+- confirm OpenChamber server is running
+- verify extension is updated
+- reload VS Code window and retry connection
@@ -0,0 +1,77 @@
+---
+title: Tunnels
+description: Expose OpenChamber safely for remote and mobile access.
+---
+
+# Tunnels
+
+Use `openchamber tunnel` to expose a running OpenChamber instance.
+
+## Quick start (Cloudflare quick mode)
+
+1. Start OpenChamber:
+
+```bash
+openchamber
+```
+
+2. Start a tunnel:
+
+```bash
+openchamber tunnel start --provider cloudflare --mode quick
+```
+
+3. Check status:
+
+```bash
+openchamber tunnel status
+```
+
+By default, OpenChamber prints a QR code in interactive TTY sessions. Use `--qr` to force QR output, or `--no-qr` to disable it.
+
+## Managed modes
+
+### Managed remote
+
+Use a token + hostname managed by Cloudflare:
+
+```bash
+openchamber tunnel start --provider cloudflare --mode managed-remote --token-file ~/.secrets/cf-token --hostname app.example.com
+```
+
+### Managed local
+
+Use a local `cloudflared` config:
+
+```bash
+openchamber tunnel start --provider cloudflare --mode managed-local --config ~/.cloudflared/config.yml
+```
+
+## Profiles (managed-remote)
+
+Save a reusable profile:
+
+```bash
+openchamber tunnel profile add --provider cloudflare --mode managed-remote --name prod-main --hostname app.example.com --token-file ~/.secrets/cf-token
+```
+
+Start using the saved profile:
+
+```bash
+openchamber tunnel start --profile prod-main
+```
+
+## Useful commands
+
+```bash
+openchamber tunnel providers
+openchamber tunnel ready --provider cloudflare
+openchamber tunnel doctor --provider cloudflare
+openchamber tunnel stop --port 3000
+```
+
+## Behavior notes
+
+- one active tunnel per OpenChamber instance (port)
+- starting a new mode/provider on same instance replaces previous tunnel
+- generating a new connect link revokes previous unused one