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.

Local Setup

On this page