Bohdan Triapitsyn
2031e3b4a8
Add a packaged-client runtime boundary so the shared UI can talk to local, desktop, remote, and VS Code runtimes through the right transport instead of assuming one same-origin web server. Centralize OpenChamber-owned API access behind RuntimeAPIs, runtimeFetch, and runtime URL helpers, while keeping official OpenCode traffic on the SDK path. Support runtime switching, remote host selection, desktop client credentials, and headless connection links for pairing packaged clients with remote OpenChamber servers. Harden the new auth model by moving long-lived client tokens out of browser URLs, introducing short-lived scoped URL tokens for browser-owned transports, restricting URL-token access to explicit readable/realtime routes, and making client-token management session-scoped or self-scoped as appropriate. Update browser-owned assets and preview proxy flows to work with the split runtime model, including authenticated project icons, preview token propagation, CSP-safe preview bridge injection, and preview proxy auth that survives short-lived URL-token expiry. Tighten Electron security boundaries for packaged clients by gating privileged preload state to trusted origins and requiring explicit confirmation before connect deep-links import or switch remote runtimes. Also refresh agent guidance and project skills so future runtime/API, auth, preview, UI, CLI, settings, locale, and drag-to-reorder work follows the new architecture.
98 lines
3.7 KiB
Plaintext
98 lines
3.7 KiB
Plaintext
---
|
|
title: OpenCode Server
|
|
description: Connect OpenChamber to a local or remote OpenCode server.
|
|
---
|
|
|
|
# OpenCode Server
|
|
|
|
OpenChamber runs on top of an OpenCode server. By default it starts one for you, so you don't have to do anything. You only need this page if you want to point OpenChamber at a server you already run, or manage the one it starts.
|
|
|
|
## How OpenChamber finds a server
|
|
|
|
When OpenChamber starts, it looks for a server in this order:
|
|
|
|
1. reuse a server it already started
|
|
2. connect to an external one if you told it to (see below)
|
|
3. auto-detect a server on the default port (`4096`)
|
|
4. otherwise, start and manage its own
|
|
|
|
If nothing is configured, step 4 happens automatically and you're up and running.
|
|
|
|
## Connect to a server you already run
|
|
|
|
Set these before starting OpenChamber:
|
|
|
|
```bash
|
|
OPENCODE_HOST=http://localhost:4096 OPENCODE_SKIP_START=true openchamber
|
|
```
|
|
|
|
- `OPENCODE_HOST` — the full address of your OpenCode server, including the port (a value like `http://localhost:4096`). It must not have a path at the end.
|
|
- `OPENCODE_SKIP_START=true` — tells OpenChamber not to start its own server.
|
|
|
|
If you only need to change the port, set `OPENCODE_PORT` instead of `OPENCODE_HOST`.
|
|
|
|
If `OPENCODE_HOST` is missing its port or has a path, OpenChamber ignores it and falls back to starting its own server. Watch the startup logs for a `[config]` warning if a connection you expected didn't happen.
|
|
|
|
## Manage the server from the CLI
|
|
|
|
```bash
|
|
openchamber status
|
|
openchamber logs
|
|
openchamber restart
|
|
openchamber stop
|
|
```
|
|
|
|
`openchamber` on its own starts the server in the background. Add `--foreground` to keep it attached to your terminal.
|
|
|
|
## Start OpenChamber at login
|
|
|
|
Use `startup enable` to install a native user service. OpenChamber uses `launchd` on macOS, `systemd --user` on Linux, and Task Scheduler on Windows.
|
|
|
|
```bash
|
|
openchamber startup enable
|
|
openchamber startup status
|
|
openchamber startup disable
|
|
```
|
|
|
|
To protect the UI, set the password when enabling the service:
|
|
|
|
```bash
|
|
OPENCHAMBER_UI_PASSWORD='secret' openchamber startup enable
|
|
```
|
|
|
|
For a headless server that starts at login and is meant for desktop or mobile clients, include `--api-only` and a reachable host:
|
|
|
|
```bash
|
|
openchamber startup enable --port 3000 --api-only --host 0.0.0.0 --ui-password secret
|
|
```
|
|
|
|
`startup enable` snapshots your current environment into the service so it behaves more like starting `openchamber` from the same shell. This keeps provider tokens, `PATH`, SSH agent settings, and other CLI auth/config variables available. Use `--no-env-snapshot` if you want a minimal service environment.
|
|
|
|
The startup service remembers `--port`, `--host`, `--ui-password`, and `--api-only`. CLI restart and update restart reuse those saved settings.
|
|
|
|
To create a connection link for another OpenChamber app, use:
|
|
|
|
```bash
|
|
openchamber connect-url --port 3000 --server http://your-host:3000 --qr
|
|
```
|
|
|
|
Run `openchamber connect-url --help` to see all link options, including `--name`, `--lan`, `--server`, `--api-only`, `--ui-password`, and `--qr`.
|
|
|
|
You can still manage tunnels independently for that running service:
|
|
|
|
```bash
|
|
openchamber tunnel start --port 3000
|
|
openchamber tunnel stop --port 3000
|
|
```
|
|
|
|
Stopping the tunnel does not restart the service or the app.
|
|
|
|
## "OpenCode is restarting"
|
|
|
|
While the server is starting or restarting, OpenChamber shows an "OpenCode is restarting" state and pauses requests until it's ready. This is normal right after launch or a restart. If it never clears, see [OpenCode connection](/troubleshooting/opencode-connection/).
|
|
|
|
## Related
|
|
|
|
- [Providers, Models & Agents](/providers/) — set up what the server talks to
|
|
- [OpenCode connection](/troubleshooting/opencode-connection/) — if it won't connect
|