Prometheal Docs

Appearance

Getting Started ​

This guide walks you through installing, configuring, and using Prometheal from scratch.

Prerequisites ​

  • Docker and Docker Compose (recommended), or:
  • Node.js 22+ and PostgreSQL 16+ (manual setup)
  • A supported LLM API key: OpenRouter (recommended), Anthropic, or OpenAI

Quick start ​

bash
git clone https://github.com/ia03/prometheal.git && cd prometheal && ./deploy.sh

The deploy script automatically:

  1. Asks for your domain (or press Enter for localhost)
  2. Generates secure secrets (JWT, encryption key, Postgres password)
  3. Creates .env.production with secure defaults
  4. Builds the sandbox image (Linux desktop, shell, Python, Git, Chrome)
  5. Starts the full stack: App + PostgreSQL + Redis + Caddy (auto-TLS)
  6. Waits for the server to be healthy

Once it finishes, open your domain (or http://localhost) to complete the setup wizard — name your instance, create your admin account, and add an LLM API key.

Development setup

For local development with hot reload, use ./setup.sh instead. See Manual setup (development) below.

Re-running is safe

If you already have a .env or sandbox image, the script skips those steps. You can run it again at any time.

gVisor adds kernel-level sandboxing on top of Docker. Without it, containers use the default runc runtime (less isolated).

bash
# Ubuntu/Debian
sudo apt-get install -y runsc
sudo runsc install
sudo systemctl restart docker

Prometheal auto-detects gVisor and uses it when available. See gvisor.dev for other platforms.

Manual Docker setup ​

If you prefer to configure things yourself instead of using setup.sh:

1. Clone and configure ​

bash
git clone https://github.com/ia03/prometheal.git
cd prometheal
cp .env.example .env

Edit .env with the required values:

bash
# Generate a random JWT secret
JWT_SECRET=$(openssl rand -base64 32)

# Generate a 32-byte encryption key (64 hex chars)
ENCRYPTION_KEY=$(openssl rand -hex 32)

# Database (matches docker-compose.yml defaults)
DATABASE_URL=postgresql://prometheal:prometheal@postgres:5432/prometheal

# Public URL (where users will access Prometheal)
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Sandbox provider
SANDBOX_PROVIDER=docker

2. Build the sandbox image ​

bash
docker build -t prometheal-sandbox:latest -f sandbox/Dockerfile sandbox/

3. Start Prometheal ​

bash
docker compose up -d

4. Run the setup wizard ​

Open http://localhost:3000 and complete the setup wizard.

Option B: Manual setup (development) ​

1. Install dependencies ​

bash
npm install

2. Configure environment ​

bash
cp .env.example .env

Edit .env:

bash
DATABASE_URL=postgresql://user:password@localhost:5432/prometheal
JWT_SECRET=your-random-secret
ENCRYPTION_KEY=your-64-hex-char-key
NEXT_PUBLIC_APP_URL=http://localhost:3000
SANDBOX_PROVIDER=docker   # or e2b

3. Set up the database ​

bash
# Start PostgreSQL if not running
docker compose up postgres -d

# Run migrations
npx prisma migrate dev

4. Build and start ​

bash
npm run build
npm start

Or for development with hot reload:

bash
npm run dev

5. Open the setup wizard ​

Go to http://localhost:3000 and complete the setup wizard.

First steps after setup ​

Create your first agent ​

  1. Go to Dashboard and click New Agent
  2. Give it a name and description
  3. Choose a model (default: minimax/minimax-m2.5 via OpenRouter)
  4. Optionally set a system prompt to define the agent's behavior
  5. Click Create

Start chatting ​

  1. Click on your agent, then Chat
  2. Type a message. The agent will:
    • Auto-start a sandbox on the first message
    • Use shell commands, file operations, browser automation, and desktop tools to accomplish tasks
    • Remember information across conversations using its built-in memory
  3. Click the Desktop button to watch the agent work in real-time via the streamed desktop

Add integrations ​

  1. Go to Settings > Integrations (admin only)
  2. Add an integration from the catalog (e.g., GitHub, Slack, Google Workspace)
  3. Enter credentials and save
  4. Go to your agent's settings and bind the integration

See docs/integrations.md for detailed setup guides for each integration.

Connect channels (Slack / Telegram) ​

Channels let users interact with agents via external platforms.

  1. Go to Admin > Channels
  2. Click Add Channel and pick Slack or Telegram
  3. Enter a name and your platform credentials:
    • Slack: Bot Token (xoxb-...) and Signing Secret from your Slack app
    • Telegram: Bot Token from @BotFather
  4. Copy the webhook URL shown in the form and register it with the platform
  5. Optionally assign an agent now, or do it later — channels without an agent are saved but won't process messages

You can also configure channels from an agent's settings page.

See API Reference — Channels for webhook setup details.

Set up a multi-agent team ​

Agents can delegate tasks to other agents, enabling specialization.

  1. Create specialist agents — e.g., a "Code Agent" with a coding-focused system prompt, a "Research Agent" with web search integrations
  2. Create a coordinator agent — with a system prompt like: "You coordinate tasks. Delegate coding to the Code Agent and research to the Research Agent."
  3. Go to the coordinator's settings and find Agent Communication
  4. Check the boxes for the agents the coordinator is allowed to call
  5. Click Save

Now when you chat with the coordinator and ask it to code something, it will automatically delegate to the Code Agent using the agent__ tool. Each specialist runs with its own sandbox and tools.

Security notes:

  • Call permissions are directional — allowing A to call B does not allow B to call A
  • The target agent gets a fresh context (only its system prompt + the message) — no conversation history leaks
  • Nested calls are limited to 3 levels deep, with automatic cycle detection
  • All cross-agent calls are logged in the data flow audit

Enable background heartbeat ​

Agents can run periodically in the background to check on tasks, update their memory, or perform maintenance.

  1. Go to the agent's settings page
  2. Under Heartbeat, enable the toggle
  3. Set the interval (e.g., every 30 minutes)
  4. Write a heartbeat prompt — this is the message the agent receives each run (e.g., "Check your memory for pending tasks and update your status.")
  5. Click Save

Heartbeat runs use the agent's full capabilities (sandbox, browser, memory, MCP tools). Results are logged in HeartbeatLog.

Upload documents ​

  • Agent-specific: Go to the agent's Documents tab and upload files. They're synced to the sandbox's /documents/ directory.
  • Shared library: Go to Settings > Library and upload documents. Then bind them to agents from the agent's settings.

Invite users ​

  1. Go to Settings > Users
  2. Click Create Invite Link
  3. Choose a role (Admin, Manager, or User), max uses, and expiry
  4. Share the link with your team

Next steps ​

  • Architecture — How Prometheal works under the hood
  • Configuration — All environment variables and settings
  • Security — Sandbox isolation, encryption, access control
  • Integrations — Step-by-step guides for each MCP integration
  • Deployment — Production deployment with Docker, multi-instance, and monitoring
  • API Reference — All REST endpoints

Released under the MIT License.

Prometheal