← Onidia
Setup guide · 01

Give her a brain.

Gemini is the default provider and the easiest one to start with: a free key, no account to manage, no billing. Five minutes and she starts answering.

Free tier No card needed ~5 minutes

The whole thing

1

Get the key

Sign in with any Google account and create an API key. It appears exactly once — copy it straight away or you will have to issue a new one.

where to go
https://aistudio.google.com/apikey

Click Create API key, choose a project (Google makes you create one if you have none), then copy the key. It starts with AIza and is 39 characters.

2

Open her config file

The package put it there for you. If it does not exist yet, create the directory and an empty file — the app is happy with a partial config.

terminal
mkdir -p ~/.config/chat-app
nano ~/.config/chat-app/chat-app.ini
Where she looks for it

First ./chat-app.ini, then the file next to the running binary, then ~/.config/chat-app/chat-app.ini. On a package install the first two cannot see it, so this path is the one that actually matters.

Both programs walk exactly that list. onidia the buddy reads the same file as onidia-chat, so a sleep window or busy window set here reaches her too.

3

Paste the key in

Three lines are enough. The provider key at the top picks which section she reads, so it has to be gemini.

~/.config/chat-app/chat-app.ini
provider = gemini

[gemini]
api-key = AIzaSy...your-key...
gemini-model = gemini-3.6-flash
gemini-api-url = https://generativelanguage.googleapis.com

Save with Ctrl-O, then Ctrl-X.

4

Check it worked before you launch

onidia-chat verifies the key and the whole environment before it opens a window. If anything is wrong it tells you what, instead of failing mysteriously later.

terminal
onidia-chat -preflight warn

Look for the Gemini line coming back green. Then start her.

5

Start her

The buddy first — it creates the speech pipe the chat window writes into. Then the brain, in a second terminal.

two terminals
# terminal 1 - the body
onidia

# terminal 2 - the brain
onidia-chat

If you would rather not store the key

Environment variable

Export it for the session instead of writing it to disk. The env var wins over the config file, so you can keep a config with no key in it at all.

terminal
export GEMINI_API_KEY="AIzaSy..."
onidia-chat

Make it permanent

Append it to your shell profile so every new terminal has it. Convenient, but it means the key is in a plaintext file like the config anyway.

terminal
# add to ~/.bashrc or ~/.zshrc
export GEMINI_API_KEY="AIzaSy..."

Command line only

Good for a one-off, and it never touches a file. The flag beats both the config and the environment.

terminal
onidia-chat -api-key "AIzaSy..."
Precedence, so nothing surprises you

-api-key flag → GEMINI_API_KEY or GOOGLE_API_KEY in the environment → api-key in the config file → built-in default. First one found wins.

If it goes wrong

"api key not valid"

Almost always a paste problem: a leading space, a trailing newline, or quotes included. The key must be the bare 39 characters, nothing around it.

No reply, no error

Run onidia-chat -preflight warn. It probes the real endpoint and prints the status code the API returned, which is far more useful than a silent window.

Rate limited

The free tier has a per-minute quota. A 429 in the log means you are sending faster than it allows; wait a few seconds between long chats.

Still nothing

She may be pointed at a different provider. provider at the top of the config decides which section she reads — it must say gemini.