OpenRemote Gateway

Setup

Initialize gateway config with the setup wizard from Installation. The wizard does not start the gateway or open the gateway TUI.

1. Start the background gateway with oo gateway start.
2. Open the gateway control UI with oo gateway.
3. Start OpenCode normally in a workspace, for example opencode -c --hostname 127.0.0.1.
4. The OpenRemote plugin registers that OpenCode instance with the gateway.
5. Scan the QR code shown in the gateway TUI or OpenCode sidebar.
6. The mobile app connects to the gateway and the gateway routes app traffic to the selected OpenCode instance.

Closing the gateway TUI does not stop the gateway. Use oo gateway stop to stop the background service.

After setup, oo is available as a short bin alias, for example oo gateway --help.

The bare setup wizard can initialize gateway config without starting the daemon or opening the gateway TUI.

The gateway saves its app-facing port after startup. Later start and restart commands try to reuse that port when it is available, and fall back to a free port when it is busy.

Purpose

The gateway is the stable local authority for OpenRemote. It owns remote access, app authentication, QR setup, resume credentials, tunnels, client limits, and routing to registered OpenCode instances.

The OpenCode plugin keeps working on its own when the gateway is unavailable. Gateway mode is an upgrade path for multiple OpenCode instances, Wake to Code, and a persistent gateway control UI.

Architecture

Mobile App
    |
    | one QR / one auth endpoint / OpenCode API
    v
OpenRemote Gateway daemon
    |    | __ OpenCode instance: ~/workspace/openremote
    |
     __ OpenCode instance: ~/workspace/docs

• The mobile app connects to the gateway, not directly to each OpenCode plugin.
• One gateway auth endpoint is shared by all registered OpenCode instances.
• The gateway TUI can show the active gateway QR, while the OpenCode sidebar can show a compact local QR before a client connects.
• Each OpenCode plugin registers its local OpenCode API target, workspace, active sessions, and heartbeat.
• The gateway forwards app API calls to the selected OpenCode instance.
• The selected instance is tracked per app client, with room for explicit instance headers later.

Commands

Plugin behavior

When OPENCODE_REMOTE_GATEWAY=auto, the plugin tries to use the gateway if it is configured and reachable. If the gateway is missing, unavailable, or not configured, the plugin falls back to the current sidebar QR/proxy behavior.

When the gateway is active, the plugin registers with it and keeps the OpenCode sidebar small: gateway health, remote access state, QR setup when needed, and connected-client status.

The sidebar hides QR setup once a gateway client is connected. Before connection, it prefers the compact local gateway URL for sidebar QR size, while the gateway TUI can show the active gateway URL.

Workspaces

The gateway can reopen previously connected workspaces for Wake to Code. A workspace becomes known only after a local OpenCode plugin successfully registers it.

• The app can request only a known workspace id. It cannot send arbitrary commands or paths.
• The gateway uses the last command used to open that workspace.
• If the workspace is already open, the gateway switches to that instance instead of starting another copy.
• The gateway TUI shows registered instances and recent workspaces for desktop visibility.

Configuration

The saved gateway config also stores the last successful app port so stop/start and restart can keep QR URLs stable when the port is still free.