The Permissions Model

Your options

When prompted, you're not limited to a binary yes/no. You can choose:

For “Always Allow” and “Always Deny,” you also choose the scope: this specific file, anything in this directory, this project, or everywhere. These decisions are saved as trust rules and accumulate over time. The more you use your assistant, the fewer prompts you see for actions you've already approved.

The sandbox boundary

Think of your assistant's workspace as a separate computer inside your computer. It's a self-contained environment where the assistant can run freely — creating files, modifying data, running commands — without needing your approval. Anything that happens inside this inner computer stays contained.

Inside the workspace (~/.vellum/workspace/):

• Reading, writing, and editing files — no approval needed
• Running shell commands via bash — no approval needed (sandboxed execution)
• Building apps, saving memories, searching the web — no approval needed

Outside the workspace (your host machine):

• host_file_read — reading files anywhere on your machine. Prompted.
• host_file_write, host_file_edit — writing or editing files anywhere. Prompted.
• host_bash — running shell commands on your actual machine. Prompted.

When the assistant needs to do something outside its workspace, it doesn't reach out directly. Instead, it tells a separate process — one that lives outside the sandbox — to perform the action and report back. That external process is deterministic, traditional software with no AI involved. The AI stays inside the cage at all times.

The sandbox is enforced at the OS level (sandbox-exec on macOS, bubblewrap on Linux). Path traversal attacks (using ../ to escape the workspace) and symlink escapes are blocked.

How shell commands are classified

Not all shell commands are equal. Your assistant parses commands using a tree-sitter parser and classifies them based on what programs they invoke:

Low risk — read-only programs: ls, cat, grep, find, git status, git log, git diff, node, python, jq, tree, du, df, ping, dig, and similar.

Medium risk — programs that modify state: sed, awk, chmod, chown, curl, wget, non-read-only git subcommands (like git commit, git push), and any program not in the known-safe list.

High risk — dangerous programs: sudo, rm, dd, mkfs, reboot, shutdown, kill, iptables, and other system administration tools.

This parsing also generates “action keys” for pattern matching. When you approve git push, the system creates a rule that matches future git push commands without also matching git reset --hard.

Trust rules

Your approval decisions are stored as trust rules in ~/.vellum/protected/trust.json. Each rule has:

• Tool — which tool it applies to
• Pattern — a glob pattern matching specific commands, paths, or URLs
• Scope — where the rule applies (a specific directory, or everywhere)
• Decision — allow, deny, or ask
• Priority — higher priority rules win; at equal priority, deny beats ask beats allow

Rules are matched using minimatch glob patterns. You can have a broad “allow git everywhere” rule and a narrow “deny git push --force everywhere” rule, and the deny will win because deny beats allow at equal priority.

You can inspect and edit your trust rules directly in the file, or manage them through the Settings > Trust tab.

Skill tool permissions

Tools provided by third-party skills (ones you've installed, not the ones bundled with Vellum) are always prompted by default, regardless of risk level. This prevents a malicious or buggy skill from executing actions without your knowledge.

Bundled skill tools (Browser, Gmail, Calendar, etc.) follow the normal risk-based rules.

Computer use permissions

Computer use actions — clicking, typing, scrolling, opening apps — have ask rules at the highest priority level. Each action is prompted individually. This means your assistant can't silently control your screen; you approve each step.

You can create “Always Allow” rules for specific computer use patterns if you want the assistant to work more autonomously during screen control sessions.

macOS system permissions

On top of the assistant's own permission system, macOS has its own layer:

These are the “can it access this at all” layer. The assistant's Allow/Don't Allow prompts are the “should it access this right now” layer. Both must pass for an action to execute.

Cross-channel approvals

When someone messages your assistant through Telegram or Slack and the assistant needs to do something that requires permission, it routes the approval request to you (the guardian) through your active channel.

Approval grants are:

• One-time use — a grant is consumed when the action executes and can't be reused
• Time-limited — grants expire after 5 minutes if not used
• Scoped — bound to the specific tool and input that was requested

Guardian approvals are always downgraded to one-time grants, even if you select “Always Allow.” This prevents a single cross-channel approval from creating a persistent rule — you'd need to create that rule directly from the desktop app.

What happens when you say no

When you deny an action:

1. The action is blocked immediately
2. Your assistant acknowledges the denial
3. It does not retry automatically
4. It asks if there's an alternative approach
5. It only retries with your explicit consent

If you choose “Always Deny,” future attempts to use that tool with a matching pattern are blocked silently — the assistant won't even ask.