Figaro

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/figaro_logo.png"> <source media="(prefers-color-scheme: light)" srcset="docs/figaro_logo.png"> <img width="384" height="384" alt="Figaro Logo" src="docs/figaro_logo.png"> </picture> </p> <p align="center"> <a href="LICENSE.md"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a> <a href="https://en.wiktionary.org/wiki/vibecoding"><img src="https://img.shields.io/badge/code-LLM%20generated%20(with%20a%20lot%20of%20human%20oversight)-ff69b4" alt="Code LLM Generated (with a lot of human oversight)"></a> </p>

---

Figaro orchestrates fleets of Claude computer use agents that automate workflows on full desktop environments. Agents run inside containerized Linux desktops or connect to any VNC-accessible machine -- remote servers, cloud VMs, or physical workstations. All desktops are live-streamed to a central dashboard, and a supervisor agent handles task delegation. Everything can be managed conversationally through external channels like Telegram.

Figaro can connect to any accessible desktop -- local machines, remote servers, cloud VMs, or physical workstations running macOS, Windows, or Linux. Desktops are added from the UI with a connection URL (vnc://, rdp://, ssh://, telnet://, ws://, or wss://), and the supervisor agent can observe and interact with any connected desktop via screenshots, typing, clicking, and key presses. Desktop streaming uses Apache Guacamole (guacd + guacamole-common-js) for protocol-agnostic remote access.

The system is built for long-running tasks that take minutes to hours. All services communicate over NATS (pub/sub + JetStream for durable task events). A supervisor agent handles task optimization and delegation.

You can also manage everything by chatting with the supervisor agent through the gateway -- for example, via Telegram. Send it natural language instructions to create tasks, schedule recurring jobs, check worker status, or ask questions about running tasks. The supervisor understands the full system and can delegate work to workers, inspect desktops via VNC, and report back results, all through a conversational interface.

Table of Contents

• Quick Start
• Advanced Setup
• Connecting External Desktops
• Scheduled Tasks
• Self-Healing
• Self-Learning
• Agent Memory
• Gateway
• Security
• Architecture
• Services
• Development Setup
• Configuration
• NATS Subject Design
• Message Flows
• Testing
• Contributing
• Credits

UI Action shot

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/action_shot.png"> <source media="(prefers-color-scheme: light)" srcset="docs/action_shot.png"> <img width="900" alt="Figaro Dashboard" src="docs/action_shot.png"> </picture> </p>

Quick Start

curl -fsSL https://raw.githubusercontent.com/byt3bl33d3r/figaro/main/install.sh | bash

Or clone and run directly:

git clone https://github.com/byt3bl33d3r/figaro.git && cd figaro && ./install.sh

By default the install script uses the prod-local overlay, Figaro will be available at http://localhost:8000.

Prerequisites

• Docker and Docker Compose -- on Linux the install script will install Docker automatically via get.docker.com. On macOS you must install Docker Desktop manually before running the script.
• Claude credentials (~/.claude.json and ~/.claude/.credentials.json) -- created by running claude and signing in. On macOS (assuming you have a Claude Code subscription) once logged in, you can export the credentials file for use in containers with the following command:

  security find-generic-password -s "Claude Code-credentials" -w > ~/.claude/.credentials.json
  

Optional

• An OpenAI API key (used for patchright-cli transcription functionality)
• A Telegram bot token (enables chatting with the supervisor agent via Telegram for task submission, status checks, and notifications). Create a bot via @BotFather and set GATEWAY_TELEGRAM_BOT_TOKEN and GATEWAY_TELEGRAM_ALLOWED_CHAT_IDS in your .env

Advanced Setup

[!NOTE] The install.sh script does this for you.

cp .env.example .env

# Generate an encryption key for VNC password storage (required)
echo "FIGARO_ENCRYPTION_KEY=$(openssl rand -hex 16)" >> .env

# Optional: set an OPENAPI_API_KEY
# OPENAI_API_KEY=sk-proj-example
# Optional: set Telegram gateway variables for notifications and task submission
# GATEWAY_TELEGRAM_BOT_TOKEN=your-bot-token
# GATEWAY_TELEGRAM_ALLOWED_CHAT_IDS=["your-chat-id"]

VNC passwords are encrypted at rest in PostgreSQL using pgcrypto. The FIGARO_ENCRYPTION_KEY is used for symmetric encryption and must be set before starting the orchestrator. The install.sh script generates this automatically.

The base docker/docker-compose.yml defines all shared services but does not expose ports. Choose an overlay for your deployment scenario:

# Production, localhost-only (recommended) -- ports bound to 127.0.0.1
docker compose -f docker/docker-compose.yml -f docker/docker-compose.prod-local.yml up --build

# Development -- localhost ports + a desktop service for testing VNC
docker compose -f docker/docker-compose.yml -f docker/docker-compose.dev.yml up --build

[!CAUTION] The docker/docker-compose.prod.yml overlay binds ports to 0.0.0.0, making NATS and the orchestrator accessible from any network interface. Only use this if you understand the security implications and have appropriate firewall rules in place. Please read Security to understand known attack surface.

docker compose -f docker/docker-compose.yml -f docker/docker-compose.prod.yml up --build

Open http://localhost:8000.

This starts PostgreSQL, NATS (port 8443), guacd (Guacamole daemon), the orchestrator (port 8000), 2 workers, 2 supervisors, and the gateway. The supervisor service uses the same figaro-worker binary started with the --supervisor flag.

Scaling

docker compose -f docker/docker-compose.yml -f docker/docker-compose.prod-local.yml up --build --scale worker=4 --scale supervisor=3

Teardown

docker compose -f docker/docker-compose.yml -f docker/docker-compose.prod-local.yml down       # Stop services
docker compose -f docker/docker-compose.yml -f docker/docker-compose.prod-local.yml down -v    # Stop and remove all data

Connecting External Desktops

Figaro is not limited to its own containerized workers. Any machine with a VNC server can be connected as a desktop.

From the UI

Click "Add Desktop" in the dashboard header. Provide a worker ID, a desktop URL, and select the OS type. Supported URL schemes:

• vnc://user:password@hostname:5901 -- direct TCP VNC connection
• rdp://user:password@hostname:3389 -- RDP connection
• ssh://user:password@hostname:22 -- SSH connection
• telnet://user:password@hostname:23 -- telnet connection
• ws://hostname:6080 -- WebSocket (legacy noVNC-compatible)
• wss://hostname:6080 -- WebSocket over TLS (legacy noVNC-compatible)

Credentials can be embedded in the URL or entered separately. Connected desktops appear in the live desktop grid and can be viewed, screenshotted, and interacted with by the supervisor agent's VNC tools. SSH and telnet connections are accessible via the supervisor's terminal tools (ssh_run_command, telnet_run_command).

From Environment Variables

Pre-configure desktops at startup via the FIGARO_DESKTOP_WORKERS environment variable:

FIGARO_DESKTOP_WORKERS='[{"id": "mac-studio", "novnc_url": "vnc://user:pass@192.168.1.50:5900", "metadata": {"os": "macos"}}]'

Agent Upgrade Path

Desktop-only entries act as placeholders. When a worker agent connects with a matching ID, the desktop is automatically upgraded to a full agent worker capable of receiving tasks. When the agent disconnects, the desktop reverts to view-only mode rather than disappearing. This means you can pre-register your desktops and have agents attach and detach dynamically.

This is useful when you want to connect existing physical machines or VMs to Figaro without running the full containerized worker stack. For example, you can point Figaro at your Mac Mini's VNC server, and the supervisor can already observe and interact with its screen. Later, run the figaro-worker agent on that machine to give it full task execution capabilities -- the desktop entry upgrades seamlessly without any reconfiguration. If you install patchright-cli on that machine it becomes particularly handy: it's a standalone browser automation CLI that speaks the same claude-agent-sdk protocol, so you can drop it onto any machine with a browser and instantly level up your browser automation tasks.

Scheduled Tasks

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/scheduled_task.png"> <source media="(prefers-color-scheme: light)" srcset="docs/scheduled_task.png"> <img width="600" alt="Figaro Scheduled Tasks" src="docs/scheduled_task.png"> </picture> </p>

Figaro supports cron-like scheduling for recurring tasks. Scheduled tasks are managed through the UI or directly by chatting to Figaro via Telegram or whatever channel is configured in the Gateway.

Each scheduled task has:

• Prompt -- the task instruction sent to the agent
• Cron expression -- standard cron syntax for scheduling (e.g., 0 9 * * * for daily at 9 AM)
• Start URL -- opti