Skip to content
eternego / docs

Onboarding

The create-or-restore wizard — the screen you see before any persona exists, or when you click + in the sidebar. It has two flows: create a new persona, or migrate (restore) one from a diary file. This page documents every field in both and the endpoint each submits to.

You reach it at /onboarding (the choice screen), /onboarding/create, or /onboarding/migrate. With no personas at all, the app sends you here automatically.

The choice screen

/onboarding shows two cards:

A brand bar across the top reads "running locally on your machine". If you opened onboarding from an existing persona (via +), a "back to {name}" chip returns you to her chat.

Create a new persona

/onboarding/create. Three cards, stacked. Each unlocks the next once it's filled — the second is dimmed until you've named her, the third until her Mind is configured. Only the first two are required.

Step 1 — Her name

Field Type Required Notes
Name text yes Her display name, e.g. Iris. That's all she needs to begin — no bio, no persona description, no traits. She shows you who she is through talking.

Step 2 — Her Mind

The one required organ. This card is an organ configurator (the same control used in Settings and the migrate flow). First pick Local or Cloud:

Local (Ollama, runs on this machine):

Field Type Required Notes
Model name text yes The Ollama model id, e.g. qwen2.5:14b. Eternego pulls it for you if you haven't already.
URL text no Advanced. Defaults to http://127.0.0.1:11434.

A local Mind sends no provider and no API key. On the backend it's registered as a custom eternego-<id> model wrapping the base you named.

Cloud (a provider's API). Pick a provider tile, then fill three fields:

Field Type Required Notes
URL text yes The provider's base endpoint — pre-filled when you pick a tile. Do not append /v1; the platform layer adds the right suffix per provider.
API key password yes Stored locally on this machine only.
Model text yes The provider's model name, e.g. claude-sonnet-4.5.

The provider tiles offered are Anthropic, OpenAI, Gemini, xAI, DeepSeek, Together, and OpenAI-compatible (a custom endpoint, URL left blank for you to fill). The tile you pick becomes the provider slug sent to the backend. Of these, anthropic, openai, gemini, and xai have native handling; deepseek, together, and openai_compat are all driven through the OpenAI-compatible client — any provider that speaks the OpenAI chat protocol works by picking OpenAI-compatible and entering its URL.

Step 3 — Channels (optional)

A channels configurator in deferred mode: tokens you enter here are held and submitted together with the create request, not posted live. She's always reachable in this browser; Telegram and Discord are extra.

Field Type Notes
Telegram bot token password Validated against Telegram at create time.
Discord bot token password Validated against Discord at create time.

You can skip this entirely and add channels later in Settings → Channels.

Submitting

Wake her up posts everything to POST /api/persona/create as JSON. The fields map to the request model like this:

Card field Request field
Name name
Mind provider / model / URL / key thinking_provider, thinking_model, thinking_url, thinking_api_key
Telegram token telegram_token
Discord token discord_token

The create screen only sends the Mind organ; the other six organs are added afterward in Settings. (The endpoint itself accepts all seven organ groups — see Create and migrate — but this screen doesn't expose them.)

The recovery phrase

On success the screen shows her recovery phrase — 24 words, shown once. This is the only key that unlocks her diary if you ever migrate her. You must Copy or Save as a file before the Meet {name} button enables. There is no way to see it again later; save it somewhere safe.

The phrase comes back in the create response as recovery_phrase (see the response shape). After you acknowledge it, the screen routes to her Chat.

Why it works this way

The phrase is the encryption key, and Eternego never keeps a copy — which is exactly what lets her diary be backed up or sent anywhere and still be readable only by you. The trade: lose it and no one (Eternego included) can recover it, so she keeps running here but can't be moved to another machine. See Vocabulary: recovery phrase.

Restore from a diary (migrate)

/onboarding/migrate. Use this when you have a persona's .diary file and her recovery phrase — moving her to a new machine, or rebuilding after a reinstall. Three steps:

Step 1 — Her diary

Field Type Required Notes
Diary file file yes Drag-and-drop or click to pick her .diary file (accepts .diary / application/octet-stream). It's decrypted with the phrase from step 2.

Step 2 — Her recovery phrase

Field Type Required Notes
Recovery phrase textarea yes Paste the words she gave you at creation. Order matters.

Step 3 — Her Mind

The same Mind configurator as the create flow (Local / Cloud, identical fields). The Mind is not part of the diary — it's local to this install, so you choose how she thinks now. The other organs are restored from the diary.

Submitting

Bring her back posts to POST /api/persona/migrate as multipart form (because of the file upload). The fields map like this:

Step field Form field
Diary file diary
Recovery phrase phrase
Mind model / provider / URL / key model, provider, url, api_key

As with create, this screen sends only the Mind; the other organ form fields the endpoint accepts are not exposed here. On success there's no phrase reveal — the phrase is already yours — and the screen routes straight to her Chat.

Errors

Both flows surface the endpoint's error detail inline (an invalid key, a wrong phrase, a channel token that won't validate) and drop you back to the input step so you can fix it. The status codes and messages are documented in Create and migrate.