> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/hosenur/portal/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get OpenCode Portal running in under 5 minutes

## Prerequisites

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

<Steps>
  <Step title="Install Bun">
    Portal works best with Bun. Node.js may have rough edges.

    ```bash theme={null}
    # macOS and Linux
    curl -fsSL https://bun.sh/install | bash

    # Windows
    powershell -c "irm bun.sh/install.ps1|iex"
    ```

    Verify installation:

    ```bash theme={null}
    bun --version
    ```
  </Step>

  <Step title="Install OpenCode">
    Portal requires a running OpenCode server to connect to.

    ```bash theme={null}
    # Using Bun (recommended)
    bun install -g opencode

    # Using Homebrew (macOS)
    brew install sst/tap/opencode
    ```

    Verify installation:

    ```bash theme={null}
    opencode --version
    ```
  </Step>
</Steps>

## Quick start with bunx

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

<Steps>
  <Step title="Navigate to your project">
    Open your terminal and navigate to the project directory where you want to use OpenCode.

    ```bash theme={null}
    cd /path/to/your/project
    ```
  </Step>

  <Step title="Run Portal">
    Start Portal with a single command:

    ```bash theme={null}
    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`

    <Note>
      The first run may take a moment as Bun downloads and caches the Portal package.
    </Note>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## Installation (global)

For regular use, install Portal globally:

```bash theme={null}
bun install -g openportal
```

Now you can run it from any directory:

```bash theme={null}
cd ~/my-project
openportal
```

## CLI commands

Portal includes several commands for managing instances:

### Start OpenCode + Portal

```bash theme={null}
openportal
```

Starts both the OpenCode server and Portal web UI.

### Start only OpenCode server

```bash theme={null}
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

```bash theme={null}
openportal list
# or
openportal ls
```

Shows all active OpenCode instances with their ports, directories, and PIDs.

### Stop instances

```bash theme={null}
openportal stop
```

Interactively select instances to stop.

### Clean up stale entries

```bash theme={null}
openportal clean
```

Removes instance entries for processes that are no longer running.

## CLI options

Customize Portal's behavior with command-line options:

```bash theme={null}
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

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Session management" icon="messages">
    Learn how to create, organize, and delete sessions
  </Card>

  <Card title="Remote access" icon="globe">
    Set up secure remote access via Tailscale or VPN
  </Card>

  <Card title="Configuration" icon="cog">
    Customize Portal settings and preferences
  </Card>

  <Card title="Deployment" icon="rocket">
    Deploy Portal to a VPS for always-on access
  </Card>
</CardGroup>