Installation - Vellum Docs

What you need

For the web app: any modern browser. No install, no setup. The fastest way in. Connects to a cloud assistant.
For the desktop app: macOS 15 (Sequoia) or later, Apple Silicon or Intel, plus ~500 MB free disk space. Connects to a cloud or local assistant.
Internet connection (your assistant uses cloud AI models to think)
About 5 minutes and a willingness to talk to your computer

Web

The fastest way to meet your assistant. No install, no setup wizard, no config files. Your assistant runs in Vellum Cloud and you reach it from your browser.

Go to vellum.ai/signup and create your account.
Set your privacy preferences and accept the Terms of Service.
Watch your assistant hatch in the browser. About 30 seconds.
Say hi.

Your assistant lives in Vellum Cloud, encrypted and isolated to your account, reachable from any browser. You can also connect the desktop app, mobile app, voice, and chat channels (Telegram, Slack, phone) to the same assistant.

Desktop app

The desktop app gives you a menu bar presence, voice input with hold-to-talk, and the ability to control your Mac through accessibility APIs. It connects to a cloud assistant by default (so your conversations and memory show up in both the web and desktop apps), but it can also run a local assistant entirely on your machine. See Hosting options for the local-only setup.

Sign up for Vellum if you haven't already.
Download the macOS .dmg from your account dashboard.
Open the .dmg, drag Vellum to Applications, and launch it.
Sign in with your Vellum account. Your cloud assistant shows up automatically.

That's the whole process. No terminal commands, no package managers, no YAML files. Standard .dmg, signed and notarized.

Self-hosting

Want to run Vellum entirely on your own machine or your own infrastructure? You can. The runtime is open source and supports local-only mode (workspace at ~/.vellum/workspace/) as well as remote deployment to your own GCP or AWS environment.

Head to Hosting options for the full guide on local hosting and advanced deployment.

Two ways to connect

Sign in with Vellum (default) — Authenticate with your Vellum account for the managed experience. Your assistant runs in Vellum Cloud, billing is handled through your account, no API keys to manage.
Bring your own API key — Self-host the runtime and connect it to your own Anthropic API key. Useful if you want to run everything on your own machine. Your key is stored in your macOS Keychain.

What gets installed

If you run the desktop app or self-host, Vellum creates one directory on your machine. (Vellum Cloud users don't need to think about this. Your workspace lives in your encrypted cloud account and is available through the web app.)

~/.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.