Installation - Vellum Docs

What you need

macOS 15 (Sequoia) or later, Apple Silicon or Intel
~500 MB free disk space (app + daemon + workspace data)
Internet connection required (your assistant uses cloud AI models to think)
About 5 minutes and a willingness to talk to your computer

Interested? Join the waitlist to get early access.

Step 1: Download Vellum

Join the waitlist to get your download link.

Standard .dmg file. Nothing weird, nothing suspicious.

Step 2: Install

Open the downloaded .dmg
Drag Vellum to your Applications folder
Open Vellum from Applications

That's the whole process. No terminal commands. No package managers. No YAML files. (You're welcome.)

Step 3: First launch

On first launch, you'll walk through a short setup:

Welcome — sign in with your Vellum account, or choose to bring your own Anthropic API key.
Choose your hosting — your assistant runs locally on your Mac. Your machine, your data.
Enter your API key — if you're bringing your own key, enter your Anthropic API key here. It's stored securely in your macOS Keychain. This step is skipped if you signed in with Vellum.
Privacy & Terms — choose your privacy preferences (analytics and diagnostics, both optional) and accept the Terms of Service.
Hatching — your assistant boots up in an animated sequence while everything is provisioned behind the scenes.

The whole process takes about 2 minutes. Your workspace is created at ~/.vellum/workspace/ — plain text files, fully readable and editable by you.

Two ways to connect

Bring your own API key — Enter an Anthropic API key and run everything locally. Your key is stored in your macOS Keychain.
Sign in with Vellum — Authenticate with your Vellum account for a managed experience. No API key needed — billing is handled through your Vellum account.

What gets installed

Vellum creates one directory on your machine:

~/.vellum/
├── workspace/
│   ├── IDENTITY.md        # Name, personality, emoji
│   ├── SOUL.md            # Principles and behavior rules
│   ├── USER.md            # What the assistant knows about you
│   ├── NOW.md             # Current focus, goals, and context
│   ├── config.json        # Runtime configuration
│   ├── skills/            # Installed and custom skills
│   └── data/
│       └── db/
│           └── assistant.db   # Conversations, memory, schedules (SQLite)
├── lockfile.json          # Running assistant instances and ports

Everything is plain text (aside from the SQLite database). You can open these files in any editor, read them, change them, even put them in version control. Your assistant's brain is not a black box. It's a folder on your computer.

Session logs are stored in ~/Library/Application Support/vellum-assistant/logs/. The daemon binary lives inside the .app bundle, not in ~/.vellum/.

Permissions

Vellum doesn't ask for all its permissions upfront. Instead, permissions are requested only when they're actually needed:

Permission	Purpose	When requested
Screen Recording	See your screen for computer-use tasks	First time your assistant needs to see your screen
Microphone	Voice input (hold Fn to talk)	First time you use voice input
Speech Recognition	Convert voice to text	First time you use voice input
Accessibility	Control your Mac (click, type, navigate)	First time your assistant needs to interact with your apps
Notifications	Status updates and reminders	Optional, on first notification

Worth knowing: The app accesses files through normal sandbox entitlements, not Full Disk Access. Individual file and shell actions still require your approval through the in-app permission system. Check out Trust & Security for the full picture.

Updates

Vellum checks for updates automatically in the background. When an update is available, you'll see a green update button in the top right corner of the app. You can install immediately or defer until later. Updates are signed and verified before installation.

Definitions

Key terms and concepts used throughout the Vellum Assistant ecosystem.

Assistant: An AI-powered agent configured to perform tasks on your behalf. Each assistant is backed by a large language model and can be customized with specific instructions, skills, and channels.
Channel: The surface through which users interact with the assistant. Channels include the desktop app, command-line tool, and other application integrations like Telegram.
Environment: The runtime context in which an assistant operates.
Guardian: The user who is in charge of the assistant. The guardian oversees the assistant's behavior, manages its configuration, and ensures it operates within defined boundaries.
Hatch: The process of creating and initializing a new assistant. When you hatch an assistant, it is configured and made ready to receive messages.
Retire: The process of deactivating an assistant. Retiring an assistant stops it from receiving new messages and frees up associated resources.
Skill: An action or capability that the assistant can invoke during a conversation. Skills allow the assistant to interact with external systems, run code, search the web, and more.