Network Configuration

OpenCode supports enterprise network environments with proxy servers, custom CA certificates, and local network discovery via mDNS (Bonjour).

Proxy Configuration

OpenCode respects standard HTTP proxy environment variables for all outbound connections to LLM providers, APIs, and external services.

Basic Setup

export HTTPS_PROXY=https://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1
opencode

export HTTP_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1
opencode

You must set NO_PROXY=localhost,127.0.0.1 to prevent the TUI from routing local server connections through the proxy. This would create a routing loop and break the application.

Environment Variables

HTTPS_PROXY

string

HTTPS proxy URL (recommended for encrypted proxy connections).

HTTP_PROXY

string

HTTP proxy URL (fallback if HTTPS_PROXY not set).

NO_PROXY

string

Comma-separated list of hosts to bypass proxy. Must include localhost,127.0.0.1 for OpenCode to function.

ALL_PROXY

string

Generic proxy for all protocols (least specific, use HTTPS_PROXY/HTTP_PROXY when possible).

Proxy Authentication

Include credentials directly in the proxy URL:

export HTTPS_PROXY=http://username:password@proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1

Security Best Practices:

Never hardcode passwords in scripts committed to version control
Use environment variable substitution: http://${PROXY_USER}:${PROXY_PASS}@proxy.example.com:8080
Consider using an LLM Gateway for advanced auth (NTLM, Kerberos)
Rotate credentials regularly

Advanced Authentication Methods

For proxies requiring NTLM, Kerberos, or certificate-based auth:

Deploy an LLM Gateway

Use tools like LiteLLM Proxy or Kong that support advanced authentication.

# LiteLLM example
docker run -p 4000:4000 \
  -e PROXY_HOST=proxy.example.com \
  -e PROXY_PORT=8080 \
  ghcr.io/berriai/litellm:latest

Configure OpenCode to use the gateway

Point OpenCode to your gateway instead of directly to LLM providers:

opencode.json

{
  "providers": {
    "openai": {
      "baseURL": "http://localhost:4000/openai"
    }
  }
}

No proxy needed for OpenCode

OpenCode connects to the gateway on localhost, bypassing the proxy entirely.

Proxy Debugging

Verify proxy connectivity:

curl -x $HTTPS_PROXY https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

env | grep -i proxy
# Should show:
# HTTPS_PROXY=https://proxy.example.com:8080
# NO_PROXY=localhost,127.0.0.1

curl http://localhost:4096/global/health
# Should work WITHOUT going through proxy

Common Proxy Issues

TUI won't connect to server

Cause: NO_PROXY not set, routing localhost through proxy.Fix:

export NO_PROXY=localhost,127.0.0.1

SSL certificate verification fails

Cause: Proxy performs SSL interception with custom CA.Fix: Add custom CA certificate (see Custom Certificates section).

Proxy authentication errors

Cause: Special characters in password not URL-encoded.Fix: URL-encode password:

# Password: p@ssw0rd! → p%40ssw0rd%21
export HTTPS_PROXY=http://user:p%40ssw0rd%21@proxy.example.com:8080

Custom CA Certificates

Enterprise networks often use custom Certificate Authorities (CAs) for SSL/TLS inspection. Configure OpenCode to trust these certificates.

Single Certificate File

export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
opencode

This variable is read by Node.js/Bun’s TLS stack and applies to:

Proxy connections (if using HTTPS proxy)
Direct HTTPS requests to LLM providers
Any other HTTPS traffic from OpenCode

Multiple Certificates

Concatenate multiple CA certificates into one file:

cat ca-root.pem ca-intermediate.pem > combined-ca.pem
export NODE_EXTRA_CA_CERTS=/path/to/combined-ca.pem

Certificate Locations

Common enterprise CA certificate locations:

C:\ProgramData\Company\Certificates\ca.crt
# Convert to PEM if needed:
certutil -encode ca.crt ca.pem

# Export from Keychain
security find-certificate -a -p \
  -c "Corporate Root CA" \
  /Library/Keychains/System.keychain > ca.pem

# System-wide CA bundle (varies by distro)
/etc/ssl/certs/ca-certificates.crt  # Debian/Ubuntu
/etc/pki/tls/certs/ca-bundle.crt    # RHEL/CentOS

Persistent Configuration

Add to your shell profile for persistence:

export NODE_EXTRA_CA_CERTS="$HOME/.config/opencode/corporate-ca.pem"
export HTTPS_PROXY="https://proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1"

setx NODE_EXTRA_CA_CERTS "C:\Users\YourName\.config\opencode\ca.pem"
setx HTTPS_PROXY "https://proxy.example.com:8080"
setx NO_PROXY "localhost,127.0.0.1"

Certificate Verification Issues

Troubleshooting SSL Errors

CERT_HAS_EXPIRED

Symptoms: certificate has expired errors.Diagnosis:

openssl s_client -connect api.openai.com:443 -proxy proxy.example.com:8080
# Check "Verify return code"

Fix: Update your CA certificate file or contact IT.

UNABLE_TO_VERIFY_LEAF_SIGNATURE

