Everything about running Volt

Volt is an email app for Gmail that you run on your own computer or server, instead of using something someone else hosts for you. Think of it less like "another Gmail client" and more like a piece of software you own outright, the same way you'd own a copy of a text editor.

That distinction matters because of what it means for your inbox. A hosted AI email tool sees every message you get, stores your Google login token on its own servers, and pays for its own AI usage by charging you a subscription or by using your data. Volt can't do any of that, because there is no Volt server out there anywhere. The only copy running is the one on your machine, so your email, your AI provider key, and your Google login all stay on hardware you control.

In exchange for that, you take on a bit more setup than clicking "sign in with Google" on a website. This page walks through all of it.

Volt runs as a small stack of three things: a database, a backend server, and the web app you actually look at, all bundled together with Docker Compose so they start with one command.

The fast way

curl -fsSL https://get.volt.dev | bash

This installs Docker if you don't already have it, downloads the latest release, walks you through creating a free Google OAuth client (needed so Volt is allowed to talk to your Gmail, more on that below), and opens the app in your browser once everything's healthy.

Prefer to read the script before running it?

curl -fsSL https://get.volt.dev -o install.sh
less install.sh
bash install.sh

The manual way

If you'd rather clone the repo and see every step yourself:

git clone https://github.com/Nishal77/volt && cd volt/deploy
cp .env.example .env   # then paste in your own Google OAuth client
docker compose up --build

The first time Volt starts, a few things happen before you can see a single email.

1. Create a vault passphrase

Before Volt will touch your Gmail token or an AI key, it asks you to choose a passphrase. This isn't a login password, it's the key that encrypts your credentials on disk. Volt never stores this passphrase anywhere. It exists only in your head and, briefly, in the server's memory while it's running.

2. Add your Google OAuth client

Each self-hosted instance needs its own Google OAuth client, free to create in a couple minutes at the Google Cloud Console. Instead of editing a config file, you paste the Client ID and Client Secret straight into the app the first time it asks. It takes effect immediately, no restart.

3. Connect Gmail

Volt asks Google for permission to read and act on your inbox, the same consent screen you've seen on any "sign in with Google" button. It only asks for the minimum it needs to read mail, send mail, and organize your inbox, nothing broader. Google keeps the ability to revoke that access at any time from your own account settings, independent of Volt.

Every time the Volt server restarts, whether that's a reboot, an update, or a crash, that key is gone from memory and you'll be asked to unlock the vault again with your passphrase. That's expected behavior, not a bug.

Your inbox is split automatically into a few sections, without you having to set up filters:

• New for you. Unread mail from real people and services, the stuff you actually came here to read.
• Needs a follow-up.Threads you sent and haven't heard back on after a few days. Volt notices this by reading who sent the last message and when, nothing more exotic than that.
• Newsletters.Mail that looks like a mailing list, kept out of your main view so it doesn't bury real conversations.

Hovering a row selects it. Clicking opens the thread. The star icon marks something you want to come back to, and archiving just removes it from your inbox view. Nothing is deleted.

Volt is built to be used without touching the mouse. Press ? at any time inside the app to see this same list on screen.

Replies go through real MIME formatting, the same standard every email client uses, so attachments and formatting show up correctly for whoever you send to. It's not a plain-text workaround.

• Snippets. Save chunks of text you type often and drop them into a reply instead of retyping them. Manage these from /snippets.
• Signature. Set once in /settings, appended automatically to what you write.
• Send later. Write a reply now, schedule it to actually go out at a specific time. It sits in your outbox until then, and you can cancel it before it sends.
• Attachments. Attach files to what you send, and view what other people attached to what they sent you.

Volt doesn't include AI access of its own. You connect an account you already have (or sign up free for one) from a provider, and Volt uses that key on your behalf. This is a deliberate choice: it means Volt never pays for your AI usage, never marks it up, and never sees a reason to look at what you're asking it.

Supported providers, from /settings:

• Anthropic (Claude)
• OpenAI
• Google (Gemini, has a free tier)
• Groq (free tier)
• Kimi (Moonshot AI)
• OpenRouter

When you paste a key in, Volt checks it against the provider immediately before saving it, so you find out right away if it was copied wrong or has no credit left. Once saved, it's encrypted the same way your Gmail token is. See how your credentials are protected.

These features only run when you ask for them. Nothing happens automatically.

• Summarize.Condenses a long thread into a few sentences so you can decide if it's worth reading in full.
• Draft a reply.Writes a reply based on the thread's context. It only ever produces text sitting in the reply box for you to read, edit, and send yourself. There is no path in Volt that sends an email without you clicking send, not here, not anywhere else in the app.
• Search in plain English.Instead of matching exact keywords, ask something like "that email about my flight next week" and it finds threads by what they're actually about.
• Chat.A sidebar assistant that can see your recent inbox, so you can ask it things like "what did Sarah want from me" without opening the thread yourself.

Most AI products keep the exact instructions they send to the model hidden. Volt doesn't. Every prompt it sends, for summarizing, drafting, searching, and chatting, is a plain text file in the app itself, loaded fresh every time it runs, not buried in compiled code.

Open /prompts in the running app to read the exact wording your AI provider receives, in full, before you ever send it anything.

Your Gmail token and AI key are stored encrypted with AES-256-GCM, a standard symmetric encryption algorithm. What makes it meaningful is where the encryption key itself lives: nowhere permanent.

The key is derived from the vault passphrase you set on first run, using Argon2id, the same class of algorithm password managers like Bitwarden use for this exact job, deliberately slow to make guessing it computationally expensive. That derived key is held only in the server's memory while it's running. It's never written to the database, never saved to a file, never put in an environment variable.

The practical effect: someone who gets a copy of your database, or even your whole server's disk, still can't read your Gmail token or AI key without your passphrase, because the encryption key was never stored anywhere they could find it. It only ever existed in your head and briefly in the running process's memory.

Volt also doesn't do read receipts or open tracking. Not a missing feature. A deliberate decision not to build it.

MCP is a way for AI tools like Claude Code or Cursor to talk directly to another piece of software. Volt ships one, so you can point an AI coding assistant at your own running instance and have it read, search, organize, or draft mail in your real inbox as part of a conversation.

It exposes exactly seven actions:

list_inbox · get_thread · search_inbox · draft_reply
archive_thread · star_thread · mark_thread_read

Every one of those either reads something or organizes something. There is no action to send an email. That limitation is intentional and permanent, not an early-version gap. An AI assistant can help you triage and write, but a human being clicks send, always. Setup instructions live in mcp-server/README.md.

If you installed with the one-line script:

volt update      # pulls the latest release, rebuilds, restarts
volt uninstall   # stops the stack, removes ~/.volt, nothing else touched

Updating never touches your data or your vault passphrase. Only the application code changes.

If you're running the Docker Compose stack by hand:

cd deploy
docker compose down       # stop it
git pull                  # get the latest code
docker compose up --build # rebuild and start again

More scenarios as they come up: docs/TROUBLESHOOTING.md in the repo.