Installation - Vellum Docs

What you need

macOS 14 (Sonoma) and later (Apple Silicon or Intel)
An internet connection (your assistant needs it 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

When you open Vellum for the first time:

Your workspace is created. A folder appears at ~/.vellum/workspace/ on your machine. This is your assistant's brain. Plain text files, fully readable and editable by you.
Your assistant wakes up. It introduces itself and asks who you are. This is the onboarding conversation, and it's genuinely more fun than any setup wizard you've used.
You start talking. Name it, shape its personality, tell it about yourself. Or skip all that and just ask it to do something. It's flexible like that.

What gets installed

Vellum creates one directory on your machine:

~/.vellum/
|-- workspace/
|   |-- IDENTITY.md    <- Your assistant's name, personality, emoji
|   |-- SOUL.md        <- Core principles and behavior rules
|   |-- USER.md        <- What your assistant knows about you
|   |-- LOOKS.md       <- Avatar appearance (yes, it has a wardrobe)
|   |-- config.json    <- Configuration
|   '-- skills/        <- Installed and custom skills
-- ...

Everything is plain text. 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.

Permissions

Your assistant may ask for macOS system permissions during use:

Permission	What it enables	When it's requested
Full Disk Access	Reading files outside the sandbox (Downloads, Documents, Desktop)	When you ask it to look at files in those folders
Screen Recording	Seeing what's on your screen	When you want it to observe or interact with your screen
Accessibility	UI automation features	When you want it to control your computer

Worth knowing: Full Disk Access means your assistant can read files anywhere on your machine when you approve individual actions. That's what makes it useful. It's also worth being intentional about. Check out Trust & Security for the full picture.

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.

Desktop App

The easiest way to get started is by downloading the Vellum Assistant desktop application. It handles all configuration and setup automatically.

Visit the downloads page and download the installer for your operating system.
Run the installer and follow the on-screen prompts.
Once installed, open the Vellum Assistant app.
The app will automatically configure your environment.

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

Connecting to your Vellum account unlocks additional features such as syncing assistants across devices, accessing shared knowledge bases, and managing environments from the Vellum platform.

To connect your account, run the following command:

vellum login

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.