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

# Web Terminal

> Browser-based xterm.js terminal for agent sessions

The Web terminal plugin provides browser-based terminal access to agent sessions using xterm.js. Unlike iTerm2, it doesn't directly open terminals but generates URLs for the web dashboard to render terminal interfaces.

## Overview

The Web terminal plugin provides:

* Cross-platform terminal access (any OS)
* Browser-based xterm.js interface
* URL generation for dashboard terminal pages
* Session open state tracking
* No external dependencies
* Remote access capability

<Info>
  The Web terminal plugin is platform-agnostic and works on any operating system with a web browser.
</Info>

## How It Works

The Web terminal plugin is **passive** compared to iTerm2:

1. **URL Generation**: Creates dashboard URLs for terminal access
2. **State Tracking**: Tracks which sessions have been "opened"
3. **Console Logging**: Outputs URLs for manual access
4. **Dashboard Integration**: Web dashboard uses session runtime info for actual terminal connection

<Note>
  The plugin doesn't open browser windows automatically. It logs URLs that you can open manually or that the dashboard can detect.
</Note>

## Configuration

Add the Web terminal plugin to your `agent-orchestrator.yaml`:

```yaml theme={null}
plugins:
  terminal:
    name: web
    config:
      dashboardUrl: http://localhost:3000  # Optional
```

### Configuration Options

<ParamField path="dashboardUrl" type="string" default="http://localhost:3000">
  Base URL for the web dashboard. Used to generate terminal page URLs.

  **Examples:**

  * Local development: `http://localhost:3000`
  * Remote server: `https://orchestrator.example.com`
  * Custom port: `http://localhost:8080`
</ParamField>

## URL Format

The plugin generates two types of URLs:

### Single Session Terminal

```
http://localhost:3000/sessions/{session-id}/terminal
```

**Example:**

```bash theme={null}
ao open my-session-id
# Logs: [terminal-web] Session my-session-id terminal available at
#       http://localhost:3000/sessions/my-session-id/terminal
```

### All Sessions Page

```
http://localhost:3000/sessions
```

**Example:**

```bash theme={null}
ao open --all
# Logs: [terminal-web] 5 sessions available at
#       http://localhost:3000/sessions
```

## Dashboard Integration

The Web terminal plugin works with the Agent Orchestrator web dashboard:

**Dashboard Setup:**

1. Start the web server:
   ```bash theme={null}
   cd packages/web
   pnpm dev
   ```

2. Navigate to session page:
   ```
   http://localhost:3000/sessions/{session-id}/terminal
   ```

3. Dashboard uses xterm.js to connect to the session's runtime

**Connection Flow:**

1. Dashboard reads session metadata
2. Extracts `runtimeHandle` attachment info
3. Creates xterm.js terminal instance
4. Connects to runtime (e.g., tmux session via WebSocket proxy)

<Info>
  The dashboard handles the actual terminal connection. The plugin only tracks session open state and generates URLs.
</Info>

## Usage Examples

### Local Development

```yaml theme={null}
plugins:
  terminal:
    name: web
    # Uses default: http://localhost:3000
```

**Usage:**

```bash theme={null}
ao open my-session
# Open browser to: http://localhost:3000/sessions/my-session/terminal
```

### Remote Server

```yaml theme={null}
plugins:
  terminal:
    name: web
    config:
      dashboardUrl: https://orchestrator.example.com
```

**Usage:**

```bash theme={null}
ao open my-session
# Access from anywhere:
# https://orchestrator.example.com/sessions/my-session/terminal
```

### Custom Port

```yaml theme={null}
plugins:
  terminal:
    name: web
    config:
      dashboardUrl: http://localhost:8080
```

### Multi-Environment

```yaml theme={null}
projects:
  - name: local-dev
    plugins:
      terminal:
        name: web
        config:
          dashboardUrl: http://localhost:3000
  
  - name: staging
    plugins:
      terminal:
        name: web
        config:
          dashboardUrl: https://staging.orchestrator.example.com
  
  - name: production
    plugins:
      terminal:
        name: web
        config:
          dashboardUrl: https://orchestrator.example.com
```

## Session State Tracking

The plugin tracks which sessions have been "opened":

```typescript theme={null}
const openSessions = new Set<string>();

await terminal.openSession(session);
// Adds session.id to openSessions

const isOpen = await terminal.isSessionOpen(session);
// Returns: true if session.id in openSessions
```

<Note>
  State tracking is in-memory only. Restarting the orchestrator clears the open state.
</Note>

## Browser-Based Terminal

The web dashboard uses xterm.js for terminal rendering:

**Features:**

* Full ANSI color support
* Copy/paste (browser-dependent)
* Resizable terminal
* Mouse support
* Keyboard shortcuts
* UTF-8 character support

**Keyboard Shortcuts** (default xterm.js):

* Copy: `Ctrl+Shift+C` (or `Cmd+C` on macOS)
* Paste: `Ctrl+Shift+V` (or `Cmd+V` on macOS)
* Clear: `Ctrl+L`
* Search: `Ctrl+Shift+F`

