Installation

Step 1: Download Vellum

Join the waitlist to get your download link.

Standard .dmg file. Nothing weird, nothing suspicious.

Step 2: Install

1. Open the downloaded .dmg
2. Drag Vellum to your Applications folder
3. 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:

1. Choose your path — bring your own Anthropic API key, or sign in with a Vellum account.
2. Name your assistant — pick a name (default: "Velly") and choose your activation key (Fn, Ctrl, or Fn+Shift).
3. Grant permissions — Screen Recording and Microphone are requested with one-click prompts.
4. Meet your assistant — a short introductory conversation where your assistant learns about you.

The whole process takes about 5 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
│   ├── LOOKS.md           # Avatar appearance traits
│   ├── 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/.

Command-line tool

The desktop app automatically installs the vellum CLI to /usr/local/bin/vellum (or ~/.local/bin/vellum). Use it to manage your assistant from the terminal:

vellum ps        # List running assistants
vellum wake      # Start your assistant
vellum sleep     # Stop your assistant
vellum logs      # Tail assistant logs
vellum login     # Connect your Vellum account

Permissions

Vellum requests macOS system permissions during onboarding and use:

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 notification in the menu bar. You can install immediately or defer until you quit the app. Updates are signed and verified before installation.

Common issues

"Vellum can't be opened because it is from an unidentified developer"

Right-click (or Control-click) the app in Finder and select "Open." macOS will let you proceed. This only happens the first time.

"Operation not permitted" errors

A macOS permission is missing. Your assistant will ask you to grant it through System Settings when this happens. Just follow the prompt.

Assistant not responding after update

Run vellum wake in your terminal, or quit and relaunch the app. The daemon may need to restart after an update.

"Port already in use" error

Another instance may be running. Run vellum ps to check, then vellum sleep <name> to stop it.

Voice input not working

Ensure both Microphone and Speech Recognition permissions are granted in System Settings > Privacy & Security.

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.

Connect Vellum Account

Run vellum login to connect your Vellum account. This enables managed billing and cloud-hosted assistants.

This will open a browser window where you can sign in with your Vellum account. Once authenticated, your local installation will be linked to your workspace.