OpenCode2 Beta

Use OpenCode2 Beta with a persistent Railway workspace. Railway prepares the latest official Beta runtime on your cloud agent and connects the Beta desktop app or terminal client to its authenticated HTTPS server.

Connect Beta Desktop

Complete the CLI setup, then install and open the desktop app from the official OpenCode Beta repository.

Create a fresh Beta agent:

railway ca desktop --opencode2 --new

Railway downloads the Beta runtime on the agent, starts its server in the background, and checks the authenticated public connection. It then saves the URL, username, password, default server, and remote project in OpenCode Beta Desktop.

The first startup can take several minutes. Wait for the CLI to finish checking the HTTPS connection before connecting.

On macOS, setup restarts the running Beta app to apply settings. Quit it before setup on Windows/Linux. A saved configuration can still be used if automatic reopening fails; open Beta Desktop manually.

Start a remote Beta session

1. Open Home with Cmd+B on macOS or Ctrl+B on Windows/Linux.
2. Under Projects, choose Railway: <agent-name>.
3. Open /app, or the server directory selected during setup.
4. Start a New session from that project.

Existing local chats retain their original server. Setting the new server as the default does not transfer those chats. Ask the new session to execute hostname and pwd to verify its remote tools and directory.

Launch your local Beta terminal client

railway code --opencode2 --new

Railway creates the cloud server and prints connection details for both terminal and manual Desktop setup. Press Enter to connect with your local opencode2 client. Railway checks for the Beta client at this point and offers to install it if missing.

Standard OpenCode and OpenCode2 are detected and installed independently. The local installer does not install the Beta desktop app.

Canceling the launch or installation prompt leaves the cloud server running and prints its connection details. Omit --new to reuse an existing agent where possible.

Reconnect

Find your running Beta servers:

railway code --opencode2 connect

One match connects directly. Multiple matches show a workspace/project/cloud-agent name picker. Standard OpenCode servers are excluded.

Connect directly by name or ID, including to wake an agent with a saved Beta server:

railway code --opencode2 connect <agent-name>

For manual connection, use the command printed by Railway. It has this form; replace the placeholders with your server's details:

OPENCODE_SERVER_USERNAME=opencode OPENCODE_SERVER_PASSWORD='<server-password>' opencode2 --server 'https://<agent-domain>'

Beta uses --server. The standard OpenCode client uses attach. Use the client edition matching the server.

To configure Desktop manually, add the printed server URL, username, and password, then open the remote project directory. Use railway ca desktop --opencode2 --agent <agent-name> to save these settings automatically.

Run Beta entirely inside Railway CA

railway code --opencode2 remote

This runs both client and server on the cloud agent and opens the terminal session inside Railway CA. Add --new for a fresh VM:

railway code --opencode2 remote --new

You can also use railway ca --opencode2. In Railway CA's new-session picker, highlight OpenCode and press Tab to switch to OpenCode2 [Beta]. Tab also switches editions in the prompt footer; Shift+Tab cycles coding agents.

Runtime updates

Each new Beta process checks the latest official release. Railway downloads the Linux package for the agent's architecture, verifies its published SHA-256, and extracts the CLI runtime. A verified cached runtime is reused until the release changes.

Running sessions retain their executable. If an update fails, startup reports the error and preserves the previous runtime. Reconnecting to an already running server reuses that server.

New Beta agents have names such as oc2-railg-3ed, so you can distinguish them from standard OpenCode agents. See agent naming.

Provider sign-in

Beta stores provider accounts in its local credential database. Railway imports the active account for each provider from that database, while preserving credentials already configured on the agent. It transfers provider credentials, not your local chats or sessions.

The default source is ~/.local/share/opencode/opencode.db; custom XDG data paths and OPENCODE_DB are respected. Legacy auth.json is used only when no Beta credential store exists. If the Beta store exists but has no active credentials, Railway does not restore an old legacy sign-in.

If no provider is available to copy, connect one from the remote Beta session or run opencode2 auth login in a shell on the agent. This provider login is separate from the server username and password printed by Railway.

Project directory

The Beta server uses its startup directory, defaulting to /app. The local client connects to that server without a local filesystem argument.

Choose the directory when preparing a new server with --dir. Changing the startup directory of an already configured Beta server requires a fresh agent; the CLI reports this instead of silently connecting to a different directory. To work in a repository cloned beneath /app, tell Beta which subdirectory contains the project.

Sleep, restart, or remove

Stop compute while keeping files:

railway ca sleep <agent-name>

To wake the agent and restart its server for Desktop:

railway ca desktop --opencode2 --agent <agent-name>

For your local terminal, use the named connect command. Both paths reuse saved server credentials.

To remove the managed Desktop connection and stop the server on a running VM:

railway ca desktop --opencode2 --agent <agent-name> --remove

This leaves the agent and disk in place. Use --dry-run on the setup command to preview configuration without creating or waking a VM.

Troubleshoot Beta startup and sign-in →