Configuration

All Prometheal configuration is done through environment variables and the Settings UI.

---

Environment variables

Required

Variable	Description	Example
DATABASE_URL	PostgreSQL connection string	postgresql://user:pass@localhost:5432/prometheal
JWT_SECRET	Secret for signing session JWTs. Use a random string (32+ chars).	openssl rand -base64 32
ENCRYPTION_KEY	64 hex characters (32 bytes) for AES-256-GCM encryption of API keys and credentials at rest.	node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
NEXT_PUBLIC_APP_URL	Public URL where users access Prometheal. Used for redirects and CSRF origin checks.	https://prometheal.example.com

Sandbox

Variable	Default	Description
SANDBOX_PROVIDER	e2b	Sandbox backend: docker (self-hosted) or e2b (cloud)
E2B_API_KEY	—	API key from e2b.dev. Required if SANDBOX_PROVIDER=e2b.
E2B_TEMPLATE_ID	—	Custom E2B template ID. Optional.
E2B_SANDBOX_TIMEOUT	3600000	Sandbox idle timeout in ms (default: 1 hour)
DOCKER_SANDBOX_IMAGE	prometheal-sandbox:latest	Docker image for sandboxes
DOCKER_SANDBOX_NETWORK	prometheal-sandbox	Docker network name for sandbox containers
DOCKER_SANDBOX_TIMEOUT	3600000	Sandbox idle timeout in ms (default: 1 hour)
DOCKER_HOST_ADDRESS	localhost	Address the sandbox uses to reach the Prometheal server. Set to the host's IP if Prometheal runs in Docker.

LLM providers

These can also be configured in the Settings UI after setup. UI values take precedence.

Variable	Description
OPENROUTER_API_KEY	OpenRouter API key (recommended, gives access to 200+ models)
ANTHROPIC_API_KEY	Anthropic API key (for Claude models)
OPENAI_API_KEY	OpenAI API key (for GPT models)

Optional

Variable	Default	Description
REDIS_URL	—	Redis connection URL. Enables distributed KV for multi-instance deployment. Without Redis, an in-memory store is used (fine for single instance).
LOG_LEVEL	info	Logging level: debug, info, warn, error

---

Settings UI

The Settings page (/admin/settings) is organized into tabs:

General

Setting	Description
Registration	Toggle open registration (anyone can sign up) vs invite-only

Authentication

Configures SSO/OIDC and account security policies.

SSO / OIDC

Prometheal supports single sign-on via any OpenID Connect provider (Google, Okta, Azure AD, Keycloak, Auth0, etc.).

Configure in Settings > Authentication:

Setting	Description
Enable OIDC Login	Show "Log in with SSO" button on the login page
Issuer URL	The OIDC provider's issuer URL (e.g., https://accounts.google.com). Must support .well-known/openid-configuration discovery.
Client ID	OAuth 2.0 client ID from your provider
Client Secret	OAuth 2.0 client secret (encrypted at rest)
Auto-Provision Users	Automatically create accounts (with USER role) for new OIDC users. When disabled, users must be pre-created in Prometheal before they can log in via SSO.

Redirect URI: Set this in your OIDC provider's configuration:

{NEXT_PUBLIC_APP_URL}/api/auth/oidc/callback

How it works:

1. User clicks "Log in with SSO" on the login page
2. Prometheal redirects to the OIDC provider's authorization endpoint
3. After authentication, the provider redirects back with an authorization code
4. Prometheal exchanges the code for tokens, verifies the ID token via JWKS, and creates a session
5. Existing users are matched by OIDC subject ID or email. New users are auto-provisioned if enabled.

Notes:

• OIDC users who already have a local account (same email) are automatically linked on first SSO login
• Auto-provisioned users are created with the USER role and no password (they can only log in via SSO)
• The OIDC discovery document is cached for 1 hour
• CSRF protection uses a random state parameter with a 10-minute expiry

Account Security

