Quickstart

Get OpenCode Portal running in under 5 minutes

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]

Option	Description	Default
-h, --help	Show help message	-
-d, --directory <path>	Working directory	Current directory
-p, --port <port>	Portal web UI port	3000 (auto-finds if busy)
--opencode-port <port>	OpenCode server port	4000 (auto-finds if busy)
--hostname <host>	Hostname to bind	0.0.0.0
--name <name>	Instance name	Directory name
--docker	Run OpenCode in Docker	false

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