Skip to content

Bots and models ​

A bot is an AI teammate with its own instructions, model, memory, skills, routines and computer. Create one bot for each kind of job you hand out, such as an inbox assistant, a researcher or a coder, and give each the model and limits that fit the work.

What a bot has ​

PartWhat it is
Name and iconA cloud mascot or initials, shown in the sidebar and on every reply.
InstructionsStanding instructions (its system prompt): its role, how it works, its style and limits.
ModelA model key from your workspace plus a model id. A bot can also have fallback models and a cheaper model for internal steps. On Casama Cloud, Casama chooses the model and you don't need a key.
AutonomyHow often it asks before acting. See Autonomy and approvals.
BudgetA cost cap per run and per day. See Budgets and run limits.
ComputerWhere it runs commands, browses and keeps files. See Computers.
Memory, skills, routinesWhat it remembers, the instructions it can load, and work it does on its own later.

Create a bot ​

On Casama Cloud, bots run on Casama's own models, so there's nothing to set up first. On a self-hosted server you need a model key; if your workspace has none, the New bot sheet shows the add-key form in place.

  1. In the sidebar, select Add (the + button), then New bot.
  2. Under Persona, tap one of the quick picks, or Browse all to see every persona (see Personas and starter bots). Leave it on Blank to start from scratch. The card under the picks shows the persona and holds its Instructions; edit them as you like.
  3. Under Name and icon, enter a Bot name and pick a cloud mascot or Initials. If you leave the name empty, the bot is named Chief.
  4. Self-hosted only: the model key and model Casama picked for you are under Advanced. Change them there if you like.
  5. Select Create. The bot's chat opens, ready for your first message.

New bots start with Ask for risky actions autonomy (unless a persona sets another level), are visible to everyone in the workspace, and get a budget of $1 per run and $10 per day.

From the CLI, casama bot create takes the same choices plus a few the app doesn't show:

sh
casama credential list
casama bot create "Ada" --credential <key-id> \
  --fallback anthropic/claude-sonnet-5.5 \
  --cheap-model google/gemini-3.8-flash \
  --run-budget 2 --daily-budget 20 --private

Leave out --model to use the server's default model for the key's provider. See CLI for every flag.

Add a model key ​

On a self-hosted server, bots think with your own model provider keys. Keys belong to one workspace, are stored encrypted, and are never shown again after you save them.

On Casama Cloud this screen is called Service keys instead. It takes only your own keys for search, maps and paid data (Brave Search, Tavily, Google Maps, Mapbox and Treg); models, voice and images run on Casama's keys and are paid from your credits.

  1. Go to Settings → Model keys.
  2. Under Add Key, pick a Provider, give the key a Label and paste the API key. For your own server, also enter its Base URL, for example http://localhost:11434/v1.
  3. Select Add Key.
  4. To check it, open the key's More menu and choose Test Key. Casama makes a one-token call and shows Key works with the model and the time it took.

Each key shows Working, Failing or Not tested. Remove deletes a key; bots that use it stop working until you give them another key.

These providers can run a bot:

ProviderNotes
OpenRouterRecommended. One key reaches models from many providers.
OpenAIIts first OpenAI key also gives the workspace embeddings for memory and knowledge search.
Anthropic
Google Gemini
xAI
OpenAI-compatible serverOllama, LM Studio, vLLM or any server with an OpenAI-style API. Needs a Base URL. Its calls are recorded in Usage at $0.
ChatGPTYour ChatGPT plan, connected by signing in instead of a key. See below.

The same screen also takes keys that give bots other abilities but can't run a bot: Brave Search and Tavily (web search), Treg (paid data), and Google Maps and Mapbox (travel times). Images run on an OpenRouter key, and so do video, read aloud and dictation. A Google AI key is only for live calls.

From the CLI: casama credential add --provider openrouter --label Default.

Connect a ChatGPT plan ​