Setting	Default	Description
Require MFA for All Users	false	When enabled, users without MFA are redirected to the Security page until they set up two-factor authentication
Failed attempts before lockout	5	Number of consecutive failed login attempts before the account is locked (1–100)
Lockout duration (minutes)	15	How long a locked account stays locked (1–1440 minutes)

Users can enable TOTP multi-factor authentication from the Security page in their sidebar. Admins can reset MFA and unlock accounts from the Users page.

Account

The Account page (/account) allows all users to update their own profile:

Field	Description
Name	Display name shown in the sidebar and audit logs
Email	Login email address (must be unique, normalized to lowercase)

Changes require the user's current password for confirmation. When the email is changed, the session is refreshed with the new email. Profile changes are logged as user.profile.updated audit events.

LLM Keys

Setting	Description
Anthropic API Key	For Claude models
OpenAI API Key	For GPT models
OpenRouter API Key	For 200+ models via OpenRouter

Keys are encrypted at rest with AES-256-GCM. Shown as "configured" or empty — never displayed in plain text.

Network

Setting	Description
Allowed outbound domains	Comma-separated domains that sandbox containers can reach (in addition to the Prometheal server)

SIEM

See Security — SIEM / Log export for full details on transport, format, and configuration options.

System

The System tab (/api/settings/system) shows:

• Node.js version and platform
• Database connection status and latency
• Sandbox provider configuration
• Agent counts (total, running)
• User and integration counts
• Server uptime

---

Model configuration

Each agent can use a different LLM model. The model string determines which provider is used:

Model format	Provider	Example
provider/model (multi-segment)	OpenRouter	minimax/minimax-m2.5, google/gemini-2.0-flash
claude-*	Anthropic	claude-sonnet-4-20250514
gpt-*, o1*, o3*	OpenAI	gpt-4o, o3-mini
openrouter/model	OpenRouter (explicit)	openrouter/anthropic/claude-3.5-sonnet
anthropic/model	Anthropic (explicit)	anthropic/claude-sonnet-4-20250514
openai/model	OpenAI (explicit)	openai/gpt-4o

The default model is minimax/minimax-m2.5 (via OpenRouter), which is cost-effective for general tasks.

---

Spending limits

Per-agent monthly spending limits can be set in the agent's settings or via the API:

• Monthly limit in cents (e.g., 1000 = $10.00/month)
• Enforced with pessimistic cost reservation — before each agent turn, the estimated cost is reserved. If the reservation would exceed the limit, the turn is rejected.
• Real token counts replace the reservation after the turn completes.
• Resets monthly based on the limit's creation date.

Set limits via Settings > Usage or PUT /api/usage/limits.

---

Agent heartbeat

Per-agent background execution on a timer. Configured in the agent's settings or via the API.

Setting	Type	Default	Description
heartbeatEnabled	boolean	false	Enable/disable periodic background runs
heartbeatIntervalMinutes	integer	30	How often to run (5–1440 minutes)
heartbeatPrompt	string	"Review your memory..."	The message sent to the agent each heartbeat

The heartbeat runner checks every 60 seconds for agents that are due. Each run is a full agent turn (with sandbox, memory, and browser tools). Results are logged to HeartbeatLog.

---

Workspace quota

Per-agent disk space limits for the persistent workspace volume. Configured in the agent's settings or via the API.

Setting	Type	Default	Description
workspaceMaxSizeMB	integer	3072 (3 GB)	Maximum workspace disk usage in MB. Set to 0 for unlimited. Max 102400 (100 GB).

Enforcement:

• Before sandbox__write_file: checks usage, blocks if over quota
• Before sandbox__edit_file (when new content is larger): checks usage, blocks if over quota
• After sandbox__shell: checks usage, appends a warning to the output if over quota (shell commands are not blocked, since they may be deleting files)

Admin controls:

• View current usage in the agent settings page (progress bar with color coding)
• Adjust quota per agent
• Reset workspace button: stops the sandbox, deletes the Docker volume, and restarts with a fresh workspace