Security & cloud mode

What this page is for

Security on Exolvra is not one knob. It’s a layered model: capability grants per-agent, session types, cloud mode overrides, approval gates, and audit trails. This page explains the layers, shows how they compose, and gives guidance on hardening an instance based on who’s using it.

The capability model

Every tool an agent uses goes through a capability check before it runs. The check asks: “is this agent, in this session, allowed to invoke this tool right now?” The answer is computed from three layers:

1. Permanent grants — what the agent is configured to use on its edit page. If the agent doesn’t have shell in its tool set, it can’t call shell. Full stop.
2. Session type — every session is of a type: Main (dashboard chat), Channel (Telegram/Discord/Slack/Console), Bot API (widget/API key), or Internal (agent-to-agent messages). Session type sets a default capability ceiling. Channel and Bot API sessions have narrower ceilings than Main.
3. Cloud mode — if enabled instance-wide, cloud mode overrides everything above and restricts capabilities to a hard-coded safe set.

The effective capability for any tool call is the intersection of these layers. All three must allow the call for it to run.

Session types

Session type is assigned automatically based on how the session was created. You can’t manually override it for security reasons — a Bot API session can never be “promoted” to Main, and a Channel session can never be promoted to “trust me, this is trusted.”

Cloud mode

Cloud mode is the nuclear option for hardening. When enabled from Config → Budget & Security, it applies globally and overrides all other capability checks for all sessions with a hard-coded safe capability set:

• Allowed: network HTTP (web_search, web_fetch), memory read/write, data store, task board, inter-agent messages
• Blocked: file system access, shell execution, browser automation, any system-level tool

When to enable cloud mode:

• You’re running Exolvra as a service for people whose trust boundary is narrower than yours
• You’re hosting a public endpoint that anyone can hit
• You’re running in a multi-tenant deployment where one user shouldn’t be able to touch another user’s machine
• You’re uncertain about the blast radius of a compromised agent and want to set a strict floor

When not to enable cloud mode:

• You’re running a personal single-user instance and want full tool access
• You’re on a local dev machine doing real work on files and shell

Cloud mode is off by default. Enable it explicitly after you’ve decided you want it.

Optional cloud-mode relaxations

Cloud mode has one configurable exception: Cloud browser. If you enable CloudAllowBrowser, the browser tool remains available in cloud mode. Use this when you’re running a sandboxed browser pool and want agents to do web automation without having the rest of the capability relaxation of not-cloud-mode.

Session-scoped temporary grants

Sometimes you want to give an agent extra capabilities for one specific task without permanently loosening its configuration. Session-scoped temporary grants let you do that.

From the agent detail page, click Grant temporary permission. Pick the tool, set a duration (default 1 hour), save. For the duration of the grant, that agent gets the extra capability on any session it runs. When the grant expires, the capability goes back to the agent’s permanent grants.

Use temporary grants for:

• Giving a research agent shell access for one investigation
• Letting a code assistant edit files in a project it’s not usually allowed to touch
• Adding a skill for a one-off task without permanently installing it

Temporary grants are logged in the audit log and the session history. They can be revoked early from the same page.

Hardening checklist

When you’re standing up a new Exolvra instance you’ll share with others, work through this checklist:

1. Change the bootstrap password immediately on first login
2. Enable 2FA on your own Owner account
3. Create a second Admin user so you have a recovery path
4. Set daily and monthly budget caps on the instance
5. Enable session cost warnings at a reasonable threshold
6. Review the default tool grants on every specialist agent — remove anything they don’t need
7. Decide on cloud mode — enable it if the deployment is multi-tenant or public
8. Configure channel allowlists — restrict Telegram chat ids, Discord guild ids, Slack channels
9. Configure provider rate limits and alert thresholds
10. Set up the audit export webhook if you need compliance-grade retention
11. Review the approvals configuration — add gates on the tools you care about
12. Verify HTTPS is in front of the gateway before you expose it to the internet
13. Back up the data directory regularly (the whole ~/.exolvra/ tree)

Most of these are one-time setup steps. Once done, an instance is in good shape.

Common pitfalls

Running without cloud mode in a multi-tenant deployment. If you’re hosting Exolvra for multiple untrusted users, cloud mode is not optional. A specialist agent with filesystem access can read files belonging to other users on the same host.

Granting shell to every agent “just in case”. Shell is the most dangerous tool by a wide margin. Grant it only to agents that actually need it, and consider wrapping shell access behind an approval gate for destructive verbs.

Forgetting to lock down channel allowlists. A Telegram bot without a chat-id allowlist responds to anyone who finds it. A Discord bot without a guild-id allowlist can be added to any server. Always set allowlists before enabling a public channel.

Not rotating API keys. Personal API keys and bot API keys should be rotated periodically. Exolvra makes this cheap — revoke old keys from their respective edit pages and generate new ones.

Where to go next

• Approvals — the per-tool approval gate system
• Audit log — track security-relevant events
• Users & teams — identity and role hierarchy
• Admin overview — the full admin setup checklist