Symptoms: unable to verify the first certificate.Cause: Missing intermediate CA certificate.Fix: Ensure your CA file includes the full chain:

cat root-ca.pem intermediate-ca.pem > full-chain.pem
export NODE_EXTRA_CA_CERTS=/path/to/full-chain.pem

SELF_SIGNED_CERT_IN_CHAIN

Symptoms: self signed certificate in certificate chain.Fix: Add the self-signed root CA to NODE_EXTRA_CA_CERTS.

mDNS Service Discovery

mDNS (Multicast DNS), also known as Bonjour or Zeroconf, enables automatic discovery of OpenCode servers on the local network without manual IP configuration.

How mDNS Works

Server publishes service

When --mdns is enabled, the OpenCode server announces itself on the local network:

Service Name: opencode-4096._http._tcp.local.
Hostname: opencode.local (or custom via --mdns-domain)
Port: 4096

Clients discover server

mDNS-aware clients (web browsers, mobile apps) query for _http._tcp.local. services and receive server details.

Automatic connection

Clients connect to http://opencode.local:4096 without knowing the IP address.

Enable mDNS

opencode serve \
  --hostname 0.0.0.0 \
  --port 4096 \
  --mdns

mDNS requires:

--hostname set to a non-loopback address (not 127.0.0.1 or localhost)
UDP port 5353 accessible on the local network
mDNS responder running on the host (avahi-daemon on Linux, built-in on macOS/Windows)

Custom Domain Name

opencode serve \
  --hostname 0.0.0.0 \
  --port 4096 \
  --mdns \
  --mdns-domain mycompany-ai.local

Clients can then connect to http://mycompany-ai.local:4096.

mDNS Implementation

OpenCode uses the bonjour-service library:

// From packages/opencode/src/server/mdns.ts
import { Bonjour } from "bonjour-service";

const bonjour = new Bonjour();
const service = bonjour.publish({
  name: `opencode-${port}`,
  type: "http",
  host: "opencode.local",
  port: 4096,
  txt: { path: "/" }
});

Discovery from Clients

const Bonjour = require('bonjour-service');
const bonjour = new Bonjour();

bonjour.find({ type: 'http' }, (service) => {
  if (service.name.startsWith('opencode-')) {
    console.log(`Found OpenCode at ${service.host}:${service.port}`);
  }
});

import socket
from zeroconf import ServiceBrowser, Zeroconf

class OpenCodeListener:
    def add_service(self, zeroconf, type, name):
        info = zeroconf.get_service_info(type, name)
        print(f"Found OpenCode at {info.server}:{info.port}")

zeroconf = Zeroconf()
browser = ServiceBrowser(zeroconf, "_http._tcp.local.", OpenCodeListener())

# List all HTTP services
avahi-browse -rt _http._tcp

# macOS alternative
dns-sd -B _http._tcp

mDNS Platform Support

macOS
Linux
Windows
Docker/Containers

Built-in Bonjour support. Works out of the box.

# Test mDNS resolution
ping opencode.local

Requires Avahi daemon:

# Debian/Ubuntu
sudo apt install avahi-daemon avahi-utils
sudo systemctl enable avahi-daemon
sudo systemctl start avahi-daemon

# RHEL/CentOS
sudo yum install avahi avahi-tools
sudo systemctl enable avahi-daemon
sudo systemctl start avahi-daemon

Bonjour included with iTunes or install standalone:Download Bonjour Print ServicesOr install via Chocolatey:

choco install bonjour

mDNS in containers requires host networking:

docker run --network host \
  -e OPENCODE_PORT=4096 \
  opencode/opencode serve --hostname 0.0.0.0 --mdns

--network host bypasses container networking, making mDNS work but reducing isolation.

Security Considerations

mDNS Exposes Your Server to the Local Network

Any device on the same network can discover the server
Always use OPENCODE_SERVER_PASSWORD when enabling mDNS
Consider firewall rules to restrict access to trusted subnets
mDNS should not be used on untrusted networks (coffee shops, airports)

# Secure mDNS server
export OPENCODE_SERVER_PASSWORD="strong-password-here"
opencode serve --hostname 0.0.0.0 --mdns --port 4096

Firewall Configuration

Required Ports

4096

TCP

default:"yes"

Default OpenCode HTTP server port. Customize with --port.

5353

UDP

default:"no"

mDNS/Bonjour service discovery. Only needed if --mdns is enabled.

Firewall Rules

# Allow OpenCode server
sudo iptables -A INPUT -p tcp --dport 4096 -j ACCEPT

# Allow mDNS (if enabled)
sudo iptables -A INPUT -p udp --dport 5353 -j ACCEPT

sudo ufw allow 4096/tcp comment 'OpenCode server'
sudo ufw allow 5353/udp comment 'OpenCode mDNS'

# Add to /etc/pf.conf
pass in proto tcp to any port 4096
pass in proto udp to any port 5353

# Reload
sudo pfctl -f /etc/pf.conf

# Allow inbound
New-NetFirewallRule -DisplayName "OpenCode Server" `
  -Direction Inbound -Protocol TCP -LocalPort 4096 -Action Allow

New-NetFirewallRule -DisplayName "OpenCode mDNS" `
  -Direction Inbound -Protocol UDP -LocalPort 5353 -Action Allow