With an eligible ChatGPT plan you can run your bots on the plan instead of an API key. Their model calls count toward your plan's limits, and only you can use it.

  1. Open the desktop app (macOS, Windows or Linux).
  2. Go to Settings → Model keys and select Continue with ChatGPT.
  3. Sign in to ChatGPT in your browser and allow plan usage. The key appears as ChatGPT plan.

From the CLI, run casama credential chatgpt instead. Phones and the web app can't start the sign-in, because OpenAI only returns to an address on the same computer; they point you to the desktop app or the CLI.

How a ChatGPT plan works in Casama:

  • Only you can use it. A run uses your plan only when it acts for you: a message you sent, a routine you created, or work started from one of those. In anyone else's runs the bot moves on to its next model, or the run fails with a message saying the plan isn't theirs.
  • Plan limits. When you reach your plan's limit, the run stops. To continue on the bot's next model instead (which may cost money), turn on Use the bot's next model at my plan limit in the key's menu. The chat shows "Switched to the next model" when that happens.
  • Cost. Plan usage is recorded in Usage at $0.
  • Status. The key shows Connected, Plan usage off (you signed in but didn't allow plan usage) or Sign in again (the sign-in stopped working; use Reconnect from the desktop app).
  • Manage usage opens your ChatGPT settings. Remove revokes the sign-in too.
  • The plan doesn't provide embeddings. Without an OpenAI API key (or an OpenAI-compatible key with an embedding model set through the API), memory and knowledge search use full-text matching only, unless the server has a shared OpenRouter key.

Self-hosted servers offer ChatGPT sign-in by default; servers with billing turned on don't. The server's admin controls this with CHATGPT_SIGN_IN (see Configuration).

Choose a model ​

On a self-hosted server, the Model field opens Choose a model, a searchable list of the models the selected key can use. Casama Cloud shows no model fields.

  • Recommended models come first, then All models.
  • The list comes live from the provider: OpenRouter's catalog; the OpenAI, xAI, Anthropic and Google model lists; or <base URL>/models on an OpenAI-compatible server. Embedding, image, audio and batch models are left out. Lists are cached for 10 minutes.
  • If the provider can't be reached, you see "Showing suggested models" with the reason.
  • You can always type any model id and pick Use "…".

To change a bot's model later, open its profile and change Model key or Model, then select Save Changes.

The default model ​

Wherever Casama suggests a model, it uses:

KeyDefault modelModel id
OpenRouterDeepSeek V4.1 Flash 1017deepseek/deepseek-v4.1-flash-1017
OpenAIGPT-6 Lunagpt-6-luna

Other providers have no default, so you pick a model. Casama never replaces a model you chose. A server admin can change the suggestions with DEFAULT_MODEL_OPENROUTER and DEFAULT_MODEL_OPENAI.

These built-in defaults run at medium reasoning effort unless the bot sets another. Through the API, each model choice takes an optional reasoning_effort: none, low, medium, high, xhigh or max.

Fallback and cheap models ​

Each bot has a primary model, up to five fallback models in order, and an optional cheap model.

  • Fallbacks take over when a model call fails with an error worth retrying (rate limits, provider errors, or no answer within 60 seconds) before any reply has started.
  • The cheap model handles internal steps: memory extraction, conversation summaries and titles. Without one, Casama uses the same provider's small model, with the primary model as its fallback: DeepSeek V4.1 Flash 1017 on OpenRouter, GPT-6 Luna on OpenAI, Claude Haiku 5.5 on Anthropic and Gemini 3.5 Flash-Lite on Google. Other providers use the primary model.

Set fallbacks and the cheap model with casama bot create or the API (model_policy).

Personas and starter bots ​

A persona fills in a bot's name, mascot and instructions in one tap. You can edit all of it before and after creating the bot. Some personas also bring skills or routines.

  1. In the New bot sheet, tap a quick pick under Persona, or Browse all.
  2. In Choose a persona, search or browse by group, and select Preview to read a persona's Instructions and what to Try asking.
  3. Select Use ….

To swap the instructions of an existing bot, open its profile and select Load a Persona. Only the instructions change; skills and routines stay as they are.

GroupPersonas
WorkAssistant, Briefing (morning briefing routine), Support, Sales, Product, Ops (hourly health check routine), Inbox triage (weekday morning inbox routine), Outbound prospector, Recruiting screener, Coordinator
ResearchResearcher (research-report skill), Analyst, Tutor
BuildCoder (code-change skill), QA, Designer, Bug triage
CreateWriter, Marketer, Social (weekly content plan routine), Translator
LifeTravel, Budget, Coach, Chef, Expense matcher

The Coordinator plans bigger jobs, splits them into tickets and hands them to other bots. See Bots working together.

More personas come from the open gallery, such as Study buddy and Home organizer, and show By whoever made them. New ones appear without an app update. Anyone can propose one by pull request to stackwares/casama-gallery; a gallery persona asks before acting, at least before risky actions.

Your first bot ​

When you sign in for the first time and don't belong to a workspace yet, Casama first asks What should bots call you? Then it creates a workspace named after you ("<your name>'s space") and a private bot named Casama, and opens its chat. People who join by invite skip this. To create or join a workspace and add a key step by step instead, choose Set Up Manually while the space is being made.

The chat opens empty, the same way a new bot's does: "Say hello to Casama.", tiles to Connect your apps, and a few starter requests you can tap. This chat is your bot's General conversation, where its briefs and suggestions land too.

  • On Casama Cloud the bot already has a model. On a self-hosted server it uses the first key that has a default model. With no key yet, add one in Settings → Model keys first; otherwise your first message fails with an Add a model key button.
  • The first bot starts with check-ins turned on, so it can reach out when something needs you.
  • Run the setup interview whenever you like to have the bot propose its own instructions, routines and connections.

The setup interview ​

The setup interview is a few quick questions, after which the bot proposes its own instructions, routines and the accounts to connect. A new bot opens straight into an empty chat, so you can just start typing; run the interview whenever you like.

  1. Open the bot's profile and select Run Setup Again (under Advanced).
  2. Answer three to six questions on interactive cards: the work, how you like things written, the tools and accounts it should use, and any schedule.
  3. Review the proposal on its approval card: new instructions, up to five memories, up to five routines (scheduled in your timezone) and the connections to add.
  4. Approve it. The bot can't sign in to accounts for you, so it tells you which ones to connect.

You can run it as often as you like. Bots created by other bots start with setup pending too.

Tip

The proposal is high risk, so it waits for you under Ask before acting and Ask for risky actions. A bot set to Act on its own applies it without asking.

Bot profile ​

Open a bot's chat and tap its name, or select More (the … button), then Bot profile. Change the name, icon, instructions, model (self-hosted only) or autonomy, then select Save Changes.

Tiles at the top open the bot's Computer, Memory, Routines, Apps (which workspace integrations it may use) and Library (everything it made; see Library). Below them:

RowWhat it does
FolderGroups bots in the sidebar.
SharingWho can chat with, edit or manage it. See Templates, sharing and import.
ComputerWhich computer the bot uses. Automatic means its private computer if it has one, otherwise the team computer.
VoiceIts read-aloud voice and the tools it has on calls. See Voice and calls.
KnowledgeDocuments it can search and cite. See Memory and knowledge.
Check-Ins, Notifications from this botIts morning brief and suggestions, and its quiet hours.

Under Advanced:

RowWhat it does
Action rules, WatchersWhat it may do without asking, and what it keeps an eye on.
PluginsSkills and tools from plugin packages. See Plugins.
Chat apps, Linked bots, Publish as an A2A AgentOutside chat apps, trusted contacts' bots and outside agents.
Share as TemplateA file or link with its instructions, skills and routines.
ActivityEvery run, step by step.
ReplaysRecorded steps it runs without thinking. See Teach by showing.
Settings historyEvery change to its settings and who made it, with Restore These Settings.
Run Setup AgainStarts a new setup interview.

At the bottom:

RowWhat it does
Delete All ChatsDeletes every chat with the bot that you may delete. Group chats and chats it's working in stay, and so do its memories, usage records and what it made. See Delete a chat.
Archive BotRemoves it from the sidebar and stops it running. Its chats and history are kept; bring it back from Add → Archived bots.

Budgets and run limits ​

Every run is checked against its limits when it starts and again before every model step. A run that hits a limit stops, fails with a clear message, and keeps everything it did so far.

LimitDefaultError code
Cost of one run$1budget_exceeded
A bot's cost per day (UTC)$10daily_budget_exceeded
Workspace monthly cost quotaNonequota_exceeded
Model steps in one run40max_steps_exceeded
Time for one run30 minuteswall_time_exceeded
No model setno_model_configured

On hosted plans, a run can also stop with out_of_credits or computer_hours_exceeded. See Usage, budgets and plans for quotas and spend.

When a chat run runs out of steps or time, the bot doesn't go quiet: it replies once more, without tools, with what it got done, what blocked it and what it suggests.

Time spent waiting for you (an approval, a secret or a takeover) doesn't count toward the 30 minutes. Because the check runs between steps, one step can take a run slightly past its cap. A bot's cost today shows on its card in the bot list.

How bots load tools ​

A bot with many integrations can have hundreds of tools. Sending every definition on every call costs tokens, so when a bot has more than 30 tools available, it starts with its core tools (memory, skills, tasks, notifications, cards and setup) plus a one-line index of the other tool groups. It loads a group when it needs it, and keeps it for the rest of the run.

You may see this as a step in the chat. Nothing else changes: the bot can still use any tool it's allowed. Server admins can change the threshold with LAZY_TOOLS_THRESHOLD (0 turns it off).

Bots that change their own setup ​

Ask a bot for a new ability and it can often set it up itself. Anything that lets it reach more always shows you an approval card first, whatever its autonomy or rules. Anything that only makes it more careful or quieter happens straight away.

A bot canHow it asks
Add an MCP server for itself: a remote one by its https address, or one it runs on its own computer with a command such as npx -y some-mcp-serverAlways asks
Start using one of the workspace's connections, optionally only some of its toolsAlways asks
Suggest a pluginShows a card that opens the plugin's install screen, where you review it and enter any keys
Suggest a new look for the app (a theme, colors, fonts, light or dark)Shows a card. Apply changes the look on that device only, with Undo
Add an action rule for itselfAsk me first and Hand it to me apply at once. Go ahead rules always ask, and it can never allow payments or sign-ins
Add a website or GitHub repository to its knowledgeLike any other medium-risk action
Stop notifying you, or set its own quiet hoursQuieter applies at once. Going back to your usual hours asks
Remove a server it added, stop using a connection, remove its own knowledgeNever asks

A key for a server goes in as {{secret:NAME}} from Settings → Advanced → Secrets. If the secret doesn't exist yet, the bot asks you for it in the chat first, and it must be allowed for the server's host. New tools arrive from the bot's next message.

Bots can't change billing, members, encryption keys, secrets, sharing, or their own autonomy or budget.

Limits ​

  • A bot keeps its own copy of a key it gives a server. If you change the secret later, remove the server and let the bot add it again.
  • A server a bot runs on its computer takes plain settings only, not secrets. For one that needs a key, use a plugin.
  • The app has no fields for budgets, fallback models, the cheap model or reasoning effort. Set them with casama bot create when you create the bot, or through the API. A bot can also change another bot's budget with its bots.update tool, but never above its own.
  • ChatGPT sign-in works only from the desktop app or the CLI. Hosted Casama needs OpenAI's approval before it can offer it.