Get started

The Umbris bot answers on the community's Discord. Each reply runs on an API key of your own, which you get from a provider such as OpenRouter and save with the bot once. Until you do, the bot answers with the setup instead, unless the operator is running a free trial.

Talk to the bot

The bot answers only messages addressed to it. To address it in a channel:

1. Join the Discord with the button at the top of this page.
2. In a channel of the server, type @ and pick the bot from the list.
3. Write your message after its name, and send it.

Two other kinds of message also address it:

• A Discord reply to one of its messages.
• A direct message, if the operator has turned DMs on. They are off unless turned on, and a DM is answered only while you are a member of a server the bot serves. Group DMs are never answered.

Every other message is left alone, with no reply. @everyone and @here do not address the bot, and neither does a mention of a role, even one with the bot's name. /start and /setkey work in a DM with the bot even when DMs are off for chat, and so do the commands that show or delete your own data, such as /keys, /settings and /umbris delete-all-my-data.

Your first message

Until you save a key, the bot answers your message with a short line in the channel and sends you the setup in a DM:

You have no key for OpenRouter. Check your DMs, I've sent you the setup.

OpenRouter is an example: the line names the provider your replies would use. If the bot cannot send you a DM, the line says so:

You have no key for OpenRouter. I couldn't DM you. Open your DMs for this server, or use /start.

/start shows the setup at any time. If the bot sent you the setup recently, the line says so and points to /start instead of sending it again. If you wrote to the bot in a DM, the setup is the reply itself.

The setup comes in one of two forms. If it carries the buttons Connect OpenRouter and Add a key for another provider, each opens the terminal at a step below: Connect OpenRouter on the terminal or Save a key for another provider. Without the buttons, it explains the seal page and /setkey, as in On Discord.

If you already hold a key, but not for the provider your replies use, you get a switch line instead, for example:

You're on OpenRouter, but your key is for Mistral. Switch your first choice to Mistral with /umbris provider -> Mistral.

To follow it, run /umbris provider and pick Mistral under use. The FAQ has the other forms of this line.

Commands that start with /umbris use the bot's default group name. If its commands show under another name when you type a slash, use that name instead.

The free trial, if it is on

The operator can run a free trial, paid for with a key of their own. It is off unless the operator turns it on, so it may not be running when you read this. While it is on, a member with no key saved gets trial replies in a server instead of the setup; in a DM the bot answers with the setup.

To start a trial, you must not have chatted with the bot before, and your Discord account must be old enough, for example at least 30 days old: the operator sets the minimum age. The number of new trials a day is capped too.

A trial reply uses one provider and model, chosen by the operator, without memory, search or image tools. It ends with the turns you have left, for example:

Trial: 9 of 10 left.

The numbers are examples: the operator sets the allowance.

• The trial pauses for everyone when it reaches its limit for the day, and starts again at 00:00 UTC.
• A reply that ends in an error can still use up a turn. One the provider turned down at the start, because of a rate limit, the key or payment, does not.
• Your last trial reply ends "Add your own key to keep going: /start." After that, the bot answers you with the setup.
• Saving a key of your own ends the trial. A key for a provider this bot offers answers from then on.
• There is one trial per Discord account. Deleting your data with the bot does not give you another.

The trial's other messages are in the FAQ.

Get an API key

The bot supports eight providers and holds up to 3 keys per provider for you. The operator chooses which of them this bot offers: the terminal's Provider for the new key list shows those. Each line below gives the website where you make a key, then how its keys start:

• OpenRouter: openrouter.ai, sk-or-
• Anthropic: console.anthropic.com, sk-ant-
• OpenAI: platform.openai.com, sk-proj- or sk-svcacct- (a plain sk- names no single provider, so the bot asks which one)
• Google Gemini: aistudio.google.com, AIza
• xAI: console.x.ai, xai-
• Mistral: console.mistral.ai (no fixed start)
• DeepSeek: platform.deepseek.com (no fixed start)
• Groq: console.groq.com, gsk_

In its setup with buttons, the bot names two free starts:

No key yet? Google Gemini gives free API keys without a card (its free tier lets Google review your messages). OpenRouter's free models work on a new account.

These are the bot's own words about other services, which can change their terms. Check them on the provider's website before you rely on them.

Connect OpenRouter on the terminal

The terminal is the bot's own web page for members, linked as Terminal in this site's menu. If this bot has it set up, the terminal can get a key from OpenRouter for you and store it, with nothing to copy. The terminal is open to members of a server the bot serves, so join the Discord first.

