Local Setup

Get Portal running on your local machine in under a minute.

Prerequisites

You need OpenCode installed on your system. Install it using one of these methods:


# Using curl (macOS/Linux)
curl -fsSL https://opencode.ai/install | bash
 
# Using bun
bun install -g opencode
 
# Using Homebrew (macOS)
brew install sst/tap/opencode

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

Quick Start

The fastest way to get started:


# Navigate to your project directory
cd /path/to/your/project
 
# Run Portal with bunx
bunx openportal

Portal will automatically:

Find available ports (defaults: 3000 for Web UI, 4000 for OpenCode)
Start the OpenCode server
Start the Web UI
Display the access URLs

Global Installation

For frequent use, install Portal globally:


bun install -g openportal

Then run it from any project directory:


cd /path/to/your/project
openportal

Commands

Default Command

Start both OpenCode server and Web UI:


openportal                    # Start in current directory
openportal .                  # Same as above
openportal /path/to/project   # Start in specific directory

Run Command

Start only the OpenCode server (no Web UI):


openportal run                        # Current directory
openportal run -d ./my-project        # Specific directory

Stop Command

Stop running instances:


openportal stop               # Stop instance for current directory
openportal stop --name myapp  # Stop instance by name

List Command

List all running instances:


openportal list
openportal ls                 # Shorthand

Clean Command

Remove stale entries from the config:


openportal clean

CLI Options


openportal [command] [options]
 
Options:
  -h, --help              Show help message
  -d, --directory <path>  Working directory (default: current directory)
  -p, --port <port>       Web UI port (default: 3000, auto-finds if busy)
  --opencode-port <port>  OpenCode server port (default: 4000, auto-finds if busy)
  --hostname <host>       Hostname to bind (default: 0.0.0.0)
  --name <name>           Instance name (default: directory name)

Examples


# Use custom ports
openportal --port 8080 --opencode-port 5000
 
# Bind to specific hostname
openportal --hostname 127.0.0.1
 
# Give the instance a custom name
openportal --name my-project
 
# Start OpenCode only with custom port
openportal run --opencode-port 5000
 
# Specify a different project directory
openportal -d /path/to/other/project

Troubleshooting

OpenCode not found

If you see an error about OpenCode, install it first:


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

Port already in use

Portal automatically finds available ports. If you want specific ports and they’re in use, specify different ones:


openportal --port 3001 --opencode-port 4001

Instance already running

If Portal detects an existing instance for the directory, it will show the existing instance info instead of starting a new one. Use openportal stop first if you want to restart.