Common Issues

Installation

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

This is a standard macOS Gatekeeper warning for apps not distributed through the App Store.

Fix: Right-click (or Control-click) the app in Finder → select “Open” → click “Open” in the dialog. This only happens once.

The app won't launch / crashes on startup

Try:

1. Make sure you're on macOS 14 (Sonoma) or later.
2. Check that Docker is running (your assistant runs in a Docker container)
3. Try deleting and re-downloading the app
4. Check Console.app for crash logs if the issue persists

Permissions

“Operation not permitted” error

A macOS system permission is missing. Your assistant needs the relevant permission granted through System Settings.

Fix: Your assistant will show a clickable prompt that takes you directly to the right System Settings panel. Grant the permission, then try again.

If the prompt doesn't appear, manually go to: System Settings → Privacy & Security → find the relevant permission category (Full Disk Access, Screen Recording, or Accessibility) → toggle Vellum on.

I clicked “Don't Allow” by accident

No problem. Your assistant won't retry automatically. Just tell it: “Try that again” or “Go ahead and access that file.” It'll send a new permission prompt.

My assistant keeps asking for the same permission

Each individual action gets its own prompt. This is by design, not a bug. If your assistant needs to read three different files, that's three separate Allow prompts. This is how the permission model ensures you're aware of every access.

If this feels excessive for your workflow, let us know. We're exploring ways to make this smoother without compromising transparency.

Skills & services

A skill won't load

Try:

1. Ask your assistant: “Why isn't the [skill name] skill working?”
2. Check if the skill requires setup (OAuth connection, API key, etc.)
3. Try reinstalling: “Reinstall the [skill name] skill.”

OAuth connection failed (Google Calendar, Slack, Gmail)

Try:

1. Make sure you have an active internet connection
2. Try the connection again: “Reconnect my Google Calendar”
3. Check that you're logging into the correct account
4. If using a corporate Google account, your organization may block third-party OAuth apps. Check with your IT department.

Email isn't working

Check:

1. Has email been set up? Ask: “Is your email set up?”
2. If not, run setup: “Set up your email”
3. If it was working before, try: “Reconnect your email”

DoorDash orders not going through

Check:

1. Is your DoorDash account connected? “Is DoorDash set up?”
2. Is your delivery address correct? “What address are you delivering to?”
3. Is there a payment method on your DoorDash account? (Managed in DoorDash, not in Vellum)

Performance

My assistant is slow to respond

Response time depends on:

1. The AI model provider — Cloud API latency varies. Complex requests take longer.
2. Tool execution — Actions like web browsing or API calls add time.
3. Context size — Very long conversations with lots of loaded skills can slow things down.

Try:

• Start a new conversation (resets context length)
• Check your internet connection
• Try a simpler request to see if the issue is task-specific

My assistant forgot something I told it

Possible reasons:

1. It wasn't saved. Your assistant doesn't save everything automatically. For important info, say “Remember this: [fact].”
2. It's in a different conversation. Memories carry across conversations, but conversation history doesn't. Important context should be saved to memory or workspace files.
3. It was saved but not recalled. Memory search is associative, not perfect. Try asking more specifically: “What do you remember about Project Moonshot?”

Workspace

My workspace files look wrong or corrupted

Your workspace is plain text files. If something looks off:

1. Open the file in a text editor and check for formatting issues
2. If a file is genuinely corrupted, delete it. Your assistant will recreate default versions on next launch.
3. If you're using version control (git), you can revert to a previous state

I accidentally deleted a workspace file

• IDENTITY.md, SOUL.md, USER.md, LOOKS.md — Your assistant recreates these with defaults on next launch. You'll lose your customizations but not your assistant.
• Memories — If the memory store is deleted, saved memories are gone. There's no automatic backup.
• Custom skills — If you delete a skill folder, that skill is gone. Reinstall from the catalog or rebuild it.

💡 Pro tip: Consider putting your workspace under version control with git. It's a folder of text files, perfect for git. Then you can always revert mistakes.