1. Open the terminal.
2. If you are not signed in, press Sign in with Discord.
3. If Discord asks, approve the sign-in.
4. Find the provider and keys pane.
5. Press Connect OpenRouter.
6. If OpenRouter's page does not open by itself, press Continue to OpenRouter.
7. Sign in on OpenRouter and approve the connection.
8. Back on the terminal, check for this line:

OpenRouter is connected. Your key is stored.

While it connects, and after some failed attempts, the terminal shows this hint:

On a phone, if OpenRouter's page does not come back here, open this page in your browser and connect from there.

• No Connect OpenRouter button means Connect is not set up on this bot. Make a key on openrouter.ai and save it as in Save a key for another provider.
• If you already have an OpenRouter key stored, the terminal asks before it replaces it.
• If connecting fails, the terminal says why. Press Connect OpenRouter to try again.

Save a key for another provider

Any other key is sealed before you save it. The seal page encrypts the key in your browser, with your Discord id sealed in, and gives you a block of text, the sealed blob. You save the blob, so the key itself never passes through Discord or the terminal. This also works for an OpenRouter key you already have.

On the terminal

1. Open the terminal and sign in, as above.
2. In the provider and keys pane, press Add a key for another provider.
3. Under Provider for the new key, pick the provider.
4. If you have no key yet, press Get a key: it opens the provider's page for making one.
5. Press Seal your key. The seal page opens with your Discord id filled in.
6. Paste your key under Your API key.
7. Check that Your Discord user id is your own.
8. Press Seal my key.
9. Press Copy blob.
10. Back on the terminal, paste the blob under Sealed output.
11. Press Save.

The terminal confirms with a line that starts:

Mistral key saved.

If the list offers Recognise from the key, you can keep it instead of picking, when your key's start names its provider. If there is no Seal your key link, open this site's seal page and type your Discord id yourself.

On Discord

/setkey works only in a DM with the bot, and it works there even when DMs are off for chat. Where the terminal shows a Seal a key link, it opens the seal page with your Discord id filled in.

In the provider list of /setkey, pick a provider this bot offers; the terminal's Provider for the new key list shows them.

1. Open the seal page.
2. Paste your key under Your API key.
3. Enter your id under Your Discord user id, unless it is filled in. The page says where Discord shows it.
4. Press Seal my key.
5. Press Copy blob.
6. Open a DM with the bot.
7. Type /setkey and pick the command.
8. Paste the blob into blob.
9. Pick your provider under provider. You can leave it out if your key starts with sk-or-, sk-ant-, sk-proj-, sk-svcacct-, AIza, xai- or gsk_.
10. Send the command.

The bot replies privately, for example:

Your Mistral key is stored. /keys lists yours.

Either way:

• A sealed blob works once. To save the same key again, seal it again.
• You can hold up to 3 keys per provider. A key saved for a provider you already hold is added beside the others and named after the provider and its number, such as OpenRouter 2. To give it a short name of your own, fill in name on Discord or Name (optional) on the terminal.
• To swap a key for a new one, fill in replace on Discord and pick the key it replaces. The terminal shows Replace beside each key for a provider it can add. With 3 keys held for a provider, replace or remove one before adding another.
• If the bot says the key looks like it is for another provider, the blob still works: save it again with that provider.
• If you paste the key itself into Discord instead of the blob, treat the key as exposed and replace it at the provider.

To check a copy of the seal page you saved, compare it with the Security page.

After you save a key

Saving a sealed key can change which provider answers you. If you had not chosen a provider, or your first choice has no key, the saved provider becomes your first choice, if this bot offers it. The reply to /setkey then ends with a sentence that starts "Your replies now use", with the provider and model. After Connect OpenRouter, /start shows which provider your replies use.

The reply can also offer a backup, with Yes and No buttons, for example:

Use Mistral as a backup if OpenRouter fails?

On Discord the offer lasts 5 minutes. When your first choice turns a request down, for example under a rate limit, the bot moves on to your backups: see A reply failed.

To see where you stand:

• /keys lists your keys by name, with the date each was saved. It never shows a key.
• /settings shows your provider, model, backups, keys and image model, and changes nothing.
• /start says which provider and model your replies use, or which provider to switch to.

To change them:

• /umbris provider changes the provider that answers you. Unless you also pick a model, a new provider starts at its default model.
• /umbris model changes the model on that provider.
• On the terminal, the provider and keys pane has First choice, Model and Backups if it fails, then Save.
• /umbris help lists the commands you can use.

What the bot does with your key, and how to remove it, is on the next page: Your API key.