Security & Permissions - Developer Guide

Vellum uses OS-level sandboxing, a keychain-backed credential vault, and a scoped trust rule system to keep your data safe while giving the assistant the access it needs.

Sandbox

The sandbox uses native OS-level sandboxing: sandbox-exec with SBPL profiles on macOS, bwrap (bubblewrap) on Linux. No extra dependencies on macOS. Fail-closed — if the backend is unavailable, commands fail immediately rather than falling back to unsandboxed execution.

Workspace tools (file_read, file_write, file_edit, bash) operate within ~/.vellum/workspace.
Host tools (host_bash, host_file_read, host_file_write, host_file_edit) execute directly on the host, subject to trust rules and permission prompts.

Troubleshooting

Symptom	Cause	Fix
`Docker CLI is not installed`	Docker not installed	Install Docker Desktop
`Docker daemon is not running`	Docker Desktop not started	Start Docker Desktop or `sudo systemctl start docker`
`Cannot bind-mount the sandbox root`	File sharing not configured	Add `~/.vellum/workspace` to Docker file sharing
`bwrap cannot create namespaces`	bubblewrap not installed (Linux)	`apt install bubblewrap`

Run vellum doctor for a full diagnostic check.

Credentials

Secrets are stored in the macOS Keychain (encrypted file fallback on Linux). The LLM never sees raw tokens or keys.

Secret prompt — a floating SecureField panel collects credentials; the LLM never sees the value.
Ingress blocking — inbound messages are scanned for secrets (regex + entropy) and rejected if detected.
Usage policy — each credential specifies allowedTools and allowedDomains, enforced by the CredentialBroker.
No plaintext read API — secrets are only consumed by the broker for scoped tool execution.
One-time send — when enabled, a “Send Once” button lets users provide a value for immediate use without persisting it.

Credential References

Use either format in proxied shell commands:

UUID — the canonical credential ID from credential_store list
service/field — human-readable, e.g. fal/api_key

Unknown references fail immediately with a clear error before the command executes.

Wildcard Matching

Patterns like *.fal.run match subdomains (api.fal.run, queue.fal.run) and the bare domain (fal.run). Exact patterns take precedence over wildcards.

Ambiguity Blocking

When multiple credentials match the same host, the request is blocked — the proxy refuses to guess. Per-credential selection picks the most specific template (exact > wildcard). Cross-credential resolution blocks when more than one credential matches.

Debugging 401 Errors

Check the credential reference matches via credential_store list
Verify the hostPattern matches the target host
Check for ambiguity — overlapping patterns block injection
Verify the injection template has the correct headerName and valuePrefix
Enable LOG_LEVEL=debug for decision traces

Permission Modes

Mode	Default	Behavior
`workspace`	✅	Workspace-scoped ops auto-allowed. Host operations and network requests follow normal approval flow.
`strict`	—	Every tool invocation requires an explicit trust rule. No implicit auto-allow.

assistant config set permissions.mode '"workspace"'   # default
assistant config set permissions.mode '"strict"'       # lock everything down

Trust Rules

Approval decisions are persisted in ~/.vellum/protected/trust.json.

Pattern matching — minimatch glob patterns for commands and file paths
Execution target binding — rules scoped to sandbox or host contexts
High-risk override — rules with allowHighRisk: true auto-allow high-risk invocations

Shell Command Allowlists

When you approve a shell command, the prompt offers parser-derived allowlist options based on the command's structure. For example, cd /repo && gh pr view 5525 --json title generates:

cd /repo && gh pr view 5525 --json title — exact command
gh pr view * — any gh pr view command
gh pr * — any gh pr command
gh * — any gh command

Compound commands with multiple non-prefix actions only offer an exact-command option to prevent over-generalization.

Version-bound Skill Approvals

Trust rules record the skill's version hash. If source files change, the hash changes and you're re-prompted — modified skills can't silently inherit previous approvals.

Skill Mutation Protection

Writes to skill directories are escalated to high risk, preventing the agent from modifying its own capabilities without explicit consent.