---
title: Remote Instances
description: Connect the desktop app to OpenChamber on another machine over SSH.
---

# Remote Instances

The desktop app can connect to OpenChamber running on another machine over SSH — a work server, a cloud box, a homelab — and bring its UI to your screen as if it were local. Set this up at **Settings → Remote Instances**.

> Remote instances are a **desktop-only** feature. On the web or in VS Code, connect to a remote server with the environment variables in [OpenCode Server](/opencode-server/) instead.

## Add a remote instance

1. Open **Settings → Remote Instances** and add one.
2. Give it the SSH command you'd normally use to reach the machine, plus a nickname.
3. Choose how OpenChamber runs there:
   - **managed** — OpenChamber installs and starts itself on the remote machine
   - **external** — connect to one that's already running
4. Connect.

OpenChamber walks through the steps — checking the connection, setting up the remote, starting the server, and forwarding the port — and shows where it is at each stage. When it reaches **ready**, the remote UI loads locally.

## Credentials

You decide whether to save the SSH and UI passwords or enter them each time. If the connection drops, OpenChamber reports which step failed so you can fix it — see [Remote access](/troubleshooting/remote-access/).

## Direct connection links

If a remote machine already runs OpenChamber, create a connection link there and import it in **Settings → Remote Instances → Server links**:

```bash
openchamber connect-url --port 3000 --server http://your-host:3000 --qr
```

`connect-url` starts the server first if nothing is running on that port. Add `--api-only` for a headless server, `--lan` to bind to the LAN when starting, `--ui-password` to protect browser access, and `--name` to label the saved connection.

The generated link contains a client token for OpenChamber apps. That token is separate from the browser UI password and survives server restarts until you revoke or delete it.

## Related

- [OpenCode Server](/opencode-server/) — connect to a remote server on web or VS Code
- [Remote access](/troubleshooting/remote-access/) — when a connection won't complete
