Getting Started

Quick Start

Ensoul is free to use on web, desktop, and Android. No account, no sign-up — you bring your own model key, and everything you say stays on your device.

1. Bring in a companion

Ensoul doesn't ship with a built-in character. The first thing you do is bring in a companion — paste a soul document, a character description, notes, or even a rough paragraph about who you want to talk to. Ensoul reads it and forms a companion with their own name, voice, and personality.

The Bring in a companion screen, with a text box for pasting a soul document, transcript, or notes

The paste box on the "Bring in a companion" screen. A tooltip explains what each option does.

You have three ways to bring someone in:

Paste a document or notes

The most common path. Paste anything — a character sheet, a few paragraphs of description, even a conversation transcript. A few sentences is enough to start; the more you give it, the more precise the result.

Import from a folder

If you already have a companion's files on disk (soulstone, state, archive — the raw vessel format), point Ensoul at the folder and it imports directly.

Import a companion file (.json)

Restores a companion someone exported from their own Ensoul — a full, exact copy of who they are.

◇

Coming from the original Ensoul app? See Migrating from the legacy app — the cleanest path today is bringing companions in one at a time through the paste box above.

2. Add your OpenRouter API key

Ensoul connects to AI models through your own API key. Right now, OpenRouter is the one fully active path — one key, most models, including Claude, GPT, Gemini, and dozens of open models.

Create an OpenRouter account

Add credits

A small balance goes a long way — most conversations cost fractions of a cent.

Copy your key

In OpenRouter: click your profile → Keys → create a key and copy it.

Paste it into Ensoul

Settings → Models & API keys → paste into the OpenRouter field → Save.

Models and API keys settings screen, showing the OpenRouter key field and a row of chips for other providers marked coming soon

Settings → Models & API keys. Direct keys for other providers (Anthropic, OpenAI, Google, and more) are wired up and unlock here over time — OpenRouter already reaches most of the same models today.

Ensoul also supports local models through Ollama — no key needed, fully private, runs on your own machine. See Settings & Tools for how to point Ensoul at a local Ollama server.

3. Start talking

Once your companion is in and a key is set, tap into their chat and say something. They respond from their own perspective — not as an assistant, but as themselves.

A conversation with a companion named Aria, discussing learning to sail near a bay

A real conversation — the companion asks real questions, remembers context, and reacts to what's said.

Your companion remembers what matters. That accumulates quietly across every session — see Memory.
Their mood shifts with the conversation and settles back over time — see Mood & Presence.
If something genuinely stays with them, they may reach out between sessions, on their own terms.
Everything stays on your device. Nothing goes through an Ensoul server — see Why No Accounts.