<Info>
  Keyboard shortcuts may vary based on browser and xterm.js addons. Check the dashboard documentation for the full list.
</Info>

## Remote Access

The Web terminal plugin enables remote access to agent sessions:

**Scenario**: Agent runs on server, you access from laptop

1. **Deploy orchestrator on server**:
   ```bash theme={null}
   # On server (e.g., orchestrator.example.com)
   ao start
   cd packages/web && pnpm start  # Port 3000
   ```

2. **Configure plugin**:
   ```yaml theme={null}
   plugins:
     terminal:
       name: web
       config:
         dashboardUrl: https://orchestrator.example.com
   ```

3. **Access from anywhere**:
   ```bash theme={null}
   # On laptop
   ssh orchestrator.example.com
   ao open my-session
   # Open laptop browser to URL
   ```

<Warning>
  **Security Considerations:**

  * Use HTTPS for remote dashboards
  * Implement authentication (not included in base dashboard)
  * Use VPN or SSH tunneling for sensitive sessions
  * Restrict dashboard port access with firewall rules
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Dashboard not loading terminal">
    **Check dashboard is running:**

    ```bash theme={null}
    curl http://localhost:3000/api/health
    ```

    **Verify session exists:**

    ```bash theme={null}
    ao list
    # Should show session with RUNNING status
    ```

    **Check browser console:**

    * Open DevTools (F12)
    * Look for xterm.js errors
    * Verify WebSocket connection
  </Accordion>

  <Accordion title="Terminal shows 'Connection failed'">
    **Check runtime attachment info:**

    ```bash theme={null}
    cat ~/.ao/sessions/{session-id}/metadata.txt
    # Look for runtimeHandle data
    ```

    **Verify runtime is accessible:**

    * For tmux: `tmux ls` should show session
    * For docker: container should be running

    **Check dashboard logs:**

    ```bash theme={null}
    cd packages/web
    pnpm dev
    # Watch for connection errors
    ```
  </Accordion>

  <Accordion title="Wrong dashboard URL generated">
    Update config:

    ```yaml theme={null}
    plugins:
      terminal:
        name: web
        config:
          dashboardUrl: http://correct-url:3000
    ```

    Verify environment:

    ```bash theme={null}
    ao config show
    # Check terminal plugin config
    ```
  </Accordion>

  <Accordion title="Terminal not responding to keyboard input">
    **Browser focus issues:**

    * Click inside terminal area
    * Check browser doesn't have conflicting shortcuts
    * Try different browser

    **xterm.js not initialized:**

    * Refresh page
    * Check browser console for errors
    * Verify xterm.js loaded successfully
  </Accordion>

  <Accordion title="Can't copy/paste in terminal">
    **Browser security restrictions:**

    * Use keyboard shortcuts: `Ctrl+Shift+C/V`
    * Some browsers require HTTPS for clipboard access
    * Check browser clipboard permissions

    **Alternative:**
    Use iTerm2 plugin for native copy/paste if on macOS.
  </Accordion>
</AccordionGroup>

## Comparison with iTerm2

| Feature | Web | iTerm2 |
| - | - | - |
| Platform | Any OS | macOS only |
| Setup | Browser only | iTerm2 required |
| Remote access | ✅ Native | ❌ Local only |
| Performance | Good (JavaScript) | Excellent (native) |
| Copy/paste | Browser-dependent | Native |
| Customization | CSS/JS | iTerm2 profiles |
| Tab management | Browser tabs | Native tabs |
| Keyboard shortcuts | xterm.js | iTerm2 bindings |
| Authentication | Custom | OS-level |

## Use Cases

<AccordionGroup>
  <Accordion title="Remote orchestrator on cloud server">
    Perfect for:

    * CI/CD server with orchestrator
    * Shared development server
    * Team collaboration on agent sessions
    * Accessing sessions from any device
  </Accordion>

  <Accordion title="Cross-platform development">
    Perfect for:

    * Linux development machine
    * Windows + WSL
    * Docker-based workflows
    * Any non-macOS environment
  </Accordion>

  <Accordion title="Demo or presentation">
    Perfect for:

    * Screen sharing agent sessions
    * Client demonstrations
    * Training sessions
    * Recording terminal sessions
  </Accordion>

  <Accordion title="Browser-based workflows">
    Perfect for:

    * Chromebook or thin client access
    * Tablet/mobile access (with caveats)
    * Kiosk mode displays
    * Embedded terminal in other web apps
  </Accordion>
</AccordionGroup>

## Source Code

View the plugin source:

* Package: `@composio/ao-plugin-terminal-web`
* Location: `packages/plugins/terminal-web/src/index.ts`
* Dashboard: `packages/web/app/sessions/[id]/terminal/page.tsx`

## Related

* [iTerm2 Terminal](/plugins/terminal/iterm2) - macOS native terminal alternative
* [Web Dashboard](/cli/dashboard) - Dashboard setup and configuration
* [Terminal Plugin Interface](/api/terminal) - Technical interface
* [xterm.js Documentation](https://xtermjs.org/) - Official xterm.js docs


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.