---
title: "Connecting to Runners"
description: "Connect to your runners via browser, desktop application, or terminal."
section: "runners"
url: "https://forkline.dev/docs/runners/connecting"
markdown: "https://forkline.dev/docs/runners/connecting.md"
source: "src/content/docs/runners/connecting.mdx"
---

# Connecting to Runners

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

_Interactive figure (ConnectionMethodsBoard) — see the HTML version of this page._

![Runner detail page](https://forkline.dev/docs/screenshots/runner-detail.webp)

## 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](https://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:

```bash
# 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:

```bash
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:

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

## Next Steps

- [Start a runner](https://forkline.dev/docs/runners/starting)
- [Manage your runners](https://forkline.dev/docs/runners/managing)