EMMA
← Back

Help

Getting her running, your first hour, controlling what she remembers, and fixing what goes wrong. If none of this covers it, email me — I read everything.

Looking for everything she can do — every dial, panel and setting? That's the user manual. This page is the short one, for getting started and getting unstuck.

Installing her

1. Install Ollama first

Ollama is the free engine EMMA thinks with. It's a separate install and it's the one step people miss. If you skip it, EMMA's first-run setup will notice, hand you the right installer for your system, and carry on by itself the moment it's running.

2. Install EMMA

Get the latest build from Releases.

3. Your computer will warn you — here's why

The builds aren't code-signed yet, so:

Windows: "Windows protected your PC" → More info → Run anyway
macOS: "Apple could not verify EMMA is free of malware" → press Done, then System Settings → Privacy & Security, scroll down to the line about EMMA and press Open Anyway. You only do this once. (Before macOS 15, right-click the app → Open does the same.)

That warning means "unsigned", not "unsafe" — but you're right to be suspicious of it. Every release publishes SHA-256 hashes so you can check the file you downloaded is the file that was built.

4. First run picks a model for your machine

She looks at your RAM and GPU and suggests a model that will actually run well, rather than the biggest one. You can change it later — the model name in the top bar is a picker, and it warns you honestly when a model is too big for your hardware.

Your first hour

Three things show you what she actually is. Everything else can wait.

  1. Tell her something about yourself — then quit and come back tomorrow. Anything: what you do, what you're building, your dog's name. Close her completely, open her the next day, ask about it. That's the whole product in one move.
  2. Ask her to do something on your actual machine. "What's taking up space on my disk?" On the default dial (Full) she does it and tells you what she did; turn the dial to Ask and she waits for your OK first. Every action is written to a log you can read.
  3. Turn on Dream Mode before bed. Overnight she goes back over the day, makes connections, and leaves a short briefing for the morning.

She is as smart as your hardware lets her be. That's the honest trade for privacy. On a good GPU she's genuinely capable; on an old laptop she'll be slower and less sharp than a cloud assistant. Better you know now.

The safety dial — what she may do without asking

EMMA can act on your computer: read files, run commands, use a browser. The dial in the top bar decides how much of that happens without your say-so.

Two things sit above the dial and apply even on Full: protected paths (your SSH keys, GPG, cloud credentials — she is refused regardless of setting, and you can add your own in Settings → Protected paths), and the audit log, which records everything she does in a tamper-evident chain you can read line by line under Her world → Activity.

There's also a Stop button while she's working, and undo for file changes she made.

Memory: seeing it, forgetting it, taking it with you

Everything she knows is in the memory panel in the top bar. It's not a black box — you can read it, edit it and delete it.

Your export always works — during the trial, after it expires, whatever happens. Your memory is never held hostage to a payment.

Her memory is encrypted at rest from the first moment on a new install — AES-256, with the key in your operating system's keychain. The switch is Settings → Encrypt memory at rest, and when it's on she shows you a recovery key: write it down somewhere that isn't this computer.

When something's wrong

On Linux she opened in my browser, not in her own app window

Since 1.11.0 she opens in her own window on Linux too. She draws it with your system's own GTK and WebKitGTK, so if she opened in a browser instead, those pieces aren't installed. Add them with sudo apt install python3-gi gir1.2-webkit2-4.1 (the .deb asks for them itself; the AppImage can't) and start her again. Her world → Check-up has a window line that says what she found. If you'd rather have her in the browser, that's a choice too: Settings → Open in my browser instead.

She is running entirely on your machine either way, and every feature works. One difference worth knowing: in a browser tab, closing it doesn't stop her — she keeps running in the background, which is what lets her dream overnight. To stop her then, quit the emma process from your system monitor (or systemctl --user stop emma.service if you set up the background service). Closing her own window quits her, as on Windows and macOS.

She isn't reading anything aloud

Press the speaker beside the message box. If it turns itself back off, hover over it — she'll tell you what went wrong, and it's usually that no voice is installed yet: go to Settings → Her voice, pick one, and she fetches it once. Before 1.2.0 a failure like that was silent, so her voice appeared to come and go for no reason; if that's what you've been seeing, update.

She can't hear me

Since 1.4.0 she can. Press the microphone beside the message box and talk, or the headphones for hands-free conversation. The first time, she asks whether to download her speech model (about 148 MB, once); say yes and she hears you from then on, without ever using the internet again for it. If the mic button is missing entirely, you're on an older version — update.

Recognising who is speaking is a different feature with its own one-time download, in Settings → Knowing who's speaking. And working with audio or video files (transcripts, watching a video) needs ffmpeg, which she offers to fetch for you in Settings → Hearing you — talking to her doesn't.

She says Ollama isn't running

Ollama isn't installed, or isn't started. Install it from ollama.com; on Windows and macOS it starts itself after installing. On Linux the installer sets up a service, or run ollama serve. EMMA rechecks every couple of seconds and continues on her own once it's up — you don't need to restart her.

She's very slow, or the answers are poor

Almost always the model is too big for the machine. Open the model picker in the top bar — anything marked as a poor fit for your hardware will say so. A smaller model that runs fast usually feels far better than a large one that crawls. A first reply is also slower than the rest, because the model has to load into memory.

She won't act on my machine any more

Two likely reasons. The safety dial may be on Lock — check the top bar. Or your trial has ended: she stays as a read-only companion, still talking, with export still working, but she won't touch your machine until there's a licence. Nothing is deleted, and everything comes back when you buy.

She can't see a file, or refuses to touch one

Protected paths (credentials and key stores) are refused on purpose, at every dial setting. Everything else: check Her world → Settings — What she may do without asking and Protected paths.

On Windows or macOS, the window opened in my browser instead

She falls back to your browser when her own window can't start. She works exactly the same either way — it's cosmetic. On Windows or macOS that's worth telling me about, with your OS. (On Linux it's expected — see above.)

She stopped mid-answer, or said her model refused

Usually Ollama restarting, or a model that was removed or swapped. She retries and then says so in words rather than hanging. Check the model picker still shows something installed.

In the Studio, the camera says it isn't answering

Some USB webcams get stuck and stop answering, even with the camera allowed. Unplug it, plug it straight into the computer (not a hub, ideally a different port), then press Try the camera again. Record sound only keeps you going meanwhile. If your browser is asking whether to allow the camera, choose Allow: the camera icon at the left of the address bar.

I'm live, EMMA's light is green, but YouTube says "No data"

That's almost always an old stream key: YouTube still accepts it, so EMMA can't tell. Copy the key from YouTube Studio again, paste it into the place in the Go live tab and press Save the key.

Something just felt awkward

Type /papercut followed by what annoyed you. It logs instantly — no model call, nothing sent anywhere. Later, type /papercuts to see them all with a Copy all button, bundled with your OS, hardware and model version. Paste that into an email to me.

Small annoyances are the most useful thing you can send. Big bugs I'll find myself. It's the "this felt off and I can't say why" ones I can't see from in here.

Trial, buying, refunds

60 days, everything unlocked. When it ends she becomes a read-only companion — still talking, export still working, nothing deleted. If you buy six months later, everything she remembered is still there.

Buying is open — £149 once, yours forever, from the pricing section. Your key arrives by email straight after checkout; if it hasn't turned up in a few minutes, check spam and then email me and I'll resend it by hand.

14-day no-questions refund, and your licence is checked on your own machine with no server involved. Full terms in plain English: the licence.