Guide

What is this

Soma isn't an AI in a chat window. It's a companion that floats on your desktop, that you can see, and that can act.

• A presence: a VRM/Live2D character floats transparently on your desktop, always on top, lip-syncing and emoting.
• A voice: sentence-by-sentence streamed speech, with the mouth in sync.
• A memory: each character remembers what mattered in your conversations.
• Hands (Advanced): open pages, tidy files, control music — acting on your real desktop, not just talking about it.

Quick start

Four steps from install to your first sentence.

1. Drag Soma Agent into Applications, then open it (opening straight from the dmg leaves it unfindable later).
2. Pick your interface language. You can change it later, and it does not lock what language characters speak.
3. Under ⚙ Settings → License, enter your email for a 7-day trial, or paste a license key you bought.
4. Under ⚙ Settings → AI Model, paste an API key (or pick Ollama for a free local model) — then start talking.

Soma deliberately has no Dock icon — that translucent character on your desktop is the app. If you lose the window, search "Soma" in Spotlight.

AI models & keys

Soma doesn't resell AI credits. You connect with your own API key straight to the provider and pay them for what you use — your conversations never touch our servers. That's BYOK.

Anthropic (Claude)

console.anthropic.com | the only one with desktop tools, image and PDF reading

OpenAI (GPT)

platform.openai.com | chat only

Google Gemini

aistudio.google.com | chat only

Ollama (local)

ollama.com | free, nothing leaves your Mac, chat only

Your key lives only in secrets.json on this Mac (file mode 600), readable only by the Rust side — it never reaches the web layer, and never reaches us.

Cost depends on the model. Haiku is cheapest — a casual message is a fraction of a cent. Opus, or large attachments every turn, climbs noticeably. Ollama is free.

License & trial

Enter your email under ⚙ Settings → License to start a 7-day free trial — no payment details. Your key is emailed to you; keep it for when you switch machines. The trial covers Basic features.

When the trial ends your characters, settings and memories all stay — you just cannot send messages. Purchase, paste the key, and pick up where you left off.

One-time purchase, no subscription: Basic NT$599, Advanced NT$899 (two extra characters plus desktop tools), Podcast dual-character add-on NT$399.

Basic covers 1 machine, Advanced 2. To move, hit Deactivate on the old Mac first, then paste the same key on the new one.

Buying and activating

Pick a plan at soma-agent.com and check out through Paddle (credit cards and common wallets). One-time purchase, no subscription.

1. Choose Basic or Advanced under Plans on the website; add Podcast if you want two characters talking to each other.
2. Complete payment in the Paddle checkout. Use an email address you can actually receive mail at.
3. Your licence key is emailed to that address, usually within a few minutes.
4. Open Soma Agent → ⚙ Settings → Licence, paste the key and press Activate.

No key in your inbox? Check spam first, then use the Recover key page on the website with the same email. Still nothing — write to soma-agent.com.">support@soma-agent.com.

The My account page on the website emails you a sign-in link, no password needed. From there you can see your licences, which machines are bound, and unbind an old computer.

The Podcast add-on needs your existing licence key entered at checkout so it attaches to the same licence. Refunds follow the refund policy on the website.

Characters, memory & language

Switch or add characters under ⚙ Settings → Character. Each keeps its own persona, memory and look, entirely separately.

Language and voice are set per character and can be changed any time — any character can speak any language. Reply language lives under ⚙ Settings → Character, the voice under → Voice.

Characters remember what you talked about and gradually distil it into long-term memory. View or clear it in character settings.

With the Podcast add-on, the two-person icon above the input lets two characters talk to each other while you watch, or with you joining in.

Voice

Add your Azure Speech key and region under ⚙ Settings → Voice to give characters a voice; without it Soma falls back to the system voice.

Voice input: hold the right Option key to talk, release to send. macOS needs Input Monitoring permission, and the hotkey is changeable.

Import your own model

⚙ Settings → Appearance → Import model. Both .vrm and Live2D (folder or zip) work, and imported models are never restricted by your plan.

Live2D textures must be RGBA PNG. Indexed/palette PNGs will leave the character stuck on "Loading…".

Troubleshooting

No Dock icon

Expected — the pet deliberately stays out of the Dock. The character on your desktop is the app.

Character stuck on "Loading…"

Usually an imported texture that is not RGBA PNG. Convert it and import again.

Attachment says Claude only

Images and PDFs only work on Anthropic models. Switch the chat model back to Claude.

No sound

Check the Azure key and region under ⚙ Settings → Voice, and that system volume is not muted.

Voice input does nothing

Allow Soma under System Settings → Privacy & Security → Input Monitoring.

Fetching a page returns nothing

The web tool is Anthropic-only and needs a full http(s) URL.

Platform & shortcuts

macOS for now (Intel and Apple Silicon). Windows is planned, and a Mac App Store release is on the way.

Voice input (hold to talk)

Right Option (changeable)

Send message

Enter

Turn / zoom / reset character

Right-drag / scroll / double-click