# @openchambery/web
[](https://github.com/yee94/openchamber/stargazers)
[](https://github.com/yee94/openchamber/releases/latest)
[](https://discord.gg/ZYRSdnwwKA)
Run [OpenCode](https://opencode.ai) in your browser. Install the CLI, open `localhost:3000`, done. Works on desktop browsers, tablets, and phones as a PWA.
Full project overview, screenshots, and all features: [github.com/yee94/openchamber](https://github.com/yee94/openchamber)
## Install
```bash
curl -fsSL https://raw.githubusercontent.com/yee94/openchamber/main/scripts/install.sh | bash
```
Or install manually: `bun add -g @openchambery/web` (or npm, pnpm, yarn).
> **Prerequisites:** [OpenCode CLI](https://opencode.ai) installed, Node.js 22+.
## Usage
```bash
openchamber # Start on port 3000
openchamber --port 8080 # Custom port
openchamber --lan --port 3000 # Listen on LAN (0.0.0.0)
openchamber --ui-password secret # Password-protect UI
openchamber startup enable # Start at login as a native service
OPENCHAMBER_UI_PASSWORD=secret openchamber startup enable # Save service password env
openchamber startup status # Show startup service status
openchamber startup disable # Remove startup service
openchamber connect-url --port 3000 # Add this server to OpenChamber Desktop
openchamber connect-url --server http://host:3000 --qr
openchamber connect-url --port 3000 --qr
openchamber logs # Follow latest instance logs
OPENCODE_PORT=4096 OPENCODE_SKIP_START=true openchamber # Connect to external OpenCode server
OPENCODE_HOST=https://myhost:4096 OPENCODE_SKIP_START=true openchamber # Connect via custom host/HTTPS
openchamber stop # Stop server
openchamber update # Update to latest version
```
`startup enable` snapshots your current environment into the native service so startup behaves like you launched `openchamber` from the same shell. This preserves provider tokens, PATH, SSH agent settings, and other CLI auth/config env vars. Use `--no-env-snapshot` for a minimal service env.
## Self-hosted Private Relay
Run a private Relay when OpenChamber Hosts need outbound-only remote access:
Install and run OpenChamber Hosts with `@openchambery/web`. Install the self-hosted Relay server separately:
```sh
npm install -g @openchambery/relay-server
openchamber-relay --public-url wss://relay.example.com/ws
```
Use TLS at a reverse proxy and keep the default loopback listener. From the repository root, Docker deployment uses:
```sh
OPENCHAMBER_RELAY_SERVER_PUBLIC_URL=wss://relay.example.com/ws \
OPENCHAMBER_RELAY_PUBLISHED_PORT=8787 \
docker compose -f docker-compose.relay.yml up -d --build
```
Compose publishes `127.0.0.1:${OPENCHAMBER_RELAY_PUBLISHED_PORT:-8787}` by default. `OPENCHAMBER_RELAY_PUBLISHED_PORT` selects the host port, and a TLS reverse proxy provides the public `wss://` entry point.
Point every OpenChamber Host at the Relay, then generate a Relay pairing link or enable Relay pairing:
```sh
OPENCHAMBER_RELAY_URL=wss://relay.example.com/ws openchamber
```
The **Add a device** dialog defaults to `wss://relay.openchamber.dev/ws` and lets the operator enter a custom `ws://` or `wss://` Relay endpoint for that pairing. The Host persists and switches to the selected endpoint before creating the QR code; `OPENCHAMBER_RELAY_URL` remains authoritative when set. The creating client remembers the last effective endpoint locally.
Saved pairing candidates retain their endpoint snapshot, including the Relay URL. Mobile and Desktop clients reconnect through that saved endpoint until a new pairing flow replaces it. See [OpenChamber Relay Server](https://github.com/yee94/openchamber/tree/main/packages/relay-server#readme) for bundle builds, reverse-proxy configuration, security, operations, and systemd guidance.
### Connect other OpenChamber apps
Use `connect-url` when a web/API server should be added to OpenChamber Desktop or another OpenChamber app. If no server is running on the selected port, OpenChamber starts one first.
```bash
openchamber connect-url --port 3000
openchamber connect-url --port 3000 --qr
openchamber connect-url --port 3000 --json
openchamber connect-url --port 3000 --name "Workstation"
openchamber connect-url --port 3000 --lan --server http://workstation.local:3000 --qr
```
### Headless/API-only server for Desktop
Use this on a remote machine when you want OpenChamber running as a web/API server, then connect to it from OpenChamber Desktop on another machine:
```bash
openchamber connect-url --port 3000 --api-only --lan --server http://workstation.local:3000 --qr --ui-password your-password
```
`--api-only` starts API routes without serving browser UI assets. `--lan` binds the server so other machines can reach it. `--server` is the address saved into the Desktop connection link. `--ui-password` protects browser access if UI routes are enabled elsewhere; the generated client token is what Desktop uses for API access.
This creates a remote client token and prints an `openchamber://connect?...` link. The link contains the server URL, token, label, and payload version. In OpenChamber Desktop, paste it in **Settings -> Remote Instances -> Direct Instances -> Import Link** to add that server as an Instance.
If the server was started with `--lan` or `--host 0.0.0.0`, `connect-url` automatically advertises a detected LAN IP instead of `127.0.0.1`. Use `--server ` when you want to advertise a specific DNS name, Tailscale address, reverse proxy URL, or HTTPS endpoint.
If you are exposing the server beyond localhost, start it with a password:
```bash
openchamber serve --lan --port 3000 --ui-password your-password
```
Generating a client token does not automatically password-protect the hosted browser UI. `--ui-password` protects browser access; the client token lets another OpenChamber app connect to this server.
Connect to external OpenCode server
```bash
OPENCODE_PORT=4096 OPENCODE_SKIP_START=true openchamber
OPENCODE_HOST=https://myhost:4096 OPENCODE_SKIP_START=true openchamber
```
| Variable | Description |
|----------|-------------|
| `OPENCODE_HOST` | Full base URL of external server (overrides `OPENCODE_PORT`) |
| `OPENCODE_PORT` | Port of external server |
| `OPENCODE_SKIP_START` | Skip starting embedded OpenCode server |
| `OPENCHAMBER_OPENCODE_HOSTNAME` | Bind hostname for managed OpenCode server (default: `127.0.0.1`, use `0.0.0.0` for LAN/remote access — trusted networks only) |
| `OPENCHAMBER_HOST` | Bind hostname for the OpenChamber web server (default: `127.0.0.1`; use `0.0.0.0` for LAN/remote access — trusted networks only) |
| `OPENCHAMBER_VERBOSE_REQUEST_LOGS` | Set to `true` to log every HTTP request; disabled by default to keep user logs small |
| `OPENCHAMBER_SKIP_API_COMPRESSION` | Set to `true` to disable gzip compression for `/api/*` responses |
| `OPENCHAMBER_COMPRESS_API` | Set to `true` to force `/api/*` compression, or `false` to disable it. Desktop runtime disables API compression by default to reduce local sidecar CPU use |
Bind managed OpenCode to LAN / Tailscale
```bash
OPENCHAMBER_OPENCODE_HOSTNAME=0.0.0.0 openchamber --port 3000
```
**Security note:** binding to `0.0.0.0` exposes the server on all network interfaces — use only on trusted networks and protect with firewall rules or `--ui-password`.
**Optional env vars:**
```yaml
environment:
UI_PASSWORD: your_secure_password
OPENCHAMBER_UPDATE_API_URL: https://updates.example.com/v1/update/check # Primary compatible update-check service; Vercel and GitHub Releases provide fallback
```
**Data directory:** mount `data/` for persistent storage. Ensure permissions:
```bash
mkdir -p data/openchamber data/opencode/share data/opencode/config data/ssh
chown -R 1000:1000 data/
```
Background & daemon mode
```bash
openchamber # Runs in background by default
openchamber stop # Stop background server
```
systemd service (VPN / LAN access)
Use `--foreground` to keep the CLI process alive so systemd (or any other process manager) can track and restart it. Combine with `OPENCODE_HOST` to connect to an OpenCode instance running as a separate service.
**`~/.config/systemd/user/opencode.service`**
```ini
[Unit]
Description=OpenCode Server
[Service]
Type=simple
ExecStart=opencode serve --port 4095
Environment="PATH=/home/linuxbrew/.linuxbrew/bin:/home/linuxbrew/.linuxbrew/sbin:/home/YOU/.local/bin:/home/YOU/.npm-global/bin:/usr/local/bin:/usr/bin:/bin"
Environment=SSH_AUTH_SOCK=%t/ssh-agent.socket
Restart=on-failure
RestartSec=5
[Install]
WantedBy=default.target
```
> **Why set `PATH` and `SSH_AUTH_SOCK`?**
> systemd user services start with a minimal environment — no shell profile is sourced.
> Without an explicit `PATH`, OpenCode won't find tools installed via Homebrew, npm, or `~/.local/bin`.
> Without `SSH_AUTH_SOCK`, git operations over SSH (push, pull, clone) will fail.
> `%t` expands to `$XDG_RUNTIME_DIR` (e.g. `/run/user/1000`), where most SSH agents write their socket.
**`~/.config/systemd/user/openchamber.service`**
```ini
[Unit]
Description=OpenChamber Web Server
After=opencode.service
[Service]
Type=simple
ExecStart=openchamber serve --port 3000 --host 0.0.0.0 --ui-password your-password --foreground
Environment="OPENCODE_HOST=http://localhost:4095"
Environment="OPENCODE_SKIP_START=true"
Restart=on-failure
RestartSec=5
[Install]
WantedBy=default.target
```
```bash
systemctl --user daemon-reload
systemctl --user enable --now opencode openchamber
```
`--host 0.0.0.0` is required to listen on all interfaces (the default is `127.0.0.1`). Use `--host ` or `OPENCHAMBER_HOST=` to bind to a specific interface instead.
## What makes the web version special
- **Remote access** - LAN pairing and private relay with QR onboarding. Scan from your phone, start coding.
- **Mobile-first PWA** - optimized chat controls, keyboard-safe layouts, drag-to-reorder projects
- **Background notifications** - know when your agent finishes, even from another tab
- **Self-update** - update and restart from the UI, server settings stay intact
- **Cross-tab tracking** - session activity stays in sync across browser tabs
- LAN pairing and private relay for reaching a host that is not publicly exposed
- One-scan onboarding with pairing QR links
- Mobile-first experience: optimized chat controls, keyboard-safe layouts, and attachment-friendly UI
- Background notifications plus reliable cross-tab session activity tracking
- Built-in self-update + restart flow that keeps your server settings intact
## License
MIT
