Portals — Agent Manager Docs

Overview

Portals let you access running sessions from a separate terminal — useful for monitoring agents on a remote machine, pairing, or keeping the main UI on one screen while interacting from another.

The portal communicates over a Unix socket at /tmp/agent-manager/portal.sock.

Usage

# Interactive picker — browse sessions, create new ones
agent-manager portal

# Connect directly to a known session
agent-manager portal <session-id>

# Static table of running sessions
agent-manager portal --list

bash

Interactive Picker

Use arrow keys to navigate, Enter to select
Choose "+ New Session" to start a fresh agent from the portal
Press Esc to exit

Once connected, the portal mirrors the session in real-time. Press Ctrl+C to disconnect and return to your shell.

Features

Full terminal mirroring — See the exact same output as the main app in real-time
Input forwarding — Type commands and interact with the agent as if you were in the main app
Scroll support — Mouse wheel, Ctrl+U/Ctrl+D, and PageUp/PageDown all work
Connection indicator — The main app shows a ⇄ icon in the header when a portal client is connected
Remote session creation — Start new agent sessions directly from the portal

Protocol

The portal uses newline-delimited JSON over a Unix domain socket.

Client to Server

Message Type	Description
`portal_list`	Request list of running sessions
`portal_subscribe`	Subscribe to a session's output
`portal_input`	Forward keyboard input to the session
`portal_unsubscribe`	Disconnect from current session
`portal_list_drivers`	Request available agent drivers
`portal_create_session`	Create a new agent session
`portal_scroll`	Scroll the terminal view

Server to Client

Message Type	Description
`portal_sessions`	List of running sessions
`portal_frame`	Screen content update
`portal_status`	Session status change
`portal_session_ended`	Session terminated
`portal_error`	Error message
`portal_drivers`	Available agent drivers
`portal_session_created`	New session created confirmation

Types

interface PortalSessionInfo {
  id: string;
  driverName: string;
  displayName: string;
  cwd: string;
  status: string;
}

interface PortalDriverInfo {
  name: string;
  displayName: string;
  installed: boolean;
}

// Client → Server
type PortalClientMsg =
  | { type: "portal_list" }
  | { type: "portal_subscribe"; sessionId: string }
  | { type: "portal_input"; data: string }
  | { type: "portal_unsubscribe" }
  | { type: "portal_list_drivers" }
  | { type: "portal_create_session"; driverName: string; cwd: string }
  | { type: "portal_scroll"; lines: number }

// Server → Client
type PortalServerMsg =
  | { type: "portal_sessions"; sessions: PortalSessionInfo[] }
  | { type: "portal_frame"; content: ScreenContent; cursor: { x: number; y: number }; cols: number; rows: number }
  | { type: "portal_status"; sessionId: string; status: string }
  | { type: "portal_session_ended"; sessionId: string }
  | { type: "portal_error"; message: string }
  | { type: "portal_drivers"; drivers: PortalDriverInfo[] }
  | { type: "portal_session_created"; sessionId: string }

TypeScript

interface PortalSessionInfo {
  id: string;
  driverName: string;
  displayName: string;
  cwd: string;
  status: string;
}

interface PortalDriverInfo {
  name: string;
  displayName: string;
  installed: boolean;
}

// Client → Server
type PortalClientMsg =
  | { type: "portal_list" }
  | { type: "portal_subscribe"; sessionId: string }
  | { type: "portal_input"; data: string }
  | { type: "portal_unsubscribe" }
  | { type: "portal_list_drivers" }
  | { type: "portal_create_session"; driverName: string; cwd: string }
  | { type: "portal_scroll"; lines: number }

// Server → Client
type PortalServerMsg =
  | { type: "portal_sessions"; sessions: PortalSessionInfo[] }
  | { type: "portal_frame"; content: ScreenContent; cursor: { x: number; y: number }; cols: number; rows: number }
  | { type: "portal_status"; sessionId: string; status: string }
  | { type: "portal_session_ended"; sessionId: string }
  | { type: "portal_error"; message: string }
  | { type: "portal_drivers"; drivers: PortalDriverInfo[] }
  | { type: "portal_session_created"; sessionId: string }