Local Installation

Install and run OpenCode Portal on your local machine

OpenCode Portal provides a mobile-first web UI for OpenCode. This guide covers local installation and setup.

Prerequisites

Before installing OpenCode Portal, you need to have OpenCode installed on your system.

1. Install OpenCode

   Install OpenCode using one of the following methods:

   Bun

   bun install -g opencode
   
2. Install OpenPortal

   You can either install OpenPortal globally or run it directly with bunx.

   Global Installation

   Bun (Recommended)

   bun install -g openportal
   

   OpenPortal works best when paired with Bun. Node.js may have some rough edges.

   Run Without Installing

   Alternatively, use bunx to run OpenPortal without installing:

   bunx openportal
   
3. Start OpenPortal

   Navigate to your project directory and start OpenPortal:

   cd /path/to/your/project
   openportal
   

   This will:

   • Start the OpenCode server (default port: 4000)
   • Start the web UI (default port: 3000)
   • Automatically find available ports if defaults are busy

   You should see output like:

   Starting OpenPortal...
     Name: your-project
     Directory: /path/to/your/project
     Web UI Port: 3000
     OpenCode Port: 4000
     Hostname: 0.0.0.0
     Mode: Process
   
   ✅ OpenPortal started!
      OpenCode PID: 12345
      Web UI PID: 12346
   
   📱 Access OpenPortal at http://localhost:3000
   🔧 OpenCode API at http://localhost:4000
   
4. Access the Web UI

   Open your browser and navigate to:

   http://localhost:3000
   

   You can now interact with OpenCode through the web interface.

CLI Commands

OpenPortal provides several commands for managing instances:

Start OpenCode + Web UI

openportal

Starts both the OpenCode server and the web UI.

Start OpenCode Server Only

openportal run

Starts only the OpenCode server without the web UI.

Stop Running Instances

openportal stop

Stops all running OpenPortal instances in the current directory.

List Running Instances

openportal list
# or
openportal ls

Displays all running OpenPortal instances with their status.

Clean Stale Entries

openportal clean

Removes stale configuration entries for stopped instances.

CLI Options

Customize OpenPortal behavior with these options:

Directory Options

# Specify working directory
openportal -d /path/to/project
openportal --directory /path/to/project

# Or pass directory as argument
openportal /path/to/project

Port Configuration

# Custom Web UI port
openportal -p 8080
openportal --port 8080

# Custom OpenCode server port
openportal --opencode-port 5000

If the specified ports are busy, OpenPortal will automatically find available ports.

Network Configuration

# Bind to specific hostname
openportal --hostname 127.0.0.1

# Default is 0.0.0.0 (all interfaces)

Instance Naming

# Set custom instance name
openportal --name my-instance

# Default is the directory name

Help

openportal -h
openportal --help

Usage Examples

Basic Usage

# Start in current directory
openportal

# Start in specific directory
openportal /path/to/my-project

Custom Ports

# Use custom web UI port
openportal --port 8080

# Use both custom ports
openportal --port 8080 --opencode-port 5000

Server Only Mode

# Start only OpenCode server
openportal run

# Server only with custom port
openportal run --opencode-port 5000

# Server only in specific directory
openportal run -d ./my-project

Instance Management

# List all running instances
openportal list

# Stop instance in current directory
openportal stop

# Stop specific instance by name
openportal stop --name my-instance

# Clean up stale entries
openportal clean

Troubleshooting

Port Already in Use

If the default ports are already in use, OpenPortal will automatically find available ports. You can also specify custom ports:

openportal --port 8080 --opencode-port 5000

OpenCode Not Found

If you see an error about OpenCode not being found, ensure it’s installed globally:

# Check if OpenCode is installed
which opencode

# Install if missing
bun install -g opencode

Instance Already Running

If OpenPortal detects an instance already running for the directory, it will display the existing instance information instead of starting a new one.

To stop the existing instance:

openportal stop

Web Server Not Found

If you installed OpenPortal globally and see “Web server not found” errors, try reinstalling:

bun install -g openportal