Skip to main content

​
What is OpenPortal CLI?

OpenPortal CLI is a command-line tool that launches OpenCode with an integrated web UI, making it easy to interact with OpenCode through a browser interface. It manages both the OpenCode server and the web UI as separate processes or Docker containers.

​
Architecture

OpenPortal operates with a dual-server architecture:

​
Components

  1. OpenCode Server - The core AI coding assistant that processes requests
  2. Web UI Server - A web interface for interacting with OpenCode
  3. Configuration Manager - Stores instance state in ~/.portal.json

​
Deployment Modes

OpenPortal supports two deployment modes:

​
Process Mode (Default)

Both OpenCode and the Web UI run as local processes on your machine. This is the default and fastest mode for local development. 
openportal

​
Docker Mode

OpenCode runs in a Docker container while the Web UI runs locally. This mode provides better isolation and consistency across different environments. 
openportal --docker

​
Instance Management

OpenPortal maintains a configuration file at ~/.portal.json that tracks all running instances. Each instance includes:
  • Unique identifier
  • Instance name
  • Working directory
  • Port assignments (Web UI and OpenCode)
  • Process IDs or Container IDs
  • Deployment mode (process or docker)
  • Startup timestamp

​
Port Allocation

By default, OpenPortal automatically finds available ports:
  • Web UI: Port 3000 (customizable with -p or --port)
  • OpenCode Server: Port 4000 (customizable with --opencode-port)
If the default ports are in use, OpenPortal automatically selects the next available port.

​
Quick Start

​
Start OpenPortal with Web UI

openportal
This starts both OpenCode and the Web UI in the current directory.

​
Start Only OpenCode Server

openportal run
This starts only the OpenCode server without the Web UI, useful when you want to connect your own client.

​
View Running Instances

openportal list

​
Stop an Instance

openportal stop

​
Configuration File

OpenPortal stores its configuration at ~/.portal.json. The file contains: 
{
  "instances": [
    {
      "id": "abc123",
      "name": "my-project",
      "directory": "/home/user/my-project",
      "port": 3000,
      "opencodePort": 4000,
      "hostname": "0.0.0.0",
      "opencodePid": 12345,
      "webPid": 12346,
      "startedAt": "2026-03-03T10:30:00.000Z",
      "instanceType": "process",
      "containerId": null
    }
  ]
}
Do not manually edit ~/.portal.json while instances are running. Use the CLI commands to manage instances instead.

​
Environment Variables

​
OPENCODE_DOCKER_IMAGE
string
default:"ghcr.io/anomalyco/opencode:1.1.3"
Docker image to use when running in Docker mode
​
DOCKER_HOST
string
default:"platform-specific"
Docker daemon connection string (e.g., tcp://localhost:2375, unix:///var/run/docker.sock)
​
DEBUG
boolean
default:"false"
Enable debug logging for Docker operations

​
Directory Behavior

OpenPortal uses the working directory as the root for OpenCode operations. You can specify the directory in several ways: 
# Use current directory
openportal

# Specify directory as first argument
openportal /path/to/project

# Use current directory shorthand
openportal .

# Use --directory flag
openportal --directory /path/to/project

# Short form
openportal -d /path/to/project

​
Instance Naming

By default, OpenPortal names instances after the directory basename. You can specify a custom name: 
openportal --name my-custom-name
Instance names help identify multiple instances when using openportal list.

​
Docker Mode Details

When running in Docker mode (--docker):

​
Mount Behavior

  • Your working directory is mounted into the container at the same path
  • The container runs with read-write access to the mounted directory
  • Container is configured with AutoRemove: true for automatic cleanup

​
Security Validations

OpenPortal prevents mounting sensitive system directories: Unix/Linux:
  • /, /etc, /usr, /bin, /sbin, /lib, /lib64, /boot, /dev, /proc, /sys, /run, /var/run, /root
Windows:
  • C:/, C:/Windows, C:/Program Files, C:/Program Files (x86), C:/ProgramData

​
Container Lifecycle

# Start with Docker
openportal --docker
# Container is created and started

# Stop the instance
openportal stop
# Container is stopped and automatically removed

​
Common Workflows

​
Development Workflow

# Start OpenPortal in your project
cd /path/to/project
openportal

# Access Web UI at http://localhost:3000
# Work with OpenCode through the browser

# Stop when done
openportal stop

​
Multiple Projects

# Start instance for project A
cd /path/to/project-a
openportal --name project-a

# Start instance for project B
cd /path/to/project-b
openportal --name project-b

# List all instances
openportal list

# Stop specific instance
cd /path/to/project-a
openportal stop

​
Docker Deployment

# Start with Docker for consistency
openportal --docker

# Or start only OpenCode in Docker
openportal run --docker

​
Next Steps

Commands

Explore all available commands

Options

Learn about command-line options

Build docs developers (and LLMs) love

Get started for freeTalk to us