Skip to content

README.md

Latest commit

 

History

History
384 lines (285 loc) · 9.47 KB

README.md

File metadata and controls

384 lines (285 loc) · 9.47 KB
Raw

Web Interface Configuration

Note: This documentation applies to the Web Interface (which runs on any platform: Linux, macOS, Windows). For macOS Desktop App-specific configuration (hotkeys, notifications), see macOS App Configuration.

Overview

The web interface provides a browser-based UI that works identically on Linux, macOS, or any other platform. This document covers web server settings, authentication, security, and deployment options.

Table of Contents

Basic Configuration

Start by creating a default configuration file:

mitto config create

This creates ~/.mittorc with sensible defaults. Review and customize the file for your environment:

acp:
  - claude-code:
      command: npx -y @zed-industries/claude-code-acp@latest

web:
  host: 127.0.0.1 # Server host (default: 127.0.0.1)
  port: 8080 # Server port (default: 8080)

Then start the Web server with:

# Start with default settings in a specific directory
mitto web --dir /some/directory

# Specify a different port
mitto web --port 3000  --dir /some/directory

# Create multiple workspaces
mitto web  --dir /some/directory-a  --dir /some/directory-b

and then connect to http://localhost:8080 in your browser.

Multi-Workspace Support

Configure multiple workspaces via CLI:

# Single workspace
mitto web --dir /path/to/project

# Multiple workspaces
mitto web --dir /path/to/project1 --dir /path/to/project2

# Specify ACP server per workspace
mitto web --dir auggie:/path/to/project1 --dir claude-code:/path/to/project2

You can also load workspaces and folder-level settings from external JSON/YAML files. These overlays are applied in memory and are not persisted to disk:

# Load workspaces from a file
mitto web --workspaces config/workspaces.yaml

# Overlay folder-level settings (name/code/color/auto_children/beads)
mitto web --folders config/folders.yaml

Predefined Prompts

Configure quick-access prompts that appear in the chat interface. Prompts are a top-level configuration section:

prompts:
  - name: "Continue"
    prompt: "Please continue with the current task."
  - name: "Propose a plan"
    prompt: "Please propose a plan for the current task."
    backgroundColor: "#E8F5E9" # Optional: custom background color
  - name: "Write tests"
    prompt: "Please write tests for the code you just created."
    backgroundColor: "#FFF3E0"

These prompts appear as quick-action buttons, making it easy to send common instructions.

Prompt Options

Field Type Description
name string Required. Display name for the button
prompt string Required. The prompt text to insert
backgroundColor string Optional. Hex color for button background (e.g., "#E8F5E9")

When a backgroundColor is set, the prompt button will display with that color and automatically adjust text color for readability.

Authentication

When exposing Mitto to the network, enable authentication to protect access.

Simple Authentication

web:
  auth:
    simple:
      username: admin
      password: your-secure-password

When enabled:

  • Users are redirected to a login page
  • Sessions are stored in secure HTTP-only cookies
  • Sessions expire after 24 hours

IP Allowlist

Bypass authentication for trusted IP addresses:

web:
  auth:
    simple:
      username: admin
      password: secret
    allow:
      ips:
        - 127.0.0.1 # localhost IPv4
        - ::1 # localhost IPv6
        - 192.168.0.0/24 # local network

Rate Limiting

Authentication includes automatic rate limiting:

  • 3 failed attempts within 1 minute triggers a 5-minute lockout
  • Returns 429 Too Many Requests when blocked

Security Configuration

Additional security settings for internet-exposed deployments.

Trusted Proxies

When behind a reverse proxy, configure trusted proxies for correct client IP detection:

web:
  security:
    trusted_proxies:
      - 127.0.0.1
      - 10.0.0.0/8
      - 172.16.0.0/12

WebSocket Origin Validation

Allow WebSocket connections from specific origins:

web:
  security:
    allowed_origins:
      - https://your-domain.com
      - https://abc123.ngrok.io

Rate Limiting

web:
  security:
    rate_limit_rps: 10 # Requests per second (default: 10)
    rate_limit_burst: 20 # Maximum burst (default: 20)

