Skip to main content

​
Overview

The attach command connects a terminal UI (TUI) to an already running OpenCode backend server started via serve or web commands. This allows you to:
  • Use the TUI with a remote OpenCode backend
  • Access the same session from multiple terminals
  • Connect to a server running on another machine
  • Maintain long-running server instances

​
Usage

opencode attach [url]
If no URL is provided, OpenCode will prompt you to select from recently connected servers or enter a new URL.

​
Options

​
url
string
URL of the running OpenCode server (e.g., http://localhost:4096 or http://192.168.1.100:4096)
​
--dir
string
Working directory to start TUI in. This is the directory context on the remote server.
​
--session
string
Session ID to continue. Short form: -s

​
Examples

​
Basic Usage

Start a server in one terminal: 
# Terminal 1
opencode serve --port 4096
Attach from another terminal: 
# Terminal 2
opencode attach http://localhost:4096

​
Remote Server Connection

Connect to OpenCode running on a remote machine: 
# On remote server (192.168.1.100)
opencode web --hostname 0.0.0.0 --port 4096

# On local machine
opencode attach http://192.168.1.100:4096

​
Specify Working Directory

Set the working directory context on the remote server: 
opencode attach http://localhost:4096 --dir /path/to/project

​
Continue Specific Session

Attach and continue a specific session: 
opencode attach http://localhost:4096 --session abc123def456

​
Use Cases

​
Development Workflow

Maintain a persistent server while working: 
# Start server once in a tmux/screen session
opencode serve --port 4096

# Attach from any terminal window as needed
opencode attach http://localhost:4096

# Detach with Ctrl+C, server keeps running

​
Team Collaboration

Multiple team members can attach to the same server: 
# Team member 1 starts server
opencode web --hostname 0.0.0.0 --port 4096

# Team member 2 attaches via TUI
opencode attach http://192.168.1.100:4096

# Team member 3 accesses via browser
open http://192.168.1.100:4096

​
Remote Development

Run OpenCode on a powerful remote machine: 
# On remote dev server with GPU
ssh dev-server
opencode serve --hostname 0.0.0.0 --port 4096

# On local laptop
opencode attach http://dev-server:4096

​
Multiple Projects

Run separate servers for different projects: 
# Project 1
opencode serve --port 4096 &

# Project 2
opencode serve --port 4097 &

# Attach to either project
opencode attach http://localhost:4096  # Project 1
opencode attach http://localhost:4097  # Project 2

​
Authentication

If the server requires authentication, provide credentials: 
# Set credentials in environment
export OPENCODE_SERVER_USERNAME="admin"
export OPENCODE_SERVER_PASSWORD="your-password"

# Or use URL format (not recommended for scripts)
opencode attach http://admin:password@localhost:4096
Avoid including credentials directly in commands or scripts. Use environment variables instead.

​
Comparison with Other Modes

FeatureTUI (default)attachserveweb
Terminal interface✓✓✗✗
Web interface✗✗✗✓
API access✗✓✓✓
Remote access✗✓✓✓
Multiple clients✗✓✓✓
Background server✗Required✓✓

​
Detaching

To detach from the server without stopping it:
  1. Press Ctrl+C in the attached terminal
  2. The TUI session ends
  3. The server continues running
  4. Attach again anytime to resume
To stop the server:
  1. Connect to the terminal running serve or web
  2. Press Ctrl+C to stop the server
  3. All attached clients will disconnect

​
Session Management

When you attach without specifying a session:
  • OpenCode shows you available sessions
  • Select an existing session to continue
  • Or create a new session
To attach to a specific session directly: 
opencode attach http://localhost:4096 --session <session-id>

​
Troubleshooting

​
Connection Refused

Problem: Error: connect ECONNREFUSED Solutions:
  • Verify the server is running
  • Check the URL and port are correct
  • Ensure firewall allows the connection
  • Confirm the server uses --hostname 0.0.0.0 for network access

​
Authentication Failed

Problem: Error: 401 Unauthorized Solutions:
  • Verify OPENCODE_SERVER_PASSWORD matches the server
  • Check OPENCODE_SERVER_USERNAME if customized
  • Ensure credentials are set in environment variables

​
Session Not Found

Problem: Session ID doesn’t exist Solutions:
  • Omit --session to see available sessions
  • Verify the session ID is correct
  • Check if the session was deleted

​
Network Timeout

Problem: Connection times out Solutions:
  • Check network connectivity: ping <server-ip>
  • Verify server is reachable: curl http://<server-ip>:<port>
  • Check firewall rules and network segmentation
  • Try using IP address instead of hostname

​
Advanced Configuration

​
SSH Tunneling

Securely connect to a remote server over SSH: 
# Create SSH tunnel
ssh -L 4096:localhost:4096 user@remote-server

# In another terminal, attach via tunnel
opencode attach http://localhost:4096

​
Reverse Proxy

Use a reverse proxy (nginx, Apache) for TLS and advanced routing: 
# nginx config
location /opencode/ {
  proxy_pass http://localhost:4096/;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
  proxy_set_header Host $host;
}
Then attach: 
opencode attach https://example.com/opencode/

serve

Start headless backend server

web

Start server with web interface

run

Run commands non-interactively

Network Setup

Configure network access