Skip to main content
Maestro includes a built-in web server that provides HTTP and WebSocket APIs for remote access to your AI coding sessions from mobile devices and browsers.

​
Architecture

The web server provides:
  • HTTP REST API for session management and control
  • WebSocket API for real-time session updates
  • Mobile-optimized UI for on-the-go access
  • Security token authentication for secure remote access
The web server is designed for local network access. Exposing it to the public internet requires additional security measures (see Tunnel Manager).

​
Configuration

Enable the web server from Maestro’s settings:
1

Open Settings

Press Cmd/Ctrl + , or navigate to Maestro → Settings
2

Enable Web Interface

Toggle Enable Web Interface to start the server
3

Configure Port (Optional)

By default, Maestro uses a random available port. You can specify a custom port:
  • Enable Use Custom Port
  • Set Custom Port (default: 8080)
4

Access Web Interface

Click the generated URL or scan the QR code to access from mobile devices

​
URL Structure

All endpoints require a security token that’s automatically generated when the server starts. 
http://localhost:PORT/$TOKEN/                  → Dashboard (all live sessions)
http://localhost:PORT/$TOKEN/session/$UUID     → Single session view
http://localhost:PORT/$TOKEN/api/*             → REST API
http://localhost:PORT/$TOKEN/ws                → WebSocket
The security token is regenerated each time Maestro restarts. Bookmark the full URL including the token.

​
REST API Endpoints

​
Get All Sessions

Retrieve all active sessions. 
GET /$TOKEN/api/sessions

​
Get Session Details

Retrieve detailed information for a specific session, including conversation logs. 
GET /$TOKEN/api/session/:sessionId?tabId=optional-tab-id

​
Get Theme

Retrieve the current theme configuration. 
GET /$TOKEN/api/theme

​
Send Command

Execute a command in a session. 
POST /$TOKEN/api/session/:sessionId/write
Content-Type: application/json

{
  "data": "Write a hello world function\n"
}

​
Interrupt Session

Stop the currently running command in a session. 
POST /$TOKEN/api/session/:sessionId/interrupt

​
WebSocket API

Connect to the WebSocket endpoint for real-time updates.

​
Connection

const ws = new WebSocket(`ws://localhost:${port}/${token}/ws`);

ws.onopen = () => {
  console.log('Connected to Maestro');
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  handleMessage(message);
};

​
Message Types

​
type
string
required
Message type identifier
  • init - Initial connection data
  • session:state - Session state change
  • session:added - New session created
  • session:removed - Session deleted
  • session:live - Session marked as live
  • session:offline - Session marked as offline
  • tabs:change - Tab configuration changed
  • theme:change - Theme updated

​
Client Messages

Send commands to Maestro via WebSocket: 
{
  "type": "execute",
  "sessionId": "session-uuid",
  "command": "Write a hello world function",
  "inputMode": "ai"
}

​
Rate Limiting

The web server includes configurable rate limiting to prevent abuse:
​
max
number
default:"100"
Maximum requests per minute for GET endpoints
​
maxPost
number
default:"30"
Maximum requests per minute for POST endpoints
​
timeWindow
number
default:"60000"
Time window in milliseconds (default: 1 minute)
Rate limit exceeded responses return HTTP 429 with a Retry-After header.

​
Security

Auto-generated Tokens

Security tokens are UUIDs regenerated on each app restart

Invalid Token Handling

Requests with invalid/missing tokens redirect to the Maestro website

Local Network Only

Server binds to 0.0.0.0 but is designed for local network access only

No Persistent Authentication

No user accounts or persistent auth - access is token-based only
For secure public internet access, use the Tunnel Manager to create a Cloudflare tunnel.

​
Implementation Details

The web server is built with:
  • Fastify - High-performance HTTP framework
  • @fastify/websocket - WebSocket support
  • @fastify/cors - CORS handling
  • @fastify/rate-limit - Rate limiting
Source: src/main/web-server/WebServer.ts:1

Build docs developers (and LLMs) love

Get started for freeTalk to us