Network Architecture Patterns

Pattern 1: Local Development (Default)

┌─────────────────┐
│   Developer     │
│    Machine      │
│                 │
│  ┌───────────┐  │
│  │    TUI    │  │
│  └─────┬─────┘  │
│        │ HTTP   │
│        ↓        │
│  ┌───────────┐  │
│  │  Server   │  │
│  │ :4096     │  │
│  └─────┬─────┘  │
│        │ HTTPS  │
└────────┼────────┘
         ↓
    LLM Provider

No proxy, no mDNS
Localhost only
Fastest, most secure

Pattern 2: Corporate Network with Proxy

┌─────────────────┐
│   Developer     │
│    Machine      │
│                 │
│  ┌───────────┐  │      ┌──────────┐
│  │  Server   │  │──────┤  Proxy   │
│  │ :4096     │  │HTTPS │ :8080    │
│  └───────────┘  │      └────┬─────┘
│                 │           │ HTTPS
└─────────────────┘           ↓
                         LLM Provider

HTTPS_PROXY configured
NO_PROXY=localhost
Custom CA certificate if proxy intercepts SSL

Pattern 3: Remote Server with mDNS

      Local Network
┌──────────────────────────┐
│                          │
│  ┌──────────────────┐    │
│  │  Remote Server   │    │
│  │                  │    │
│  │  ┌────────────┐  │    │
│  │  │   Server   │  │    │
│  │  │ :4096      │  │    │
│  │  └──────┬─────┘  │    │
│  │         │ mDNS   │    │
│  └─────────┼────────┘    │
│            ↓             │
│   ┌────────────────┐     │
│   │ Client Device  │     │
│   │ (Laptop/Phone) │     │
│   └────────────────┘     │
│                          │
└──────────────────────────┘

Server on dedicated machine
--hostname 0.0.0.0 --mdns
Password authentication required
Clients auto-discover via mDNS

Pattern 4: Containerized Deployment

┌────────────────────────────┐
│      Docker Host           │
│                            │
│  ┌──────────────────────┐  │
│  │  OpenCode Container  │  │
│  │                      │  │
│  │    Server :4096      │  │
│  └──────────────────────┘  │
│            │               │
│            │ Bridge Network│
│            ↓               │
│  ┌──────────────────────┐  │
│  │  Reverse Proxy       │  │
│  │  (Nginx/Caddy)       │  │
│  │  :443 (HTTPS)        │  │
│  └──────────┬───────────┘  │
└─────────────┼──────────────┘
              ↓
         Internet

Expose via reverse proxy with SSL
Internal container networking
Auth + CORS configured

Best Practices

Always set NO_PROXY

Include localhost,127.0.0.1 in NO_PROXY when using proxies to prevent TUI connection failures.

Use HTTPS proxies

Prefer HTTPS_PROXY over HTTP_PROXY for encrypted proxy connections.

Secure mDNS servers

Always set OPENCODE_SERVER_PASSWORD when using --mdns or --hostname 0.0.0.0.

Test certificates

Verify NODE_EXTRA_CA_CERTS with openssl s_client before running OpenCode.

Next Steps

Server Architecture

Learn about the OpenCode server API and architecture.

Troubleshooting

Diagnose network connectivity issues.

Windows WSL Setup

Optimal network setup for Windows users.

​Proxy Configuration

​Basic Setup

​Environment Variables

​Proxy Authentication

​Advanced Authentication Methods

​Proxy Debugging

​Custom CA Certificates

​Single Certificate File

​Multiple Certificates

​Certificate Locations

​Persistent Configuration

​Certificate Verification Issues

​mDNS Service Discovery

​How mDNS Works

​Enable mDNS

​Custom Domain Name

​mDNS Implementation

​Discovery from Clients

​mDNS Platform Support

​Security Considerations

​Firewall Configuration

​Required Ports

​Firewall Rules

​Network Architecture Patterns

​Pattern 1: Local Development (Default)

​Pattern 2: Corporate Network with Proxy

​Pattern 3: Remote Server with mDNS

​Pattern 4: Containerized Deployment

​Best Practices

Always set NO_PROXY

Use HTTPS proxies

Secure mDNS servers

Test certificates

​Next Steps

Server Architecture

Troubleshooting

Windows WSL Setup

Proxy Configuration

Basic Setup

Environment Variables

Proxy Authentication

Advanced Authentication Methods

Proxy Debugging

Custom CA Certificates

Single Certificate File

Multiple Certificates

Certificate Locations

Persistent Configuration

Certificate Verification Issues

mDNS Service Discovery

How mDNS Works

Enable mDNS

Custom Domain Name

mDNS Implementation

Discovery from Clients

mDNS Platform Support

Security Considerations

Firewall Configuration

Required Ports

Firewall Rules

Network Architecture Patterns

Pattern 1: Local Development (Default)

Pattern 2: Corporate Network with Proxy

Pattern 3: Remote Server with mDNS

Pattern 4: Containerized Deployment

Best Practices

Next Steps