Skip to main content

​
Prerequisites

Before you begin, make sure you have the following installed:
1

Install Bun

Portal works best with Bun. Node.js may have rough edges.
# macOS and Linux
curl -fsSL https://bun.sh/install | bash

# Windows
powershell -c "irm bun.sh/install.ps1|iex"
Verify installation:
bun --version
2

Install OpenCode

Portal requires a running OpenCode server to connect to.
# Using Bun (recommended)
bun install -g opencode

# Using Homebrew (macOS)
brew install sst/tap/opencode
Verify installation:
opencode --version

​
Quick start with bunx

The fastest way to run Portal is using bunx - no installation required.
1

Navigate to your project

Open your terminal and navigate to the project directory where you want to use OpenCode.
cd /path/to/your/project
2

Run Portal

Start Portal with a single command:
bunx openportal
This will:
  • Start the OpenCode server (default port: 4000)
  • Start the Portal web UI (default port: 3000)
  • Automatically find available ports if defaults are busy
  • Open your browser to http://localhost:3000
The first run may take a moment as Bun downloads and caches the Portal package.
3

Select your instance

When Portal loads, you’ll see the instance selector. Click on your running instance to connect.If you see “No instances found”, make sure OpenCode started successfully. Check the terminal output for errors.
4

Create your first session

Once connected:
  1. Click the + button in the sidebar to create a new session
  2. Type your message in the chat input (e.g., “Show me the project structure”)
  3. Press Send or hit Enter
  4. Watch as OpenCode responds with AI-powered assistance
You can mention files using @ - just type @ followed by a filename and select from the autocomplete popup.
Portal binds to 0.0.0.0 by default, making it accessible on your local network. For production deployments, use a VPN like Tailscale or configure proper authentication.

​
Installation (global)

For regular use, install Portal globally: 
bun install -g openportal
Now you can run it from any directory: 
cd ~/my-project
openportal

​
CLI commands

Portal includes several commands for managing instances:

​
Start OpenCode + Portal

openportal
Starts both the OpenCode server and Portal web UI.

​
Start only OpenCode server

openportal run
Starts just the OpenCode server without the web UI. Useful if you’re running Portal separately or using the official OpenCode UI.

​
List running instances

openportal list
# or
openportal ls
Shows all active OpenCode instances with their ports, directories, and PIDs.

​
Stop instances

openportal stop
Interactively select instances to stop.

​
Clean up stale entries

openportal clean
Removes instance entries for processes that are no longer running.

​
CLI options

Customize Portal’s behavior with command-line options: 
openportal [command] [options]
OptionDescriptionDefault
-h, --helpShow help message-
-d, --directory <path>Working directoryCurrent directory
-p, --port <port>Portal web UI port3000 (auto-finds if busy)
--opencode-port <port>OpenCode server port4000 (auto-finds if busy)
--hostname <host>Hostname to bind0.0.0.0
--name <name>Instance nameDirectory name
--dockerRun OpenCode in Dockerfalse

​
Examples

# Start Portal on a custom port
openportal --port 8080

# Start OpenCode in a specific directory
openportal run -d ~/projects/my-app

# Run OpenCode in Docker (requires Docker installed)
openportal --docker

# Combine multiple options
openportal -d ~/work/api --port 5000 --name api-project

​
Docker mode

Run OpenCode in a Docker container for isolated environments: 
openportal --docker
This requires Docker to be installed and running. Portal will:
  • Pull the OpenCode Docker image (if not cached)
  • Mount your project directory into the container
  • Start OpenCode inside the container
  • Connect Portal to the containerized instance
You can customize the Docker image: 
OPENCODE_DOCKER_IMAGE=ghcr.io/anomalyco/opencode:latest openportal --docker

​
Using Portal features

​
Chatting with OpenCode

The chat interface supports rich interactions:
  • Text messages: Ask questions, request code changes, or give instructions
  • File mentions: Use @filename to reference files (autocomplete available)
  • Multi-line input: Shift+Enter for new lines, Enter to send
  • Tool visibility: See when OpenCode reads, writes, or edits files

​
Viewing git diffs

Click the Diff icon in the sidebar to see all uncommitted changes:
  • Unified diff view with syntax highlighting
  • File-by-file breakdown
  • Line-level additions and deletions
  • Refresh button to update changes

​
Switching models

Click the model selector in the chat header to choose from available AI models. Portal displays all configured providers and their models.

​
Managing instances

Click the instance name in the sidebar to view and switch between running instances. Each instance shows:
  • Project name and directory
  • Port number
  • Running status indicator

​
Troubleshooting

​
Port already in use

Portal automatically finds available ports if defaults are busy. To manually specify: 
openportal --port 8080 --opencode-port 4001

​
“No instances found”

This means the OpenCode server didn’t start. Check:
  1. OpenCode is installed: opencode --version
  2. No permission errors in terminal output
  3. The directory is accessible and not restricted

​
Connection errors

If Portal can’t connect to OpenCode:
  1. Verify OpenCode is running: openportal list
  2. Check firewall settings aren’t blocking ports
  3. Try restarting: openportal stop then openportal

​
Bun vs Node.js issues

Portal is optimized for Bun. If using Node.js, you may encounter:
  • Slower startup times
  • Module resolution issues
  • Missing dependencies
Switch to Bun for the best experience.

​
Next steps

Session management

Learn how to create, organize, and delete sessions

Remote access

Set up secure remote access via Tailscale or VPN

Configuration

Customize Portal settings and preferences

Deployment

Deploy Portal to a VPS for always-on access

Build docs developers (and LLMs) love

Get started for freeTalk to us