On this page
Where an answer quotes the bot, the quote is its own text with example names and numbers filled in. Setup, step by step, is on Get started; what the bot keeps is on Privacy and memory.
How do I start?
Address the bot: mention it by picking it from the @ list, reply to one of its messages, or send it a direct message. Then run /start. It shows you, privately, how to add a key of your own, or which provider and model answer you if you already have one. Get started walks through it.
If the operator runs a free trial, your first messages can be answered before you add a key: see the free trial.
What does it cost, and who pays?
Your replies run on your own API key, so your provider bills the account behind that key, at its prices.
- The bot has no spending cap of its own. To cap what you spend, set a limit at your provider.
- To start for free, Google Gemini gives free API keys without a card (its free tier lets Google review your messages), and OpenRouter's free models work on a new account.
- Making an image is charged by the image provider, on your key.
- Free trial replies are paid for by the operator.
How do I add a key, and is it safe?
You seal the key first on the seal page, which scrambles it in your browser, so your key itself never passes through Discord. Then save what it gives you on the terminal, under Add a key for another provider, or with /setkey in a DM with the bot. If the terminal shows Connect OpenRouter, it gets a key from OpenRouter for you and stores it, with nothing to seal. Get started has the steps.
/keyslists each key's name and the date you saved it.- The operator can read keys while they are in use. Privacy and memory says exactly what is and is not protected.
- You can hold up to 3 keys per provider. Saving another key for a provider adds it;
/setkeywithreplaceswaps one. - If the start of the key names a different provider from the one you picked, the bot names the provider to pick, and the sealed blob still works for a second try.
- To remove a key, run
/revokekey, or pressRemovebeside it on the terminal. This does not disable the key at the provider.
Which providers and models can I use?
The bot knows eight providers: OpenRouter, Anthropic, OpenAI, Google Gemini, xAI, Mistral, DeepSeek and Groq. The operator chooses which of them it offers; the terminal's Provider for the new key list shows those.
- To change the provider that answers you, run
/umbris provider, or pick it underFirst choiceon the terminal and pressSave. - To change the model, run
/umbris model, or pick it underModelon the terminal.Automaticuses the provider's default model. - If you never choose, the bot answers with a provider you hold a key for.
Why doesn't the bot answer?
Check these first:
- Your message must address the bot: a mention picked from the
@list, a Discord reply to one of its messages, or a direct message.@everyone,@hereand role mentions do not count. - In a server, the bot answers only where the operator has set it to serve. Direct messages are answered only if the operator has turned them on, and only while you are a member of a server the bot serves.
- If the bot's replies have been turned off for you,
/umbris helpstarts with this line, and a moderator is the person to ask:
The bot isn't responding to you here. If you think that's a mistake, ask a moderator.
The bot can also turn a message away for a moment. Wait, then send it again:
You have reached this bot's limit of 6 turns per 60 s; further turns are ignored for the next 42 s.
I am busy with 2 turns already; try again in a moment.
The bot is restarting and stopped working on this. Please ask again in a minute.
The numbers are examples: the operator sets the limit. Only the first message turned away gets a notice; others right after it get no reply.
The bot says I have no key
You have no key for OpenRouter. Check your DMs, I've sent you the setup.
The bot holds no key of yours for the provider that would answer you, OpenRouter in this example. Run /start to see the setup privately, then save a key as in Get started.
If you hold a key, but not for the provider your replies use, the bot tells you to switch instead:
You're on OpenRouter, but your key is for Mistral. Switch your first choice to Mistral with /umbris provider -> Mistral.
You're on OpenRouter, but your keys are for Mistral and Groq. Switch your first choice to one of them with /umbris provider.
Run /umbris provider and pick the provider under use, or pick it under First choice on the terminal and press Save.
You're on OpenRouter, and no key you hold works here. /keys lists yours; /start shows how to add one.
None of your keys is for a provider this bot offers. Save a key for one it does offer.
A reply failed. What do I do?
When your provider turns a request down, the bot moves on before giving up: to your other keys for that provider when it limited, refused payment or rejected a key, then to your backups in order. The reply then carries a line that says what happened:
Fallback: OpenRouter refused the request under a rate or quota limit. Served by Mistral (mistral-small-latest).
Here OpenRouter turned the request down and Mistral answered; the names and the model are examples. The bot moves on when the provider limits your key, refuses payment, rejects your key, does not offer your chosen model, or is unavailable or stalls. It skips a backup whose context window is smaller than your first choice's. It moves on only at the start of a reply: once a provider has answered anything in this turn, a later failure ends the reply there, and the work so far may be saved for you to continue.
If no key or backup is left to try, the line ends Last tried instead, and the provider's own message follows. With one key and no backups, you get that message straight away. Find yours below:
- The provider is limiting your key. Wait as long as the line says, or until your plan's limit resets, then send again. A backup answers in the meantime next time: see Set up a backup.
Your key works; Mistral is limiting it. Try again in about 3 minutes.
- The provider will not take payment. Check that account's plan and balance at the provider. On OpenRouter, pick a free model (its id ends in
:free) or add credits.
Mistral wouldn't charge this key for this model; check that account's plan or billing.
- The provider rejected your key. Check the key at the provider, then seal a fresh one and save it with
/setkeyandreplace, or remove it with/revokekey. If another key or backup answered, the reply ends with a line naming the rejected key.
(error: AuthenticationError -- DeepSeek rejected your stored API key. Check the key with that provider, then seal a fresh blob and submit it with
/setkey.)
- The provider does not have the model. Choose another model with
/umbris modelor on the terminal.
(error: NotFoundError -- the provider could not find the requested model or endpoint; choose another model on the terminal. If the server default also fails, ask the operator to check it.)
- The provider is down or slow. Try again later, or switch models or providers.
(error: InternalServerError -- the provider reported a server failure; try again later.)
(error: the model was slow to respond. Try again, or switch models with /umbris model.)
A key that the provider rejects or will not charge, or that fails three times, is rested for up to 15 minutes. If another key or backup works meanwhile, the bot uses it. If you ask while every key and backup is resting, the bot says until what time, in UTC: ask again then, or save a fresh key, which is not rested.
Any other error line has the same shape: what went wrong, two hyphens, then what to do. Do what the part after the hyphens says.
How do I set up a backup?
A backup is another provider you hold a key for, tried when your first choice turns a request down.
- On Discord, run
/umbris fallback.Automaticuses the bot's backups,No backupsturns them off, or name up to 3 providers in order. - On the terminal, under
Backups if it fails, chooseMy own orderand pickBackup 1and the rest, then pressSave. - When you save a key for another provider, the bot can offer it as a backup, with
YesandNobuttons:
Use Mistral as a backup if OpenRouter fails?
A reply is slow or stopped partway
While the model works, Discord shows the bot typing, and after a minute the bot posts this line, which it removes when it finishes:
Still working on this (over a minute so far).
Every reply has a time limit, set by the operator. If the bot runs out of time while still working, it says so:
(error: stopped at this bot's 5-minute limit; ask for less at once.)
The 5 minutes is the default. Ask for less at once, or try a faster model with /umbris model. If part of the answer was already written, the bot may have kept it: see Continue a reply.
How do I continue a reply that stopped?
When a reply stops after the bot has written part of it, the message can end with this line:
(Work saved in this running bot. Address me with ‘continue’ here, or reply to this cut.)
In a server, use Discord's reply on that message and send continue, or mention the bot and send continue after the mention. In a DM with the bot, send continue. Capitals and a full stop or exclamation mark at the end are fine; any other words make it a new request. The saved work lasts only while the bot runs, and sending the bot another message in that channel can drop it.
How do I stop a reply?
Run /umbris stop. It stops your queued and running work and tells you privately what it stopped, for example:
Stopped: 1 reply.
A reply the bot has already started to post finishes. Stopping also discards your saved work. Editing or deleting your message does not stop a reply.
The bot answered with no text
The provider declined to answer this one.
The provider's own filter refused to answer. Rephrase, or pick another model with /umbris model.
(no reply: the model returned no text (reason: unknown).)
The model sent nothing back. Try again, or pick another model.
How does the free trial work?
When the operator runs a free trial, a member who has never chatted with the bot can get a few replies before adding a key. Mention the bot in a server; in a DM the bot answers with the setup instead. Each trial reply ends with the replies you have left:
Trial: 9 of 10 left.
The numbers are examples: the operator sets the allowance. A reply that ends in an error can still use up a reply. One the provider turned down at the start, because of a rate limit, the key or payment, does not. When none are left, or once you save a key of your own, the trial ends: save a key to keep going.
If you get the setup instead of a trial reply, the bot's message starts with the reason:
Your free trial is used up.
The free trial is for members who haven't chatted with me before.
This Discord account is too new for the free trial.
Today's free trials are taken; try again after 00:00 UTC.
The free trial is paused for today; it starts again at 00:00 UTC.
The last one means the trial has reached its limit for the day, for everyone. Wait until 00:00 UTC, or save a key of your own.
The free trial is paused while the operator fixes it. You can add your own key with /start.
The trial's own key has stopped working, and the trial stays paused until the operator fixes it. Save a key of your own to keep going.
What do you keep about me, and how do I delete it?
Privacy and memory lists what the bot keeps, for how long, and what it sends to your provider. To delete what it holds about you, run /umbris delete-all-my-data: it asks before it deletes anything, and Delete my data says what is removed and what is kept.
Which commands are there?
/umbris help lists the commands you can use where you type it. If the bot's commands show under another name than /umbris when you type a slash, use that name instead.
/start: the setup, or which provider and model answer you./keys: your keys by name, with the date each was saved./settings: your provider, model, backups, keys and image model. It changes nothing./setkey: in a DM with the bot, save a sealed key./revokekey: remove one or all of your stored keys./umbris provider: change the provider that answers you./umbris model: change the model on that provider./umbris fallback: choose backups if your first choice fails./umbris stop: stop your queued and running work./umbris delete-all-my-data: delete the data the bot holds about you.
On the terminal, the provider and keys pane shows your keys, adds or removes them, and changes your first choice, model and backups.