Connection Limits

web:
  security:
    max_ws_message_size: 65536 # Default: 64KB

Scanner Defense

Scanner Defense automatically blocks malicious IPs at the TCP connection level on the external listener only. It is enabled by default when external access is configured (external_port >= 0). The localhost listener is not affected.

web:
  external_port: 8443 # Enables scanner defense automatically

  security:
    scanner_defense:
      # Override defaults (all optional):
      rate_limit: 100 # Max requests per minute
      rate_window_seconds: 60 # Rate limit window
      error_rate_threshold: 0.9 # 90% error rate triggers block
      min_requests: 10 # Min requests before error analysis
      suspicious_path_threshold: 5 # Suspicious path hits before block
      block_duration_seconds: 604800 # Block for 7 days (default)
      whitelist: # Additional whitelisted IPs
        - 10.0.0.0/8
      # ip_block_command: "pfctl -t mitto_blocked -T add {ip}" # Optional OS-level blocking

To disable scanner defense:

web:
  security:
    scanner_defense:
      enabled: false

See External Access - Scanner Defense for detailed configuration options.

Lifetime hooks and External Access Tunnels

See External Access Configuration for details.

Important: Always enable authentication when exposing Mitto externally.

Development Mode

Serve static files from a directory for hot-reloading:

mitto web --static-dir ./web/static

Or in config:

web:
  static_dir: ./web/static

For the native macOS app (which does not accept CLI flags), use the MITTO_STATIC_DIR environment variable instead:

MITTO_STATIC_DIR=./web/static ./Mitto.app/Contents/MacOS/mitto-app

Resolution priority is MITTO_STATIC_DIR > config (web.static_dir) > embedded assets.

Reverse Proxy Setup

nginx

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Configure trusted proxies in Mitto:

web:
  security:
    trusted_proxies:
      - 127.0.0.1

Caddy

example.com {
    reverse_proxy 127.0.0.1:8080
}

Caddy automatically handles WebSocket upgrades and HTTPS.

Complete Example

# Global prompts (top-level section)
prompts:
  - name: "Continue"
    prompt: "Please continue with the current task."
  - name: "Propose a plan"
    prompt: "Please propose a plan for the current task."
    backgroundColor: "#E8F5E9"
  - name: "Code Review"
    prompt: "Please review this code for issues."
    backgroundColor: "#FFF3E0"

# Web interface configuration
web:
  host: 0.0.0.0
  port: 8080

  auth:
    simple:
      username: admin
      password: your-secure-password

  security:
    trusted_proxies:
      - 127.0.0.1
    allowed_origins:
      - https://your-tunnel.ngrok.io
    rate_limit_rps: 10
    rate_limit_burst: 20

  hooks:
    up:
      command: "ngrok http ${PORT}"
      name: "ngrok"
    down:
      command: "pkill -f 'ngrok http'"
      name: "stop-ngrok"

Security Headers

Mitto automatically sets security headers:

  • X-Content-Type-Options: nosniff
  • X-Frame-Options: DENY
  • X-XSS-Protection: 1; mode=block
  • Referrer-Policy: strict-origin-when-cross-origin
  • Content-Security-Policy (restricts script and image sources)
  • Cross-Origin-Opener-Policy: same-origin
  • Cross-Origin-Resource-Policy: same-origin

HSTS is enabled when using HTTPS.

Content Security Policy (CSP)

The CSP restricts what resources can be loaded:

  • Scripts: Only from same origin and trusted CDNs (with nonces)
  • Images: By default, only same-origin, data URLs, and blob URLs
  • Styles: Same origin plus trusted font CDNs

External Images: By default, external images (e.g., https://example.com/image.png) are blocked by CSP for privacy. To allow them, see Conversation Configuration.

Related Documentation

[External Access] (../ext-access.md) [ACP Servers] (acp.md) [Workspace Config] [workspace.md) [Configuration Overview] (../overview.md) [Prompts & Quick Actions] (../prompts.md) [Command Processors] (../processors.md) [macOS App] (../mac/README.md)