OpenCode

Keep OpenCode on your computer and give it a development environment on Railway. The CLI starts an authenticated OpenCode server on a cloud agent, checks its HTTPS connection, and gives your client everything it needs to connect.

YOUR COMPUTER

OpenCode Desktop or terminal

Prompts, review, and approvals

HTTPS

RAILWAY CLOUD AGENT

Your development environment

Coding tools, terminal, and files

Work happens on Railway. Your project files stay on the agent’s persistent disk.

Choose your edition

This guide covers standard OpenCode. OpenCode2 Beta → has its own Desktop app, runtime, and --opencode2 commands. Its guide covers automatic Desktop setup, local terminal connections, and running Beta inside Railway CA.

Connect OpenCode Desktop

Complete the CLI setup. Install and open OpenCode Desktop once, then run:

railway ca desktop --opencode

Railway creates or wakes the cloud agent, starts opencode serve in the background, and saves the authenticated server, default server, and remote project in standard OpenCode Desktop. You do not need to run a separate server command.

On macOS, setup restarts a running OpenCode app to apply the settings. Quit Desktop before setup on Windows or Linux. If the configuration is saved but the app cannot reopen, open it manually.

Start a chat on the cloud agent

Open Home with Cmd+B on macOS or Ctrl+B on Windows/Linux.
Under Projects, find Railway: <agent-name>.
Open /app, or the directory you chose with --dir.
Use the project's menu to start a New session.

Choose the Railway project when starting a session. Changing the default server does not move existing chats; a chat opened against your local server continues to run locally.

To verify, ask OpenCode to run hostname and pwd using its terminal tool. Compare the output with the selected remote project.

Use your local terminal client

railway code --opencode

Railway prepares the same cloud server and prints its Desktop connection settings and a terminal connection command. Press Enter to launch your local OpenCode client. If it is missing, Railway offers to install it first.

Declining or canceling either prompt leaves the server running and prints the details so you can connect later. The local-client flow prints Desktop settings for manual entry; use railway ca desktop --opencode to write them automatically.

OpenCode's client/server architecture lets the local interface use tools and files on the remote server.

Reconnect to an existing server

railway code --opencode connect

Railway discovers running standard OpenCode servers on agents you own. One match connects directly; multiple matches open a picker labeled workspace/project/cloud-agent name.

Connect to a known agent by name or ID:

railway code --opencode connect <agent-name>

A named connection can wake an agent with a saved server configuration and restart its server. It does not create a new VM. In a noninteractive terminal, the CLI prints connection details instead of launching a client; use a name or ID when there are multiple candidates.

Connect manually

Use the values printed by Railway when you add a server in Desktop:

Setting	Value
Name	The cloud agent's name
Server	The agent's printed HTTPS URL
Username	`opencode`
Password	The generated password printed by setup
Directory	`/app`, or your chosen remote directory

The printed terminal command has this form. Replace the URL and password placeholders with your connection details:

OPENCODE_SERVER_USERNAME=opencode OPENCODE_SERVER_PASSWORD='<server-password>' opencode attach 'https://<agent-domain>' --dir /app

The password authenticates access to your coding server. Provider sign-in is separate; setup can carry the provider credentials in your local OpenCode auth.json. Keep the printed password private.

Run entirely inside Railway CA

railway code --opencode remote

Both the client and server run on the cloud agent, and your terminal opens OpenCode inside Railway CA. This flow does not launch your local OpenCode client.

Choose a fresh agent or project directory

railway code --opencode --new
railway ca desktop --opencode --new

Choose one command for your preferred interface. New standard OpenCode agents get names such as oc-railg-3ed. Existing agents keep their names; see agent naming.

To configure an existing agent's remote directory:

railway ca desktop --opencode --agent <agent-name> --dir /app/my-project

The local terminal flow also accepts --dir. Clone or create your project on the agent before using its directory.

Sleep and return

railway ca sleep <agent-name>

Sleep keeps the disk and stops the server. To return from Desktop, rerun setup:

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

Or use the named connect command for your local terminal. Setup reuses the saved server credentials. There is no local SSH tunnel to keep running.

Remove the connection

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

This stops the managed server on a running agent and removes its local Desktop connection, project, and shared SSH entry. It does not wake a sleeping agent or delete its disk. Use railway ca sleep or railway ca delete to manage the VM itself.

For a preview without changes, use --dry-run with the setup command. Existing Desktop configuration is backed up before changes.

OpenCode troubleshooting →