View as Markdown

Connecting to Runners

Once your runner is running, connect through the interface that best matches the task.

Connection methods
Browser

Fastest path into a runner

Best for quick prompts, browsing files, and using the built-in terminal without installing anything locally.

Chat · Files · Terminal
Desktop App

Best for longer editing sessions

Use the OpenCode app when you want an IDE-style experience, local file sync, and interactive collaboration with the agent.

IDE · Sync · Multi-terminal
Terminal

Fits scriptable CLI workflows

Connect from the command line when you want automation, shell-first workflows, or direct control over the session.

CLI · Scripting · Shell access
All three connection paths reach the same runner. Pick the interface that matches the job.

Runner detail page

Browser Connection

The browser is the fastest way to get into a runner:

  1. Navigate to the runner in Forkline
  2. Click the runner URL
  3. The runner interface opens in your browser

Browser Features

  • Chat interface: Send prompts and receive responses
  • File browser: Navigate and inspect your repository
  • Terminal: Execute commands in the runner environment
  • Task history: Review previous interactions

Tip: Choose the browser when you want zero setup and a fast way to inspect or direct a running session.

Desktop Application

Use the OpenCode desktop app for deeper interactive work.

Prerequisites

  1. Download the desktop app from opencode.ai
  2. Get your OpenCode password from the runner panel in Forkline

Connecting

  1. Open the desktop app
  2. Enter the runner URL
  3. Enter your OpenCode password
  4. Click Connect

Desktop Features

  • Full IDE: Syntax highlighting and code navigation
  • Local file sync: Edit locally and sync with the runner
  • Split terminal: Run multiple shell sessions
  • Real-time collaboration: Watch changes as the agent works

Terminal Connection

Connect from the OpenCode CLI:

# Install OpenCode CLI
npm install -g opencode

# Connect to runner
opencode connect <runner-url> --password <password>

Runner Password

Each runner session has its own password:

  • Find it in the runner panel in Forkline
  • Keep it secret and never commit or share it
  • Treat it as specific to that one runner session

Troubleshooting

Connection fails with /api/health 404

If your OpenCode client reports a 404 on /api/health or similar endpoints, the client and runner are running incompatible versions. This is not a password issue.

Solution: Forkline runners are tested with OpenCode 2.0.24. Check your version with opencode --version. If you are running a different version, upgrade to 2.0.24:

curl -fsSL https://opencode.ai/v2/install | bash

Authentication fails despite correct password

The forkline runners attach command sets both OPENCODE_PASSWORD and OPENCODE_SERVER_PASSWORD environment variables. If you are connecting manually and authentication fails, ensure you are setting OPENCODE_PASSWORD (not just OPENCODE_SERVER_PASSWORD) when launching the OpenCode client:

OPENCODE_PASSWORD=<runner-password> opencode --server <runner-url>

Next Steps