# Agent-to-agent (A2A) [A2A](https://a2a-protocol.org) is an open protocol for AI agents to hand each other tasks. Casama speaks it both ways: - **Publish a bot** so outside agents (another company's assistant, your own agent framework, a script) can give it tasks. - **Call outside agents** from a bot, as a tool it uses like any other. Casama implements A2A version 1.0 over its JSON-RPC binding: agent cards at `/.well-known/agent-card.json`, the methods `SendMessage`, `GetTask`, `CancelTask` and `ListTasks`, and text messages. Streaming and push notifications aren't offered yet; the agent card says so. ## Publish a bot Publishing is off until you turn it on, in two steps: 1. **Turn on A2A for the workspace.** An owner or admin turns on **Agent-to-agent (A2A)** in workspace settings, or sets `a2a_enabled` with `PATCH /v1/orgs/{id}/settings`. Turning it off later unpublishes every bot. 2. **Publish the bot.** Someone who manages the bot turns on **Publish as an A2A agent** in its settings, or calls the API: ```sh curl -s -X PUT "https://casama.example.com/v1/bots/$BOT/a2a" \ -H "authorization: Bearer $TOKEN" \ -H "content-type: application/json" \ -d '{"published": true}' ``` ```json { "workspace_enabled": true, "published": true, "agent_card_url": "https://casama.example.com/a2a/5d0c1e6a-8b7f-4e8a-a1d2-3c4b5a6f7e80/.well-known/agent-card.json" } ``` Publishing while the workspace switch is off answers 409 `a2a_off`. `GET /v1/bots/{id}/a2a` reads the same status. Publishing and unpublishing are recorded in the audit log. ### Create a workspace API key Callers authenticate with a **workspace API key**, the same `ksk_...` keys the [hosted MCP endpoint](/guide/mcp) uses. An owner or admin creates one in workspace settings under **Connect AI apps**, or with the API: ```sh curl -s -X POST "https://casama.example.com/v1/orgs/$ORG/mcp-keys" \ -H "authorization: Bearer $TOKEN" \ -H "content-type: application/json" \ -d '{"name": "Partner agent"}' ``` The response's `key` is shown only once. Revoke a key with `DELETE /v1/orgs/{id}/mcp-keys/{key_id}`. A key **acts as the person who created it**, in that workspace only. So a task sent with it runs like a message from that person: with the bot's usual approvals, budgets and action rules, recorded in the audit log, and only on bots that person can use. A key stops working when its person leaves the workspace. ::: tip Create keys from an account whose access fits what the caller should reach, and give each caller its own key so you can revoke one without breaking the others. ::: ### The agent card A published bot's card is public (it holds nothing secret), so any A2A client can discover it: ```sh curl -s "https://casama.example.com/a2a/$BOT/.well-known/agent-card.json" ``` ```json { "name": "Invoicer", "description": "You chase unpaid invoices for a small design studio. Be polite and brief...", "version": "1.0.0", "supportedInterfaces": [ { "url": "https://casama.example.com/a2a/5d0c1e6a-8b7f-4e8a-a1d2-3c4b5a6f7e80", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" } ], "capabilities": { "streaming": false, "pushNotifications": false }, "defaultInputModes": ["text/plain"], "defaultOutputModes": ["text/plain"], "skills": [ { "id": "chat", "name": "Ask the bot", "description": "Give Invoicer a task in plain language; it works with its own tools and returns the result.", "tags": ["assistant"] } ], "securitySchemes": { "workspaceKey": { "httpAuthSecurityScheme": { "scheme": "Bearer", "bearerFormat": "Casama workspace API key" } } }, "securityRequirements": [{ "workspaceKey": [] }] } ``` The description is the start of the bot's instructions (up to 500 characters), so write the first lines of its instructions with outside readers in mind. A bot that isn't published answers 404. ## Send a bot a task Every call is a JSON-RPC 2.0 `POST` to `/a2a/{bot id}` with the key as a bearer token. The `A2A-Version` header is optional; if you send it, it must be `1` or `1.x`. ### SendMessage ```sh curl -s -X POST "https://casama.example.com/a2a/$BOT" \ -H "authorization: Bearer $CASAMA_KEY" \ -H "content-type: application/json" \ -H "a2a-version: 1.0" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "SendMessage", "params": { "message": { "role": "ROLE_USER", "messageId": "3e9b6c1a-0f2d-4a8b-9c7e-5d4f3a2b1c0d", "parts": [{ "text": "Which invoices from October are still unpaid?" }] } } }' ``` ```json { "jsonrpc": "2.0", "id": 1, "result": { "task": { "id": "b7a1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d", "contextId": "f0e1d2c3-b4a5-4968-8776-655443322110", "status": { "state": "TASK_STATE_COMPLETED", "timestamp": "2026-11-11T21:04:05.000Z", "message": { "role": "ROLE_AGENT", "parts": [{ "text": "Three are unpaid: #1031, #1036 and #1040..." }], "messageId": "...", "contextId": "f0e1d2c3-b4a5-4968-8776-655443322110", "taskId": "b7a1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d" } }, "artifacts": [ { "artifactId": "b7a1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d-answer", "name": "answer", "parts": [{ "text": "Three are unpaid: #1031, #1036 and #1040..." }] } ] } } } ``` - The message needs `role: "ROLE_USER"` and at least one part with `text`. Text parts are joined; other kinds of parts are ignored. - The task becomes a run in a conversation with the bot, created by the key's person, so it shows up in the app like any other chat. - **Blocking by default.** The call waits up to 55 seconds for the bot to finish or to need an approval. If it's still working, you get the task in its current state; poll `GetTask`. Pass `"configuration": {"returnImmediately": true}` in `params` to get the task back at once. - **Follow-ups.** Send the `contextId` from a task (it must be a UUID) in your next message to continue the same conversation, so the bot remembers what you discussed. Or send a `taskId` to continue that task's conversation. ### GetTask ```sh curl -s -X POST "https://casama.example.com/a2a/$BOT" \ -H "authorization: Bearer $CASAMA_KEY" -H "content-type: application/json" \ -d '{"jsonrpc": "2.0", "id": 2, "method": "GetTask", "params": {"id": "b7a1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d"}}' ``` The result is the task. The answer arrives as an artifact named `answer` and as the final status message, once the state is `TASK_STATE_COMPLETED`. | Casama run status | Task state | | --- | --- | | Queued | `TASK_STATE_SUBMITTED` | | Running, waiting for approval, waiting for a person to take over | `TASK_STATE_WORKING` | | Completed | `TASK_STATE_COMPLETED` | | Failed | `TASK_STATE_FAILED` | | Cancelled | `TASK_STATE_CANCELED` | While the bot waits for its owner to approve a step, the state stays `TASK_STATE_WORKING` with the status message "Waiting for the bot's owner to approve a step." Approvals happen in Casama, not over A2A. ### CancelTask ```sh curl -s -X POST "https://casama.example.com/a2a/$BOT" \ -H "authorization: Bearer $CASAMA_KEY" -H "content-type: application/json" \ -d '{"jsonrpc": "2.0", "id": 3, "method": "CancelTask", "params": {"id": "b7a1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d"}}' ``` Cancels the run and returns the task as `TASK_STATE_CANCELED`. A task that already finished answers the error `-32002`. ### ListTasks ```sh curl -s -X POST "https://casama.example.com/a2a/$BOT" \ -H "authorization: Bearer $CASAMA_KEY" -H "content-type: application/json" \ -d '{"jsonrpc": "2.0", "id": 4, "method": "ListTasks", "params": {"contextId": "f0e1d2c3-b4a5-4968-8776-655443322110", "pageSize": 20}}' ``` Returns `{"tasks": [...], "nextPageToken": ""}`: the tasks your key's person sent to this bot, newest first, optionally only those in one `contextId`. `pageSize` is 1 to 100 (default 50). There are no further pages. ### Errors Errors come back as JSON-RPC errors: | Code | HTTP status | Meaning | | --- | --- | --- | | `-32600` | 404 | No published bot with that id | | `-32600` | 401 | Missing, revoked or wrong key, or a key from another workspace | | `-32600` | 403 | The key's person can't use this bot | | `-32600` | 200 | Not a valid JSON-RPC request | | `-32700` | 200 | The body isn't JSON | | `-32601` | 200 | Unknown method | | `-32602` | 200 | Bad parameters, such as a message without `ROLE_USER` or text | | `-32001` | 200 | Task not found (or not yours) | | `-32002` | 200 | The task already finished and can't be cancelled | | `-32009` | 200 | Unsupported `A2A-Version` | | `-32603` | 200 | Something failed on the server | ## Call outside agents from a bot Any agent that publishes an A2A 1.0 agent card with a JSON-RPC interface can become a tool for your bots, including bots on another Casama server. **In the app:** add a connection of the kind **AI agent (A2A)**, enter the agent's address or the URL of its agent card, and its access token if it needs one. Then attach the connection to the bots that should use it. **With the API:** create an integration with `kind: "a2a"`, then attach it to a bot: ```sh curl -s -X POST "https://casama.example.com/v1/integrations" \ -H "authorization: Bearer $TOKEN" \ -H "content-type: application/json" \ -d '{ "org_id": "'"$ORG"'", "kind": "a2a", "name": "travel_agent", "config": { "url": "https://agents.example.com/travel" }, "secret": "the-agent-access-token" }' curl -s -X POST "https://casama.example.com/v1/bots/$BOT/integrations" \ -H "authorization: Bearer $TOKEN" \ -H "content-type: application/json" \ -d '{"integration_id": ""}' ``` | Field | Meaning | | --- | --- | | `name` | Lowercase letters, digits and `_`, starting with a letter, up to 40 characters | | `config.url` | The agent's address (Casama adds `/.well-known/agent-card.json`) or the full URL of its agent card (ending in `.json`) | | `secret` | Optional. Sent as `Authorization: Bearer `. Stored in the vault, never returned. | Only owners and admins add integrations. Casama reads the agent card right away to check the connection. ### What the bot gets One tool, `a2a..send`, described from the agent card's description and skills, with these inputs: | Input | Meaning | | --- | --- | | `task` | What to do, with everything the agent needs (required) | | `context_id` | Continue an earlier conversation with this agent | | `task_id` | Answer a task that asked for more input | The tool sends the task, then checks on it every 1.5 seconds until it finishes, needs input, or 10 minutes pass. It returns the agent's answer (its artifacts, or its last status message) and the `context_id` for follow-ups, and says when the agent needs more input, failed or declined. The tool is **medium risk**, so with the default autonomy the bot may ask before using it, for example after it has read untrusted content. You can change its risk like any connection's tool. See [Autonomy and approvals](/guide/autonomy). ### Connect two Casama servers To let a bot on one server use a bot on another: 1. On the other server, publish the bot and create a workspace API key. 2. On yours, add an A2A connection with the published bot's address (`https://other.example.com/a2a/`) and the key as its access token. For two people who trust each other, [linked bots](/guide/bots-together#linked-bots) are simpler: each side invites or accepts in the app, no publishing or keys needed. A link also speaks A2A under the hood, with its own per-link token instead of a workspace API key, so a linked bot answers on the same `/a2a/{bot id}` address whether or not it's published. ## Limits | What | Limit | | --- | --- | | `SendMessage` wait | 55 seconds, then poll `GetTask` | | `ListTasks` page size | 100 (default 50) | | Card description | 500 characters | | Outside agent tool wait | 10 minutes | | Tool description from a card | 1,024 characters | | Message parts | Text only, in and out | ## Related - [Hosted MCP](/guide/mcp): the other way to use bots from outside, with the same keys - [Connections](/guide/connections): add and attach connections - [Autonomy and approvals](/guide/autonomy) - [Bots working together](/guide/bots-together) - [HTTP API](/develop/api) # Build with AI agents If you build on Casama with a coding agent such as Claude Code, Codex or Cursor, give it these and it can answer from the real docs and API instead of guessing. Every option is free and needs no Casama account. | What | Gives your agent | Set up | | --- | --- | --- | | [Agent kit](#the-agent-kit) | Skills for plugins, the API, A2A, bot templates, the gallery and the Casama repo, plus the docs server | One command in Claude Code | | [Docs server (MCP)](#the-docs-server) | Search the docs, read any page, look up any API operation | One URL | | [Docs as markdown](#docs-as-markdown) | `llms.txt`, a markdown copy of every page, the OpenAPI document | Nothing | | [The gallery](#check-the-gallery-first) | Ready-made skills, apps, routines, bots, plugins and looks to reuse before building | `gallery_search`, or plain JSON | | [Starter projects](#starter-projects) | A plugin, skill, bot or routine to start from, with an `AGENTS.md` | `casama init` | | [Plugin checker](#check-a-plugin) | The same checks Casama runs at install | `npx @casama/plugin-check` | | [TypeScript client](/develop/typescript) | Typed calls for every API route | `npm i @casama/client` | ## The agent kit The agent kit is a set of skills, one per job, plus the docs server. A skill holds the exact formats, limits and steps for its job, and the agent loads it only when the task calls for it. | Skill | For | | --- | --- | | `casama-overview` | What Casama is, its concepts, where the docs are, and which skill to load next | | `casama-plugin` | Write, check and publish a [plugin](/develop/plugins) | | `casama-api` | Call the [HTTP API](/develop/api): sign in, chat with a bot, follow runs, approvals, [webhooks](/develop/webhooks), SDKs and the CLI | | `casama-a2a` | Publish a bot over [A2A](/develop/a2a), or call an outside agent | | `casama-bot-template` | [Bot templates](/develop/bot-templates), and [routines and skills as files](/develop/workspace-files) | | `casama-gallery` | Add apps, skills, starter bots, routine ideas, plugins and themes to the [gallery](https://gallery.casama.ai) | | `casama-contribute` | Change Casama itself. See also [Contribute to Casama](/develop/contributing). | **Claude Code:** ```text /plugin marketplace add stackwares/casama /plugin install casama-dev@casama ``` **Codex, Cursor and other tools:** copy the folders in [`agent-kit/skills`](https://github.com/stackwares/casama/tree/main/agent-kit/skills) to where your tool reads skills (for Codex, `~/.codex/skills`), and add the docs server below. **A Casama bot:** the kit is also a Casama plugin. In a bot's settings, under **Plugins**, paste `https://github.com/stackwares/casama/tree/main/agent-kit`. ## The docs server `https://api.casama.ai/mcp/docs` is an MCP server (Streamable HTTP) with the docs tools. It needs no sign-in and can't see any account. ```sh claude mcp add --transport http casama-docs https://api.casama.ai/mcp/docs ``` Cursor (`~/.cursor/mcp.json`) and other tools that take JSON: ```json { "mcpServers": { "casama-docs": { "url": "https://api.casama.ai/mcp/docs" } } } ``` | Tool | What it does | | --- | --- | | `search_docs` | Searches the docs by keyword and returns the best-matching sections | | `read_doc` | One page as markdown, or one section of it | | `list_doc_pages` | Every page, with its title and address | | `get_api_operation` | Finds API operations by operationId (`sendMessage`), `METHOD /path` (`POST /v1/routines`) or keywords, and shows their parameters, request body and responses as types | The local server, `npx -y @casama/mcp`, has the same tools plus `check_plugin` and `gallery_search`, and the tools that work with your bots once you sign in. With `--docs-only` it runs without a sign-in. See [Connect AI apps](/guide/mcp#docs-tools-for-building-on-casama). A self-hosted server answers at `/mcp/docs` too, from the docs that shipped with it. ## Docs as markdown | Address | What's there | | --- | --- | | [`docs.casama.ai/llms.txt`](https://docs.casama.ai/llms.txt) | An index of every page, with a one-line summary and a link to its markdown ([llmstxt.org](https://llmstxt.org)) | | `docs.casama.ai/.md` | Any page as markdown: add `.md` to its address, for example [`/develop/plugins.md`](https://docs.casama.ai/develop/plugins.md) | | [`docs.casama.ai/llms-full.txt`](https://docs.casama.ai/llms-full.txt) | Every page in one file, about 600 KB | | [`docs.casama.ai/api/openapi.json`](https://docs.casama.ai/api/openapi.json) | The HTTP API as OpenAPI 3.1. Your own server serves its version at `/openapi.json`. | The buttons at the top of every page do the same by hand: **Copy page** copies its markdown, and **Open in Claude** and **Open in ChatGPT** start a chat that reads it. ## Check the gallery first Before your agent writes a new skill, bot, routine, plugin or look, have it look in the [gallery](https://gallery.casama.ai): someone may have made it already, and a gallery item comes checked and ready to add. - **MCP:** the `gallery_search` tool of `npx -y @casama/mcp` takes plain words and, optionally, the kinds to search (`skill`, `app`, `routine`, `bot`, `plugin`, `set`, `theme`, `scheme`, `wallpaper`). It returns the best matches with what each can access, what it needs and its page. - **Terminal:** `casama gallery search "summarize unread email"`, or start from a bot or plugin with `casama init --from-gallery bot/` (or `plugin/`). See the [CLI](/develop/cli#the-gallery-gallery). - **Plain JSON**, no sign-in: | File | What's in it | | --- | --- | | [`index.json`](https://gallery.casama.ai/index.json) | Themes, color schemes, wallpapers and skills | | [`apps.json`](https://gallery.casama.ai/apps.json) | Apps bots can connect to | | [`bots.json`](https://gallery.casama.ai/bots.json) | Starter bots | | [`routines.json`](https://gallery.casama.ai/routines.json) | Routine ideas | | [`plugins.json`](https://gallery.casama.ai/plugins.json) | Reviewed plugins, each pinned to a commit | | [`sets.json`](https://gallery.casama.ai/sets.json) | Starter sets of items that go together | | [`authors.json`](https://gallery.casama.ai/authors.json) | Authors and their items | | [`manifest.json`](https://gallery.casama.ai/manifest.json) | The SHA-256 of every file above, signed with Ed25519 in `manifest.sig` | | [`api.casama.ai/v1/gallery/stats`](https://api.casama.ai/v1/gallery/stats) | How many people use each item, what's trending and how often its runs finish, keyed `/`. Small numbers are left out. | Each item has a page at `https://gallery.casama.ai/i///` with an **Open in Casama** button. The item formats are in [Gallery catalog format](/develop/gallery-format). Bots inside Casama do the same: when someone asks for something a bot has no skill or app for, the bot searches the gallery and offers a match as a card with an **Add** button. ## Starter projects The [CLI](/develop/cli) writes a starting point that already passes Casama's checks: ```sh casama init plugin acme-weather # plugin.json, mcp.json, a small server, a skill, a CI check casama init skill weekly-report # a SKILL.md casama init bot support --name "Support Desk" # a .casama-bot.json template casama init routine routines --name "Daily digest" # a routine file ``` Each one includes an `AGENTS.md` that tells your coding agent the format's rules, how to check the work and where the docs are. `init` needs no sign-in and never overwrites a file unless you pass `--force`. The examples in the repository have one too: [`examples/hello-plugin`](https://github.com/stackwares/casama/tree/main/examples/hello-plugin) and [`examples/sdk_sample`](https://github.com/stackwares/casama/tree/main/examples/sdk_sample). ## Check a plugin ```sh npx @casama/plugin-check . --strict ``` It runs the code Casama runs when someone installs a plugin, and exits 1 when Casama would refuse it (with `--strict`, also when it would skip anything). Agents can run it after every change and fix what it reports. In CI, use the GitHub Action, as described in [Plugins](/develop/plugins#check-your-plugin). ## Tips for working with an agent - Ask it to load `casama-overview` first, or to read `llms.txt`, before it plans anything. - Have it search the gallery before it builds a skill, bot, routine or plugin. - For API work, have it look up each operation with `get_api_operation` rather than writing request bodies from memory. The API changes between versions; the OpenAPI document doesn't lie. - Point it at your own server: the local MCP server reads `CASAMA_API_URL`, and `/openapi.json` on your server describes exactly what it runs. - For plugins, put the plugin check in the loop: write, check, fix, then commit. ## Related - [HTTP API](/develop/api) - [Plugins](/develop/plugins) - [Connect AI apps (MCP)](/guide/mcp) - [CLI](/develop/cli) - [TypeScript client](/develop/typescript) # HTTP API Everything the Casama apps do goes through one HTTP API, and you can call it too: from a shell script, a backend service or your own app. This page covers what every request has in common (authentication, errors, rate limits, idempotency) and how to follow a bot's work live. For every endpoint and schema, see the [API reference](/api/). The routes are defined once, as Zod schemas in `packages/contracts`, and the OpenAPI document is generated from them. So the reference, the Dart client and the server can't drift apart. ## Base URL and versioning Use your server's API address, for example `https://casama.example.com`. Every route lives under `/v1`: ```sh curl https://casama.example.com/v1/config ``` | Path | What it is | | --- | --- | | `/v1/...` | The API | | `/openapi.json` | The OpenAPI 3.1 document for this server | | `/docs` | An interactive reference rendered from that document | | `/healthz` | `{"status":"ok"}` while the process is up | | `/readyz` | 200 when the database and other dependencies answer, 503 when they don't | The `/v1` prefix changes only for breaking changes. Within `/v1`, new fields, endpoints and event types can appear at any time, so ignore fields you don't know. The server's version is in `api_version` from `GET /v1/config` and in `info.version` of `/openapi.json`. ## Public configuration `GET /v1/config` needs no sign-in. It tells a client everything it needs besides the API address: ```sh curl -s https://casama.example.com/v1/config ``` ```json { "product_name": "Casama", "api_version": "0.1.0", "supabase_url": "https://auth.casama.example.com", "supabase_anon_key": "eyJhbGciOi...", "billing_enabled": false, "default_models": { "openrouter": "...", "openai": "..." }, "default_reasoning_effort": "medium" } ``` | Field | Meaning | | --- | --- | | `supabase_url`, `supabase_anon_key` | Where and how to sign in (see below) | | `billing_enabled` | Whether plans and paywalls apply on this server | | `default_models` | The default model id for each model provider | | `default_reasoning_effort` | `none`, `low`, `medium`, `high`, `xhigh` or `max` | | `signup_proofs` | Proofs a new account must carry, if any: `app_check`, `pow` | | `chatgpt_sign_in` | Whether people can connect a ChatGPT plan here | | `wallpapers_enabled` | Whether wallpaper photo search is available | | `trace_url_template` | Where a run's trace opens, with `{trace_id}` in it, or `null` | | `server_voice` | Voice features the server's own keys cover: `live`, `read_aloud`, `dictation` | | `google_client_ids` | Google client ids Auth accepts, for Google's own sign-in sheet in the apps | | `sign_in_codes` | Whether this server makes scan-to-sign-in codes (see below) | | `signups_open` | `false` when new accounts can't be made here, so a client should offer only sign-in | | `signups_by_invitation` | Whether new accounts are only for email addresses someone on this server invited | The fields after `default_reasoning_effort` are optional and may be missing on some servers. ## Authentication The API accepts a **Supabase access token** (a JWT) as a bearer token: ```http Authorization: Bearer eyJhbGciOi... ``` You get one by signing in to the Supabase Auth server named in `/v1/config`. Casama doesn't run its own sign-in endpoint; it verifies the token's signature and requires `aud=authenticated` and `role=authenticated`. ### Sign in with email and password ```sh API=https://casama.example.com CONFIG=$(curl -s "$API/v1/config") SUPABASE_URL=$(echo "$CONFIG" | jq -r .supabase_url) ANON_KEY=$(echo "$CONFIG" | jq -r .supabase_anon_key) curl -s "$SUPABASE_URL/auth/v1/token?grant_type=password" \ -H "apikey: $ANON_KEY" \ -H "content-type: application/json" \ -d '{"email": "ana@example.com", "password": "correct-horse-battery"}' ``` The response holds `access_token`, `refresh_token` and `expires_in` (seconds). Send the access token to Casama. Before it expires, trade the refresh token for a new pair: ```sh curl -s "$SUPABASE_URL/auth/v1/token?grant_type=refresh_token" \ -H "apikey: $ANON_KEY" \ -H "content-type: application/json" \ -d '{"refresh_token": "..."}' ``` These are standard Supabase Auth endpoints, so any Supabase client library works too. The [Dart SDK](/develop/sdk) and the [CLI](/develop/cli) handle sign-in and refresh for you, including magic-link codes and two-step sign-in. ::: tip Two-step sign-in A workspace can require two-step sign-in for its owners and admins. A token from a password-only sign-in still works for everything else, but admin actions in that workspace answer 403 with the code `mfa_required` until you verify a second factor (an `aal2` session). ::: ### What about workspace API keys? Workspace API keys (`ksk_...`, created by admins in workspace settings) don't work on `/v1`. They're for the [hosted MCP endpoint](/guide/mcp) and for [agent-to-agent](/develop/a2a) calls. For scripts that call the REST API, sign in as a person (a dedicated account works well) and refresh the token as shown above. ### Endpoints without a token A few endpoints need no bearer token: - `GET /v1/config`, `GET /v1/app-config` (the owner's [remote app settings](/self-hosting/operations#remote-app-settings)) and `GET /v1/signup/challenge` - `GET /v1/join/preview` and `GET /v1/referral/preview`, which show what an invite opens before you join - `POST /v1/auth/pairing-codes/redeem`, which trades a scanned sign-in code for a one-time sign-in token - `/healthz` and `/readyz` - the inbound [webhooks](/develop/webhooks) under `/hooks/`, which check a signature instead Two WebSocket endpoints carry their own tokens instead of a bearer token: a computer's live view (`GET /v1/computers/{id}/stream`, with the token from `POST /v1/computers/{id}/stream-session`) and the desktop app's computer connection (`GET /v1/local-computer/connect`). ### Sign in another device with a code When `sign_in_codes` is `true` in `/v1/config`, a signed-in client can make a one-time code with `POST /v1/auth/pairing-codes` and show it as a QR code. The other device posts the scanned code to `POST /v1/auth/pairing-codes/redeem` and gets a one-time sign-in token back. The apps use this to sign a phone in to a server reached through [Casama Link](/guide/casama-link). ## Errors Errors use [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details, with the content type `application/problem+json` and a stable `code` you can match on: ```json { "type": "https://casama.ai/problems/validation_failed", "title": "Bad Request", "status": 400, "code": "validation_failed", "detail": "Request validation failed", "instance": "/v1/conversations", "errors": [{ "path": "bot_id", "message": "Invalid UUID" }] } ``` | Field | Meaning | | --- | --- | | `code` | Stable, machine-readable. Match on this, not on `title` or `detail`. | | `status` | The HTTP status, repeated | | `title` | The status's standard name | | `detail` | A sentence for people. It can change. | | `instance` | The request path | | `errors` | For `validation_failed`: one entry per bad field, with its dotted `path` | Common codes: | Status | Code | When | | --- | --- | --- | | 400 | `validation_failed` | The body, query or path didn't match the schema | | 401 | `unauthorized` | No bearer token on a route that needs one | | 401 | `invalid_token` | The token is malformed, expired or not a user token | | 402 | `plan_limit`, `workspace_limit`, `paid_plan_required` | A plan limit was reached (only when billing is on) | | 402 | `out_of_credits` | The workspace is out of credits, so a computer won't start (only when billing is on) | | 403 | `forbidden` | You're signed in but not allowed to do this | | 403 | `mfa_required` | The workspace requires two-step sign-in for this | | 403 | `email_unverified` | Confirm your email address before starting a computer | | 403 | `workspace_suspended` | The instance owner suspended this workspace | | 403 | `computer_forbidden` | A personal computer's files are only for its owner and the bots they allowed | | 404 | `not_found` | No such route | | 404 | `bot_not_found`, `org_not_found`, `conversation_not_found`, ... | The thing doesn't exist or you can't see it | | 409 | `run_finished` | You tried to cancel a run that already ended | | 409 | `device_offline` | A personal computer's desktop app isn't connected | | 409 | `chat_private` | A chat that holds personal device data can't be shared publicly | | 422 | `idempotency_key_reused` | The `Idempotency-Key` was used for a different request | | 429 | `rate_limited` | Too many requests; see `Retry-After` | | 429 | `too_many_links` | The workspace made its daily number of public Library links | | 500 | `internal_error` | A server bug. Retry later; the server logged it. | | 503 | `computer_unavailable` | The bot's computer couldn't be reached (stopping, waking or restarting). Retry shortly. | | 503 | `capacity_full` | The server has no room to start another computer right now. Retry in a few minutes. | Every response carries an `x-request-id` header. Send your own `x-request-id` to tie a request to your logs, and include it when you report a problem. ## Rate limits Requests to `/v1/*` and `/hooks/*` are limited per minute, per signed-in user (or per client IP address without a token). The default is 120 requests a minute; self-hosters change it with `RATE_LIMIT_PER_MINUTE`. Over the limit, the API answers 429 with the code `rate_limited` and a `Retry-After` header in seconds. Wait that long, then retry. The window is a fixed minute kept in the API process's memory, so a server that runs several API processes counts each one separately. The [Casama Link](/guide/casama-link) paths under `/link/`, which self-hosted servers call, get ten times the limit. ## Idempotency keys Network errors happen. To retry a `POST`, `PUT`, `PATCH` or `DELETE` without doing it twice, send an `Idempotency-Key` header with a value you generate once per action (a UUID works well): ```sh curl -s -X POST "$API/v1/conversations/$CONVERSATION/messages" \ -H "authorization: Bearer $TOKEN" \ -H "content-type: application/json" \ -H "idempotency-key: 6f1c2b7e-4c1a-4f0e-9a43-2b8d0f7c9e11" \ -d '{"text": "Draft the weekly update"}' ``` - The first response that isn't a server error (status below 500) is stored, and a retry with the same key gets the same status and body back, with the header `idempotent-replayed: true`. - Keys belong to the signed-in user and are kept for 24 hours. - Reusing a key for a different method or path answers 422 `idempotency_key_reused`. - Keys are up to 255 characters; a longer one answers 400 `validation_failed`. Requests without a token, and `GET` requests, ignore the header. ## Lists and pagination Most list endpoints return everything you can see in one response, wrapped in an object: ```json { "items": [ { "id": "..." } ] } ``` A few lists are paged, each in the way that suits it: | List | How to page | | --- | --- | | Run events (`GET /v1/runs/{id}/events`) | By sequence number: `after_seq` and `limit` (see [below](#read-events-after-the-fact)) | | The Library (`GET /v1/creations`) | By cursor: pass the response's `next_cursor` back as `cursor` until it's `null` | | A chat's messages (`GET /v1/conversations/{id}/thread`) | Without `limit`, the whole branch. With `limit` (up to 500), the newest messages; add `before=` for the page before it | The [API reference](/api/) lists each endpoint's parameters. ## Runs and live events When you send a message, the bot starts a **run**: one piece of work, from reading your message to its final answer. Every step of a run is an **event**, stored in order. You can read them after the fact, or stream them while the run works. ### The event envelope ```json { "v": 1, "run_id": "0b9e7c52-1f0a-4a4e-9d2c-6f3f1b0d8a11", "seq": 7, "ts": "2026-11-11T21:04:05.123Z", "bot_id": "5d0c1e6a-8b7f-4e8a-a1d2-3c4b5a6f7e80", "type": "message.delta", "payload": { "message_id": "c1f9...", "text": "Here's the draft" } } ``` | Field | Meaning | | --- | --- | | `v` | Protocol version, currently `1` | | `run_id`, `bot_id` | Which run, which bot | | `seq` | 1, 2, 3, ... per run, with no gaps | | `ts` | When it happened | | `type` | The event type | | `payload` | Depends on `type` | Ignore event types you don't know: new ones are added without a version change. ### Event types The ones most clients care about: | Type | Payload | Meaning | | --- | --- | --- | | `run.started` | `trigger`, `model`, `computer_id` | The run began | | `message.delta` | `message_id`, `text` | A piece of the bot's reply; append `text` | | `message.completed` | `message_id`, `content` | The reply is complete; `content` is the full list of parts | | `tool.started` | `call_id`, `tool`, `args_redacted` | The bot started using a tool | | `tool.output` | `call_id`, `chunk` | Output from a running tool, such as a shell command | | `tool.completed` | `call_id`, `result_preview`, `artifact_path`, `duration_ms` | The tool finished | | `tool.failed` | `call_id`, `error_code`, `message` | The tool failed; the run usually goes on | | `approval.requested` | `approval_id`, `tool`, `args_redacted`, `risk`, `expires_at` | The bot is waiting for someone to approve a step | | `approval.resolved` | `approval_id`, `decision`, `decided_by` | `approved`, `denied` or `expired` | | `usage` | `tokens_in`, `tokens_out`, `cost_usd` | Running totals for the run | | `notice` | `code`, `message` | Something the person should know about the run | | `run.completed` | `final_message_id` | Finished. The last event. | | `run.failed` | `error_code`, `message` | Failed. The last event. | | `run.cancelled` | `cancelled_by` | Cancelled. The last event. | Others you may see: `secret.requested` and `secret.resolved` (the bot asked for a secret), `takeover.requested` and `takeover.resolved` (the bot asked a person to take over its computer), `lease.changed`, `computer.state`, `checkpoint.created`, `subrun.started` and `subrun.completed` (work handed to a helper), `memory.written`, `skill.loaded`, `model.fallback`, `device.access_requested`, `device.data_used`, and `ui.shown` (an interactive card in the chat). The [API reference](/api/) has every payload as a schema (`RunEvent`). ### Read events after the fact ```sh curl -s "$API/v1/runs/$RUN/events?after_seq=0&limit=500" \ -H "authorization: Bearer $TOKEN" ``` ```json { "items": [ { "v": 1, "seq": 1, "type": "run.started", "...": "..." } ], "run_status": "running" } ``` `after_seq` (default 0) returns events with a higher `seq`. `limit` is 1 to 1000 (default 500). To page, call again with `after_seq` set to the last `seq` you got. `run_status` is the run's status right now: `queued`, `running`, `waiting_approval`, `waiting_takeover`, `completed`, `failed` or `cancelled`. ### Stream events live (SSE) Send `Accept: text/event-stream` to the same endpoint to get a [server-sent event](https://html.spec.whatwg.org/multipage/server-sent-events.html) stream: ```sh curl -sN "$API/v1/runs/$RUN/events" \ -H "authorization: Bearer $TOKEN" \ -H "accept: text/event-stream" ``` ```text event: run_event data: {"v":1,"run_id":"0b9e...","seq":1,"ts":"...","bot_id":"5d0c...","type":"run.started","payload":{...}} id: 1 event: run_event data: {"v":1,"run_id":"0b9e...","seq":2,"ts":"...","bot_id":"5d0c...","type":"message.delta","payload":{...}} id: 2 event: ping data: {} ``` - The stream first sends every stored event after `after_seq`, then live events as they happen. - Each `run_event` has the event's `seq` as its SSE `id`. - While nothing happens, a `ping` event arrives every 15 seconds. Ignore it. - The server closes the stream after `run.completed`, `run.failed` or `run.cancelled`. If the run had already ended, you get the stored events and then the stream closes. **Reconnecting.** If the connection drops, reconnect with the `Last-Event-ID` header set to the last `seq` you processed (or `?after_seq=`). You get exactly the events you missed. Events are stored before they're sent, so nothing is lost and nothing is sent twice if you track `seq`. The Dart SDK's `watchRun` does this for you, with backoff. ::: details Apps: Supabase Realtime The Casama app gets live events through Supabase Realtime instead (private topic `run:`) and fills any gaps from `GET /v1/runs/{id}/events?after_seq=`. SSE is the simpler choice for scripts and servers. ::: ### Approvals When a run waits on an `approval.requested` event, a person with access approves or denies it: ```sh curl -s -X POST "$API/v1/approvals/$APPROVAL/decision" \ -H "authorization: Bearer $TOKEN" \ -H "content-type: application/json" \ -d '{"decision": "approved"}' ``` `decision` is `approved` or `denied`; add `"always_allow": true` to stop asking about this tool for this bot. Denying fails only that step, and the bot carries on. `GET /v1/approvals?org_id=...&status=pending` lists what's waiting. See [Autonomy and approvals](/guide/autonomy) for how risk decides what asks. ### Cancel a run ```sh curl -s -X POST "$API/v1/runs/$RUN/cancel" -H "authorization: Bearer $TOKEN" ``` The API answers 202 with the run, and the worker stops it (and any helper runs it started) within about two seconds. The run then ends with a `run.cancelled` event. Cancelling a run that already ended answers 409 `run_finished`. ## The Library Everything bots make that you can open again (pages, pictures, videos, sounds, documents and kept files) is a **creation**, listed in the Library. List a workspace's creations, newest first: ```sh curl -s "$API/v1/creations?org_id=$ORG&kind=document&limit=20" -H "authorization: Bearer $TOKEN" | jq '{next_cursor, items: [.items[] | {id, kind, title, bot_name}]}' ``` Filter with `kind` (`page`, `image`, `video`, `audio`, `document` or `file`), `bot_id`, `conversation_id`, `project_id`, `pinned=true` or a search term in `q`. `sort=opened` lists what you opened most recently. `limit` is 1 to 100 (default 40). Read one with `GET /v1/creations/{id}`. Its bytes come from `GET /v1/creations/{id}/content` (pictures, videos and sound; it honours one byte range), its card picture from `/cover` when `has_cover` is true, and a document's PDF from `/preview` when `has_preview` is true. Change who can see it with `PATCH`: ```sh curl -s -X PATCH "$API/v1/creations/$CREATION" -H "authorization: Bearer $TOKEN" \ -H "content-type: application/json" \ -d '{"visibility": "public"}' | jq -r .public_url ``` `visibility` is `private`, `workspace` (every member) or `public` (anyone with the link). The public link is in `public_url` only in this one response; making it public again gives a new link and the old one stops working. The same `PATCH` renames it (`title`), pins it (`pinned`) or files it under a project (`project_id`). `DELETE` hides it at once, and `POST /v1/creations/{id}/restore` brings it back within 30 days. A public link opens a read-only viewer on the server's pages address, with no scripts. Pictures, videos, sound and PDFs show in the page; any other file downloads instead. ## Export or share a chat Download a chat as Markdown (the default) or JSON. It holds only what you can see: ```sh curl -s "$API/v1/conversations/$CONVERSATION/export?format=json" \ -H "authorization: Bearer $TOKEN" -o chat.json ``` Make a public, read-only link to it: ```sh curl -s -X POST "$API/v1/conversations/$CONVERSATION/share" -H "authorization: Bearer $TOKEN" \ -H "content-type: application/json" -d '{"public": true}' ``` ```json { "url": "https://pages.casama.example.com/t/..." } ``` Only the person who started the chat, or someone who manages its bot, can share it. Sharing again gives a new link; `{"public": false}` turns the link off and returns `{"url": null}`. A chat that holds personal data from a device answers 409 `chat_private`. ## Find your way around The [API reference](/api/) groups endpoints by tag. The main groups: | Area | Paths | | --- | --- | | Workspaces, members, invites, settings | `/v1/orgs`, `/v1/orgs/{id}/...`, `/v1/join`, `/v1/me` | | Bots and their memory | `/v1/bots`, `/v1/bots/{id}/...` | | Chats and runs | `/v1/conversations`, `/v1/runs`, `/v1/approvals`, `/v1/search` | | Routines, tickets, watchers | `/v1/routines`, `/v1/tasks`, `/v1/watchers` | | Computers | `/v1/computers`, `/v1/local-devices` | | The Library and pages | `/v1/creations`, `/v1/pages`, `/v1/projects` | | Connections and model keys | `/v1/integrations`, `/v1/apps`, `/v1/credentials` | | Skills and plugins | `/v1/skills`, `/v1/plugins` | | Usage and billing | `/v1/usage`, `/v1/orgs/{id}/billing` | | Casama Link | `/v1/orgs/{id}/link/...`, `/v1/admin/remote-access` | | Instance owner | `/v1/admin/...` | ## Walkthrough: chat with a bot from the shell This puts it all together with `curl` and `jq`. You need an account on the server and a bot you can use. **1. Sign in.** ```sh API=https://casama.example.com CONFIG=$(curl -s "$API/v1/config") SUPABASE_URL=$(echo "$CONFIG" | jq -r .supabase_url) ANON_KEY=$(echo "$CONFIG" | jq -r .supabase_anon_key) TOKEN=$(curl -s "$SUPABASE_URL/auth/v1/token?grant_type=password" \ -H "apikey: $ANON_KEY" -H "content-type: application/json" \ -d '{"email": "ana@example.com", "password": "correct-horse-battery"}' | jq -r .access_token) AUTH="authorization: Bearer $TOKEN" ``` **2. Find your workspace and bot.** ```sh ORG=$(curl -s "$API/v1/orgs" -H "$AUTH" | jq -r '.items[0].id') curl -s "$API/v1/bots?org_id=$ORG" -H "$AUTH" | jq -r '.items[] | "\(.id) \(.name)"' BOT=5d0c1e6a-8b7f-4e8a-a1d2-3c4b5a6f7e80 # pick one from the list ``` **3. Start a conversation.** ```sh CONVERSATION=$(curl -s -X POST "$API/v1/conversations" -H "$AUTH" \ -H "content-type: application/json" \ -d "{\"bot_id\": \"$BOT\", \"title\": \"From the shell\"}" | jq -r .id) ``` **4. Send a message.** The API answers 202 with the run it started. ```sh RUN=$(curl -s -X POST "$API/v1/conversations/$CONVERSATION/messages" -H "$AUTH" \ -H "content-type: application/json" \ -H "idempotency-key: $(uuidgen)" \ -d '{"text": "What can you do for me? Answer in three bullets."}' | jq -r .run_id) ``` The response also has `message_id` and `conversation_id`. If the bot was already working in this conversation, `joined` is `true` and `run_id` is that run: it reads your message before its next step. **5. Stream the run** and print the reply as it arrives: ```sh curl -sN "$API/v1/runs/$RUN/events" -H "$AUTH" -H "accept: text/event-stream" | while IFS= read -r line; do case "$line" in data:*) json=${line#data: } case $(echo "$json" | jq -r '.type // empty') in message.delta) printf '%s' "$(echo "$json" | jq -r .payload.text)" ;; tool.started) echo; echo "[tool] $(echo "$json" | jq -r .payload.tool)" ;; run.failed) echo; echo "failed: $(echo "$json" | jq -r .payload.message)" ;; run.completed) echo ;; esac ;; esac done ``` **6. Check the result.** `GET /v1/runs/{id}` returns the run's status, tokens, cost and any error; `GET /v1/conversations/{id}/thread` returns the conversation's messages, oldest first. ```sh curl -s "$API/v1/runs/$RUN" -H "$AUTH" | jq '{status, tokens_in, tokens_out, cost_usd, error}' ``` ## Limits | What | Limit | | --- | --- | | Requests | 120 a minute per user or IP address by default (`RATE_LIMIT_PER_MINUTE`) | | `Idempotency-Key` | 255 characters; kept 24 hours | | Message `text` | 100,000 characters | | Attachments per message | 10 | | Run events per page | 1,000 (default 500) | | Library items per page | 100 (default 40) | | Chat messages per page | 500 | | New public Library links | 20 per workspace a day | | Bots in a group chat | 10 | ## Related - [API reference](/api/): every endpoint and schema - [Dart SDK](/develop/sdk): a typed client with sign-in and `watchRun` - [CLI](/develop/cli): the same API from your terminal - [Webhooks](/develop/webhooks): start routines from other services - [Agent-to-agent (A2A)](/develop/a2a): call bots with workspace API keys - [Hosted MCP](/guide/mcp): use bots from AI apps # How Casama is built This page is for people who want to read or change Casama's code. It maps the repository, follows one chat message from the app to a computer and back, and shows where the security boundaries are. To set up a development machine, see [Contribute to Casama](/develop/contributing). ## The pieces A Casama server is a small set of services around one Postgres database: | Service | What it does | | ------------------------- | ----------------------------------------------------------------------------------------------- | | **API** | The HTTP API under `/v1`, the live run stream, incoming webhooks, A2A and the hosted MCP server | | **Worker** | Runs bots: each run is a durable workflow that survives a crash or restart | | **Supabase** | Postgres, Auth, Realtime and Vault. Every table has row-level security | | **Supervisor** | Starts, stops and talks to computers. It is the only service with the Docker socket | | **Computers** | One container per computer, with `computerd` inside | | **Egress proxy** | Every computer's way to the internet. It blocks private addresses | | **TURN relay** | Carries the live view of a desktop computer | | **Pages server** | Serves pages bots make, from their own origin | The API and the worker are one TypeScript codebase. `MODE=api` serves HTTP and `MODE=worker` runs workflows. Node.js runs the TypeScript sources directly, so there's no build step. The self-host compose file (`infra/compose/docker-compose.yml`) adds a few optional services: `connector` for [remote access](/self-hosting/remote-access), `backup`, SearXNG for web search, a PDF renderer, Caddy for HTTPS, the web app, and Prometheus and Grafana for monitoring. ## Repository map | Folder | What's in it | | ----------------------- | ------------------------------------------------------------------------------------------------------------------ | | `apps/server` | The API (`src/api`) and the worker (`src/worker`), billing, Casama Link (`src/link`) and the pages server (`src/pages`) | | `apps/supervisor` | The supervisor's HTTP API and terminal proxy | | `packages/contracts` | Every route and schema (Zod). The OpenAPI document and the Dart client are generated from it | | `packages/agent` | The agent runtime: the run loop, context building, memory, tools, the model gateway and integrations | | `packages/db` | The Drizzle schema pulled from the migrations, the database client, `withUserSession`, and test helpers | | `packages/domain` | Pure logic with no I/O: roles, approvals, budgets, limits | | `packages/sandbox` | The computer provider interface, the Docker provider, the `computerd` client and object stores | | `packages/mcp` | `@casama/mcp`, the MCP server that lets coding tools drive your bots | | `packages/plugin-check` | `casama-plugin-check`, the plugin checker, also run as a GitHub Action | | `packages/evals` | Agent evaluations and their tasks | | `packages/observability`| Logging, OpenTelemetry and error reporting | | `client` | The Flutter app for iOS, Android, macOS, Windows, Linux and the web | | `dart/casama_api` | The generated Dart REST client. Don't edit it by hand | | `dart/casama_sdk` | The [Dart SDK](/develop/sdk): sign-in, typed run events, live run watching | | `dart/cli` | The [`casama` CLI](/develop/cli) | | `dart/computerd` | The agent inside each computer, and on your own machine in desktop companion mode | | `supabase` | Migrations (the source of truth for the schema) and pgTAP tests in `supabase/tests` | | `infra` | Compose files, computer images, the egress proxy, TURN, the remote access connector, backups, Helm, monitoring | | `ee` | Enterprise features under a separate license: audit log export and SAML single sign-on | | `skills` | The skills bundled with every server | | `gallery` | The gallery site: themes, wallpapers, skills, apps, starter bots, routine ideas and plugins | | `site` | The casama.ai website | | `docs-site` | These docs (VitePress) | | `deploy` | One-click deploy templates for hosting platforms | | `examples` | A sample plugin and a sample SDK app | | `scripts` | Development, test and packaging scripts | | `docs` | Project records: architecture notes and the decision log | ## One chat message, end to end 1. **The app sends it.** The app calls `POST /v1/conversations/{id}/messages`. Simple reads and edits go straight to Supabase under row-level security; anything that does work goes through the API. 2. **The API records it.** Inside the person's database session, the API saves the message, creates a queued run and enqueues an `agentRun` workflow, using the run id as the workflow id. It answers right away with the run id. 3. **The worker runs it.** A worker picks up the workflow. It checks the run is allowed (budget, quota, a model is set up), recalls memories and builds the context. 4. **The model answers.** Model calls go through the model gateway, which falls back to the next model on rate limits, server errors and timeouts. Every model call and tool call is its own durable step, so a crashed worker resumes at the last finished step instead of starting over. 5. **Tools touch a computer.** When a tool needs a computer (`shell.exec`, files, the browser), the worker asks the supervisor to start or wake the bot's computer, then sends the command to `computerd` inside it. Anything the computer fetches from the internet goes through the egress proxy. 6. **Approvals pause it.** If a tool call needs a person's approval, the run emits `approval.requested` and waits, durably, for as long as it takes. 7. **Events stream back.** Every step appends a numbered run event in one transaction. A database trigger broadcasts it on Supabase Realtime, which the app listens to, and on Postgres `NOTIFY`, which the API forwards to the server-sent events stream at `/v1/runs/{id}/events` that the CLI and SDK use. Clients that miss events catch up by sequence number. 8. **The run ends.** The worker saves the answer, extracts new memories, records usage and emits `run.completed`. A cancel request is noticed within half a second while streaming, or at the next step. Routines, webhooks, chat apps, A2A calls and device triggers all start runs the same way: they create a run and enqueue the same workflow. ## Data model essentials The schema is in `supabase/migrations`. The tables you'll meet first: - **`organizations`** (workspaces), **`memberships`** with a role (owner, admin, member), and **`profiles`**. Almost every other row carries an `org_id`. - **`bots`**, with their instructions, model, autonomy level and default computer. - **`conversations`** and **`messages`**: chats. A conversation can include more than one bot. - **`runs`** and **`run_events`**: one run per piece of bot work, and its gap-free event log. - **`computers`** and **`checkpoints`**: a bot's computer and its saved states. - **`memories`**, **`skills`**, **`routines`**, **`tasks`**, **`approvals`**, **`integrations`**, **`secrets`** and **`model_credentials`**. - **`creations`**: the Library, one row per thing a bot made (pages, images, files). - **`usage_ledger`**: every model call and every second of computer time, with its cost. Model keys and named secrets live in Supabase Vault. Tables hold only a reference to them. ## Security boundaries - **Workspace isolation is enforced by Postgres.** The API runs each request inside `withUserSession`, which switches the transaction to the `authenticated` role with the caller's JWT claims. Row-level security policies, built on helpers like `is_member`, `has_role` and `can_access_bot`, decide what that person can see. A bug in a route can't read another workspace's rows. - **The worker is not a superuser.** It connects as its own database role with explicit per-table policies and no way to bypass row-level security. New tables grant it access with `public.allow_worker`. - **Secrets never reach the model.** Keys are written to Vault through the API and never returned. Tools write `{{secret:NAME}}`, and the worker swaps in the value only when the destination host is on that secret's allowlist. Every event, message and tool result passes through a redactor that knows the run's secrets. - **Untrusted content is marked.** Web pages, files and tool output are wrapped as untrusted in the model's context, and outbound HTTP from tools refuses private, loopback and cloud metadata addresses after DNS resolution. - **Computers are locked down.** Each computer runs as user 1000 with a read-only root filesystem, all Linux capabilities dropped, `no-new-privileges` and a process limit, on its own internal network. Its only way out is the egress proxy, with per-computer credentials. Only the supervisor holds the Docker socket. - **Risky actions need a person.** The approval rules in `packages/domain` combine the bot's autonomy level, each tool's risk and standing "always allow" grants. - **Bot pages get their own origin.** Pages bots publish are served from a separate address with a strict content security policy, so a page can't reach the app's session. - **Content can be encrypted at rest** per workspace, with keys wrapped locally or by AWS KMS. ## Generated code `packages/contracts` is the single source for the API. `pnpm gen` writes `packages/contracts/openapi.json` (served as the [API reference](/api/)) and regenerates `dart/casama_api` and the SDK's generated files. `pnpm --filter @casama/db pull` regenerates the Drizzle schema from the database. CI fails if any generated file is out of date. ## Why things are the way they are `docs/DECISIONS.md` in the repository records every design decision with its reasoning, numbered `D-001` onward. `docs/ARCHITECTURE.md` is the detailed as-built map, with the files behind each feature. Search both before changing something that looks deliberate. # Bot template format A bot template is one JSON file that describes a bot people can import: its instructions, skills, routines and the services it works with. It never carries keys, secrets or chats, so it's safe to share in public. Files use the extension `.casama-bot.json`, and the format is called `casama.bot`, version 1. ## Where templates come from - **Export from the app.** In a bot's settings, **Share as template** saves the file or copies a share link. You choose whether to include the bot's memories. - **Export from the API.** `GET /v1/bots/{id}/export` returns the template for any bot you can see. Add `?memories=true` to include memories; that only takes effect for people who manage the bot. - **Write one by hand.** It's plain JSON; the full example below is a good start. ```sh curl -s "https://casama.example.com/v1/bots/$BOT/export" \ -H "authorization: Bearer $TOKEN" > invoicer.casama-bot.json ``` ## A full example ```json { "format": "casama.bot", "version": 1, "name": "Invoicer", "description": "Chases unpaid invoices politely.", "persona_md": "You chase unpaid invoices for a small design studio. Be polite and brief...", "autonomy": "ask_risky", "avatar": "mascot:cool", "skills": [ { "name": "dunning", "description": "Follow-up cadence for overdue invoices. Use when an invoice is past due.", "body_md": "1. Day 7: a friendly reminder.\n2. Day 14: a firmer note with the invoice attached.\n3. Day 30: tell me before sending anything else.", "files": [ { "path": "templates/reminder.md", "content_base64": "SGkge25hbWV9LCBqdXN0IGEgcmVtaW5kZXIuLi4=", "executable": false }, { "path": "scripts/overdue.sh", "content_base64": "IyEvYmluL2Jhc2gKZWNobyAiY2hlY2tpbmcuLi4iCg==", "executable": true } ] } ], "routines": [ { "name": "Weekly chase", "instructions_md": "Check for overdue invoices and follow the dunning skill.", "schedule_cron": "0 9 * * 1" } ], "connections": [ { "kind": "composio", "name": "gmail" }, { "kind": "mcp", "name": "accounting" } ], "memories": [ { "kind": "preference", "content": "Invoices go out from billing@example.com." } ] } ``` ## Fields | Field | Type | Required | Rules | | --- | --- | --- | --- | | `format` | string | yes | Always `"casama.bot"` | | `version` | integer | yes | Always `1` | | `name` | string | yes | 1 to 80 characters | | `description` | string | no | Up to 300 characters. A one-line summary for people browsing templates. | | `persona_md` | string | yes | The bot's instructions, in Markdown. Up to 20,000 characters (can be empty). | | `autonomy` | string | yes | `ask_always`, `ask_risky` or `autonomous` | | `avatar` | string or null | no | A built-in mascot, `mascot:`, or `null` | | `skills` | array | no | Up to 30. See [Skills](#skills). | | `routines` | array | no | Up to 20. See [Routines](#routines). | | `connections` | array | no | Up to 30. See [Connections](#connections). | | `memories` | array | no | Up to 200. See [Memories](#memories). | The optional lists can be left out; a missing list means none. ### `autonomy` How much the bot may do without asking. See [Autonomy and approvals](/guide/autonomy). | Value | Meaning | | --- | --- | | `ask_always` | Asks before any action with side effects | | `ask_risky` | The default. Asks before high-risk actions, paid data lookups and payments, and before a medium-risk action that sends data out after reading outside content | | `autonomous` | Asks only before high-risk actions on personal computers | ### `avatar` One of the built-in mascots: `mascot:cool`, `mascot:focused`, `mascot:giggly`, `mascot:lovey`, `mascot:shy`, `mascot:sleepy`, `mascot:starry`, `mascot:thinker`, `mascot:winky` or `mascot:wow`. Anything that doesn't start with `mascot:` is dropped on import, and uploaded pictures are never exported. ### Skills The bot's own skills, in the open [Agent Skills](https://agentskills.io) shape. See [Skills](/guide/skills). | Field | Type | Required | Rules | | --- | --- | --- | --- | | `name` | string | yes | Lowercase letters, digits, `-` and `_`, starting with a letter or digit; up to 63 characters | | `description` | string | yes | 1 to 300 characters. The bot reads it when choosing a skill, so say when to use it. | | `body_md` | string | yes | The skill's instructions, up to 50,000 characters | | `files` | array | no | Files the skill uses, up to 60 | Each file: | Field | Type | Required | Rules | | --- | --- | --- | --- | | `path` | string | yes | A relative path of letters, digits, `.`, `_`, `-` and `/`, with no `..` | | `content_base64` | string | yes | The file's bytes, base64-encoded. Up to 1 MB per file once decoded. | | `executable` | boolean | no | Keep the executable bit (default `false`) | A skill's files can total up to 5 MB. Scripts in a skill only ever run on the bot's own sandboxed computer, never on the Casama server. ### Routines Repeating schedules. See [Routines](/guide/routines). | Field | Type | Required | Rules | | --- | --- | --- | --- | | `name` | string | yes | 1 to 120 characters | | `instructions_md` | string | yes | What to do each time, 1 to 20,000 characters | | `schedule_cron` | string | yes | A standard 5-field cron expression, such as `0 9 * * 1` (Mondays at 9:00) | There's no time zone in the file: routines run in the importing person's time zone. An end (`ends_at` or `max_runs`) doesn't travel either, so imported routines repeat until someone sets one. An export includes every routine with a cron schedule, paused ones too, except check-ins, which belong to the bot's check-in settings. Imported routines start switched on. ### Connections Services the bot works with, so the person importing knows what to connect. Names only: no credentials, tokens or addresses ever travel. | Field | Type | Rules | | --- | --- | --- | | `kind` | string | The connection type, such as `mcp`, `openapi`, `composio` or `a2a`. Up to 40 characters. | | `name` | string | The connection's name in the exporting workspace. Up to 120 characters. | ### Memories Only present when the person exporting chose to include them. | Field | Type | Rules | | --- | --- | --- | | `kind` | string | `fact`, `episode`, `summary` or `preference` | | `content` | string | 1 to 8,000 characters | An export includes up to 200 memories, pinned and most important first. ## Never in a template Casama never writes these into a template, and import doesn't read them: - model keys, secrets, OAuth tokens or any other credential - the model choice (the person importing picks a key and model) - chats and conversation history - files from the bot's computer - uploaded avatar pictures - skills shared by the whole workspace, turned-off skills, and routines that aren't on a repeating schedule (webhook, one-time and other triggers) ## Import a template In the app, open **Bots → Import a bot** and pick the file, or open a share link (`https:///import/`). Casama previews the instructions, skills, routines, connections and memory count, and you choose a model key and model, and whether to bring the routines and memories. From the API, `POST /v1/bots/import`: ```sh jq -n --slurpfile t invoicer.casama-bot.json \ --arg org "$ORG" --arg key "$CREDENTIAL" --arg model "$MODEL" \ '{org_id: $org, template: $t[0], credential_id: $key, model: $model, include_routines: true, include_memories: false}' | curl -s -X POST "https://casama.example.com/v1/bots/import" \ -H "authorization: Bearer $TOKEN" \ -H "content-type: application/json" \ -d @- ``` | Field | Required | Meaning | | --- | --- | --- | | `org_id` | yes | The workspace to create the bot in | | `template` | yes | The template file's contents | | `credential_id` | yes | A model key from that workspace | | `model` | yes | The model id the bot uses on that key | On Casama Cloud, and on any server where billing and Casama's own model upstream are switched on, the new bot uses the server's cloud model and credits instead: `credential_id` and `model` are still required but replaced. | `include_routines` | no | Create the routines (default `true`) | | `include_memories` | no | Add the memories (default `true`) | It answers `201 Created`: ```json { "bot_id": "2a7d4c1e-9b8f-4e6a-8c5d-3f2e1a0b9c8d", "skills": 1, "routines": 1, "memories": 0, "connections_to_add": [ { "kind": "composio", "name": "gmail" }, { "kind": "mcp", "name": "accounting" } ] } ``` What import does: - **Checks first.** The file must match the schema above (`validation_failed` lists what's wrong), every skill's files are checked against the limits, and every routine's cron schedule is validated. A problem stops the import with nothing created (`skill_too_large`, `skill_bad_path` or `invalid_cron`). - **Creates a new bot** owned by you, with the template's name, instructions, autonomy and mascot, and the key and model you picked. It counts toward your plan's bot limit when billing is on. - **Adds the skills** with their files and executable bits. - **Adds the routines** (if `include_routines`) in your profile's time zone, or UTC if you haven't set one. - **Adds the memories** (if `include_memories`). - **Doesn't connect anything.** `connections_to_add` lists the services to connect yourself; see [Connections](/guide/connections). Importing always creates a new bot; it never changes an existing one. Common errors: `forbidden` (you can't create bots in that workspace), `credential_not_found` (the key isn't in that workspace) and the plan's bot limit. ## Convert an agent from OpenClaw or Hermes Agent `POST /v1/agent-imports` reads an OpenClaw or Hermes Agent folder and returns a `casama.bot` template for you to review. Nothing is created yet. Send the folder as a ZIP or as a list of files, up to 50 MB and 3,000 files: ```sh jq -n --arg org "$ORG" --arg zip "$(base64 < openclaw.zip | tr -d '\n')" \ '{org_id: $org, zip_base64: $zip}' | curl -s -X POST "https://casama.example.com/v1/agent-imports" \ -H "authorization: Bearer $TOKEN" \ -H "content-type: application/json" \ -d @- ``` | Response field | Meaning | | --- | --- | | `id` | The import, for copying the leftover files later | | `kind` | `openclaw` or `hermes` | | `template` | A `casama.bot` template, ready for `POST /v1/bots/import` | | `sources` | Where each skill, routine and memory came from, in the same order as the template | | `leftovers` | Files nothing mapped to, with their size | | `skipped` | Files that were never read (keys, settings, sessions, logs), with the reason | | `notes` | What was left out or trimmed, such as paused jobs or a persona over 20,000 characters | Drop what you don't want from `template`, then send it to `POST /v1/bots/import` as above. To copy the leftovers to `~/imported/openclaw/` or `~/imported/hermes/` on the new bot's computer, call `POST /v1/agent-imports/{id}/files` with `{"bot_id": "..."}` (for people who manage the bot). It answers `409` while the bot has no computer yet. Uploads are kept for a day. See [Import an agent](/guide/sharing#import-an-agent) for what each kind maps to. ## Share links `POST /v1/bots/{id}/share` (for people who manage the bot) saves a snapshot of the template and returns a link: ```sh curl -s -X POST "https://casama.example.com/v1/bots/$BOT/share" \ -H "authorization: Bearer $TOKEN" \ -H "content-type: application/json" \ -d '{"include_memories": false, "expires_in_days": 30}' ``` ```json { "token": "q3V9...", "url": "https://app.casama.example.com/import/q3V9...", "expires_at": "2026-12-11T15:00:00.000Z" } ``` `expires_in_days` is 1 to 365 (default 30), or `null` for a link that doesn't expire. Anyone signed in to the same Casama server, in any workspace, can open the link to preview and import the snapshot; `GET /v1/bot-shares/{token}` returns it. The snapshot doesn't change when you edit the bot later: share again for a fresh one. ## Limits | What | Limit | | --- | --- | | Name | 80 characters | | Description | 300 characters | | Instructions (`persona_md`) | 20,000 characters | | Skills | 30 per template | | Skill body | 50,000 characters | | Files per skill | 60 | | File size | 1 MB each, 5 MB per skill | | Routines | 20 per template | | Connections | 30 per template | | Memories | 200 per template, 8,000 characters each | | Share link expiry | 1 to 365 days, or never | ## Related - [Bots](/guide/bots) - [Skills](/guide/skills) - [Routines](/guide/routines) - [Sharing](/guide/sharing) - [Routines and skills as files](/develop/workspace-files): a workspace's routines and skills as Markdown files # CLI `casama` is the command-line client for Casama. It talks to any Casama server: sign in, manage workspaces, model keys and bots, chat with a bot and watch it work, reach into its computer, move routines and skills as files, and run your own server. Every command can print JSON for scripts. ## Install ### Homebrew (macOS and Linux) ```sh brew install stackwares/tap/casama ``` ### Release binaries Each CLI release on [GitHub](https://github.com/stackwares/casama/releases) (tagged `cli-v`) has a native binary for each platform, with a SHA-256 checksum file next to it: | Platform | File | | --- | --- | | macOS, Apple silicon | `casama--darwin-arm64.tar.gz` | | macOS, Intel | `casama--darwin-x64.tar.gz` | | Linux, x64 | `casama--linux-x64.tar.gz` | | Linux, ARM64 | `casama--linux-arm64.tar.gz` | | Windows, x64 | `casama--windows-x64.zip` | ```sh v=0.1.0 curl -LO "https://github.com/stackwares/casama/releases/download/cli-v$v/casama-$v-linux-x64.tar.gz" curl -LO "https://github.com/stackwares/casama/releases/download/cli-v$v/casama-$v-linux-x64.tar.gz.sha256" shasum -a 256 -c "casama-$v-linux-x64.tar.gz.sha256" tar xzf "casama-$v-linux-x64.tar.gz" sudo mv casama /usr/local/bin/ casama --version ``` The binary is self-contained: no Dart runtime needed. ### From source With the [Dart SDK](https://dart.dev/get-dart) 3.13 or later and a clone of the repository: ```sh cd dart && dart pub get && cd cli dart compile exe bin/casama.dart -o casama ``` ## Connect and sign in The CLI talks to Casama Cloud (`https://api.casama.ai`) until you point it somewhere else. For your own server, save its address once, then log in: ```sh casama config --api-url https://casama.example.com casama login --email ana@example.com ``` `login` asks for your password (or reads `CASAMA_PASSWORD`). If your account has two-step sign-in, it asks for the code from your authenticator app (or takes `--code`, or `CASAMA_2FA_CODE`). With `--magic-link`, it emails you a one-time code and asks you to type it in, instead of using a password. In a script, sign in with a code in two runs: `casama login -e --magic-link --magic-code ` signs in without sending another. Most commands work in one workspace. Set a default so you don't have to pass `--org` every time: ```sh casama org list casama org use acme ``` ### Where settings live | File | What's in it | | --- | --- | | `~/.config/casama/config.json` | The saved `api_url` and the default `org` | | `~/.config/casama/session.json` | Your session (access and refresh tokens), readable only by you | On Windows the folder is `%APPDATA%\casama`. Set `CASAMA_CONFIG_DIR` to use another folder, for example one per server. The CLI refreshes the session itself; `casama logout` deletes it. The API address comes from, in order: `--api`, `CASAMA_API_URL`, the saved `api_url`, and finally `https://api.casama.ai` (Casama Cloud). `casama config` shows the one in use. ## Global options | Option | Meaning | | --- | --- | | `--api ` | API base URL for this command | | `--json` | Print JSON instead of text (see [Scripting](#scripting-with-json)) | | `--version` | Print the CLI's version | | `-h`, `--help` | Help for any command, also `casama help ` | Put global options before the command: `casama --json bot list`. Many commands take `--org` (`-o`): a workspace slug or id. Without it they use the default from `casama org use`. Bots can be named by id or by name (not case-sensitive). ## Commands ### Account and sign-in | Command | What it does | | --- | --- | | `casama config [--api-url ]` | Show the API address and config folder; with `--api-url`, save the address | | `casama signup --email [--password ]` | Create an account. If the server sends a confirmation email, confirm it, then log in. | | `casama login --email [--password ] [--code ] [--magic-link] [--magic-code ]` | Log in. `-e` is short for `--email`. `--code` is the two-step sign-in code; `--magic-code` is the emailed one-time code. | | `casama logout` | Forget the stored session | | `casama whoami` | Your email and your workspaces with your role in each | | `casama pair` | Show a QR code that signs a phone in as you, on the server this CLI points at. It works once, for five minutes. Don't share it: whoever scans it is signed in as you. | | `casama account export [-o ]` | Download everything you can see as a ZIP of JSON files (default `casama-export-.zip`) | | `casama account delete [--confirm ]` | Delete your account and the workspaces you solely own, after a grace period. Asks you to type your email unless you pass `--confirm`. | `--email` can also come from `CASAMA_EMAIL`, and `--password` from `CASAMA_PASSWORD`. `pair` works with any server, Casama Cloud included. If the server only answers on your own computer or network, `pair` says so: a phone somewhere else needs [remote access](#self-hosting-selfhost) first (`casama selfhost remote on`). ### Workspaces: `org` and `invite` | Command | What it does | | --- | --- | | `casama org list` | Your workspaces: slug, name and role | | `casama org create [--slug ]` | Create a workspace; you become its owner | | `casama org use ` | Set the default workspace for other commands | | `casama org invite [--org ] [--role member\|admin]` | Invite someone to the default workspace, or `--org` (role defaults to `member`) | | `casama invite accept ` | Join a workspace with an invite token | When the server has no email provider, `org invite` prints the `casama invite accept ` line to send to the person yourself. ### Model keys: `credential` Model keys are stored in the server's vault and never shown again. `key` is an alias for `credential`. | Command | What it does | | --- | --- | | `casama credential add --provider [--label ] [--key ] [--base-url ]` | Add a key. Prompts for it (or reads `CASAMA_MODEL_KEY`) when `--key` is missing. `--label` defaults to `Default`. | | `casama credential list` | Keys in the workspace: id, provider, label, last 4 characters and test status. A ChatGPT plan shows its account and status instead. | | `casama credential test [--model ]` | Check a key with a one-token call. Exits 1 if it fails. | | `casama credential chatgpt [--reconnect ] [--no-browser]` | Connect your ChatGPT plan in the browser so your bots can run on it instead of an API key. Only you can use the plan. `--no-browser` only prints the link. | | `casama credential remove ` | Delete a key (a ChatGPT sign-in is revoked first) | `add`, `list` and `chatgpt` take `--org`. `--provider` is one of: `openai`, `anthropic`, `google`, `xai`, `openrouter`, `openai_compatible`, `brave_search`, `tavily`, `chatgpt`, `treg`, `google_maps`, `mapbox`. For `openai_compatible`, pass `--base-url` (for example `http://localhost:11434/v1`); the key is optional. Connect `chatgpt` with `credential chatgpt`, not `credential add`. ```sh casama credential add --provider openrouter --label Main casama credential test 3f2a9c1e-7b6d-4e5f-8a9b-0c1d2e3f4a5b ``` ### Bots: `bot` | Command | What it does | | --- | --- | | `casama bot list` | Bots you can use: id, name, status, primary model and visibility | | `casama bot create --credential [options]` | Create a bot | Options for `bot create`: | Option | Meaning | | --- | --- | | `-k`, `--credential ` | Model key for the bot's models (required) | | `-m`, `--model ` | Primary model. Defaults to the server's default for the key's provider, or, when there is none (a ChatGPT plan, a custom endpoint), the first model the key lists. | | `--fallback ` | A fallback model on the same key; repeat for more, in order | | `--cheap-model ` | A cheaper model for summaries, memory and check-ins. Without it, summaries and memory use the provider's small model (falling back to the primary) and check-ins use the primary. | | `--persona ` | Instructions, or `@file.md` to read them from a file | | `--autonomy ` | `ask_always`, `ask_risky` (default) or `autonomous` | | `--private` | Only you can see and use the bot | | `--run-budget ` | Most a single run may spend | | `--daily-budget ` | Most the bot may spend in a day | ```sh casama bot create "Invoicer" --credential 3f2a9c1e-7b6d-4e5f-8a9b-0c1d2e3f4a5b \ --persona @invoicer.md --daily-budget 2 ``` ### Chat: `chat` ```sh casama chat [message] [--conversation ] ``` With a message, `chat` sends it, streams the run and exits. Without one, it starts an interactive chat; an empty line, `/exit` or `/quit` ends it. Each call starts a new conversation and prints its id; pass `-c ` (`--conversation`) to continue one. The reply goes to stdout. Tool steps (`→ tool`, `✓ result`, `✗ error`), memories, skills and the cost summary go to stderr, so you can pipe the answer alone: ```sh casama chat Invoicer "List overdue invoices as CSV" > overdue.csv ``` In a terminal, press Ctrl+C once to cancel the run, twice to quit. (On Windows, Ctrl+C quits the CLI without cancelling the run; use `casama runs cancel`.) ### Runs: `runs` | Command | What it does | | --- | --- | | `casama runs watch [--after ]` | Stream a run's events until it ends, starting after `seq` (default 0) | | `casama runs cancel ` | Cancel a run and the helper runs it started | `runs watch` catches up on events you missed, then follows live, and reconnects by itself if the connection drops. ### Memory: `memory` | Command | What it does | | --- | --- | | `casama memory list [--search ]` | A bot's memories, pinned ones first (marked `*`). `-s` is short for `--search`. | ### Usage: `usage` | Command | What it does | | --- | --- | | `casama usage [--period day\|month]` | Cost and tokens by bot since the start of the day or month (default `month`). Computer time no bot ran shows as its own line. | ### Computers: `computer` Every `computer` command except `status` acts on one computer: `--computer ` (`-c`), or the workspace's team computer when you leave it out. They all take `--org`. | Command | What it does | | --- | --- | | `casama computer status` | Computers in the workspace: id, name, state, profile and last activity | | `casama computer start` | Start the computer, or wake it from sleep | | `casama computer stop` | Save its files to storage and put it to sleep | | `casama computer shell` | Open an interactive terminal in it; type `exit` to leave | | `casama computer files ls [path]` | List a folder | | `casama computer files get [-O ]` | Download a file to stdout, or to a file with `-O` (`--output`) | | `casama computer files put ` | Upload a file | | `casama computer files rm ` | Delete a file | | `casama computer checkpoints` | Undo points, newest first | | `casama computer restore ` | Go back to a checkpoint. This replaces the computer's files. | ```sh casama computer files put ./report.csv data/report.csv casama computer files get data/summary.md -O summary.md ``` See [Computers](/guide/computers) for what a bot's computer is. ### Routines and skills as files: `files` | Command | What it does | | --- | --- | | `casama files export ` | Write the workspace's routines and skills to a folder | | `casama files import [--dry-run]` | Create and update routines and skills from a folder. Exits 1 if any file had an error. | Both are for workspace admins. `import` skips files and folders whose names start with `.` (so `.git` is safe), never deletes anything, and prints `+` for created, `~` for updated and `!` for errors. See [Routines and skills as files](/develop/workspace-files) for the format. ```sh casama files export ./casama-files # edit, commit, review... casama files import ./casama-files --dry-run casama files import ./casama-files ``` ### Self-hosting: `selfhost` `selfhost` wraps the repository's `install.sh` and Docker Compose. Run it from a clone of the repository, or point at one with `--dir ` (or `CASAMA_SELFHOST_DIR`). `--dir` goes right after `selfhost`: `casama selfhost --dir /srv/casama status`. Without either, it uses the current folder. When remote access is on, `up`, `down`, `status` and `logs` include the Casama Link connector (its service is `connector`). | Command | What it does | | --- | --- | | `casama selfhost init [--domain \| --local] [--http-port ] [--with-desktop] [--monitoring]` | Generate secrets, build images and start the stack (runs `install.sh`) | | `casama selfhost up` | Start the stack | | `casama selfhost down` | Stop the stack; data is kept | | `casama selfhost status` | Services and their health (`docker compose ps`) | | `casama selfhost logs [service...] [-f]` | The last 200 log lines (default services: `api` and `worker`); `-f` follows | | `casama selfhost upgrade` | `git pull --ff-only` in the checkout, then rebuild and restart; keeps `.env` and data | | `casama selfhost backup [options]` | Back up the database, its Vault key, computer archives, the Library's files and `.env` to a timestamped folder | | `casama selfhost restore [--identity ]` | Restore a backup. This replaces the current data. | | `casama selfhost remote on [options]` | Give a server on your own computer an address your phone can reach, through Casama Link: no domain, no open ports. Approve a code in a browser; the stack restarts with the address. | | `casama selfhost remote off [-v]` | Back to this computer only. The link and the address are kept for next time. | | `casama selfhost remote status` | The address, whether it answers from outside and, if not, where it stops | | `casama selfhost remote link [options]` | Link a server that has its own domain to Casama Cloud, so its notifications reach the apps from the App Store and Google Play. No address is made. | Options for `remote on` and `remote link`: | Option | Meaning | | --- | --- | | `--name ` | What to call this server in Casama Cloud (default: this machine's name) | | `--relink` | Link again even when this server already has a key | | `--no-browser` | Only print the link; don't try to open a browser | | `-v`, `--verbose` | Show the installer's output while the server restarts | | `--cloud ` | The Casama Cloud address, for a cloud you run yourself (or `CASAMA_CLOUD_URL`) | | `--invites`, `--no-invites` | `remote on` only. Let people you invited make an account while remote access is on, or close sign-ups. Left out: closed for a new address, unchanged for one that is already on. | `remote on` needs the stack running and your own account already on the server: remote access closes sign-ups, and until then the first account to sign up owns the server. Create it first in the app or with `casama signup`. See [Use your server on your phone](/self-hosting/remote-access) for more. `init` options: `--domain` (public domain with automatic HTTPS), `--local` (this machine only, plain HTTP), `--http-port` (default 80), `--with-desktop` (also build the desktop computer image), `--monitoring` (Prometheus and Grafana). `backup` options: | Option | Meaning | | --- | --- | | `--out ` | Where backups go (default `casama-backups`) | | `--encrypt` | Encrypt every file with [age](https://age-encryption.org) | | `--recipient ` | An age public key (`age1...`) or SSH public key to encrypt to; repeat for more. Also read from `CASAMA_BACKUP_RECIPIENTS` (comma-separated). | | `--keep ` | Keep only the newest `n` backups in `--out` | | `--keep-days ` | Remove backups older than `n` days. With `--keep` too, a backup goes only when it's outside both. | Encryption needs the `age` program installed. An encrypted backup needs `--identity` (your age identity file) to restore. A backup without its Vault key restores, but saved secrets (model keys, app sign-ins) have to be entered again unless the new machine already has the original key. See [Operations](/self-hosting/operations) for backup schedules and upgrades. ### Start a project: `init` `init` scaffolds a project for building on Casama, with an `AGENTS.md` that tells your coding agent the format's rules and limits, how to check its work and where the docs are. It works offline and needs no sign-in. | Command | What it makes | | --- | --- | | `casama init plugin [folder]` | An [Agent Plugins 1.0](/develop/plugins) plugin: `plugin.json`, `mcp.json` with a dependency-free Node MCP server in `server/`, a skill in `skills//`, a `README.md` and a GitHub workflow that runs the plugin check | | `casama init skill [folder]` | One [skill](/guide/skills): the folder with a `SKILL.md` named after it | | `casama init bot [folder]` | A [bot template](/develop/bot-templates), `.casama-bot.json`, with a sample skill and routine | | `casama init routine [folder]` | A [routine file](/develop/workspace-files#routine-files), `.md`, for `casama files import` | The folder defaults to the current one, and the name to the folder's name, lowercased with dashes (`My Plugin` becomes `my-plugin`). `--name ` (`-n`) sets it instead: for a plugin or skill it must already be a valid name; for a bot or routine it's the display name, and the file is named after it. `init` never overwrites a file unless you pass `--force`; otherwise it writes nothing and exits 1. It prints the files it wrote and what to do next. ```sh casama init plugin acme-weather cd acme-weather npx @casama/plugin-check . --strict ``` Every `AGENTS.md` points at [llms.txt](https://docs.casama.ai/llms.txt), the `.md` version of the relevant page, Casama's agent kit for Claude Code (`/plugin marketplace add stackwares/casama`, then `/plugin install casama-dev@casama`) and the docs MCP server at `https://api.casama.ai/mcp/docs`. ### Start from the gallery: `init --from-gallery` `casama init --from-gallery bot/ [folder]` writes a gallery starter bot as a [bot template](/develop/bot-templates) (`.casama-bot.json` and an `AGENTS.md`), with every setup question filled in with its default answer. `casama init --from-gallery plugin/ [folder]` copies a reviewed gallery plugin's folder at the exact commit the gallery reviewed, from GitHub. The folder defaults to the item's id. Like the other `init` commands it never overwrites a file unless you pass `--force`. Find ids with `casama gallery search`. ```sh casama init --from-gallery bot/home-organizer casama init --from-gallery plugin/hello-casama my-plugin ``` ### The gallery: `gallery` | Command | What it does | | --- | --- | | `casama gallery search [--type ] [--limit 10]` | Searches the [gallery](https://gallery.casama.ai) for skills, apps, routines, bots, plugins, sets and looks. `--type` (`-t`) can be given more than once: `skill`, `app`, `routine`, `bot`, `plugin`, `set`, `theme`, `scheme`, `wallpaper`. Prints each match's kind and id, description and page. | | `casama gallery mirror [--public-key ] [--json-only]` | Downloads a copy of the gallery for a server without internet: every catalog file, `manifest.json`, `manifest.sig` and each item's files. | `mirror` checks every catalog file against the SHA-256 in `manifest.json`, and each item's files against the hash in its catalog record, before it writes anything. With a public key (`--public-key`, or `CASAMA_GALLERY_PUBLIC_KEY`) it also checks `manifest.sig`, the catalog's Ed25519 signature, and refuses a missing or wrong one. Without a key it says the copy isn't signature-checked. `--json-only` skips the item files. Serve the folder over HTTP and set the server's `GALLERY_URL` to its address (see [Configuration](/self-hosting/configuration)). ```sh casama gallery search "summarize unread email" --type skill --type routine casama gallery mirror ./gallery-copy --public-key "$GALLERY_PUBLIC_KEY" ``` Both commands need no sign-in. `--gallery ` (or `CASAMA_GALLERY_URL`) points them, and `init --from-gallery`, at another catalog laid out the same way. ## Scripting with JSON With `--json`, a command prints its result as JSON on stdout, usually the API's own response body: ```sh casama --json bot list | jq -r '.items[] | select(.status == "idle") | .name' ``` - `chat` and `runs watch` print one run event envelope per line (JSON Lines), the same shape as the [HTTP API's events](/develop/api#the-event-envelope): ```sh casama --json chat Invoicer "Summarize this week" | jq -rj 'select(.type == "message.delta") | .payload.text' ``` - Errors go to stderr as `{"error": "", "message": "..."}`. The code is the API's problem code when there is one (`forbidden`, `run_finished`, ...), or one of the CLI's own: `not_logged_in`, `org_required`, `org_not_found`, `bot_not_found`, `no_computer`, `auth_failed`, `two_step_failed`, `network_error`. `selfhost` adds `not_a_checkout`, `backup_failed`, `identity_required`, `not_a_backup`, `restore_failed`, `not_running` and `no_account`, and `selfhost remote` passes on Casama Cloud's codes (`plan_limit`, `suspended`, `link_expired`, `unreachable`, ...). `init` adds `file_exists`. `gallery` and `init --from-gallery` add `gallery_unavailable`, `gallery_item_not_found`, `gallery_item_retired`, `manifest_invalid`, `hash_mismatch`, `signature_missing`, `signature_invalid`, `plugin_source` and `plugin_too_big`. - Prompts (password, two-step code) read environment variables first, so scripts never wait on input: `CASAMA_EMAIL`, `CASAMA_PASSWORD`, `CASAMA_2FA_CODE`, `CASAMA_MODEL_KEY`. ### Environment variables | Variable | Used for | | --- | --- | | `CASAMA_API_URL` | API address, when `--api` isn't given | | `CASAMA_CONFIG_DIR` | Config folder instead of `~/.config/casama` | | `CASAMA_EMAIL` | `--email` for `login` and `signup` | | `CASAMA_PASSWORD` | Password for `login` and `signup` | | `CASAMA_2FA_CODE` | Two-step sign-in code for `login` | | `CASAMA_MODEL_KEY` | Key for `credential add` | | `CASAMA_SELFHOST_DIR` | Checkout for `selfhost` | | `CASAMA_BACKUP_RECIPIENTS` | age recipients for `selfhost backup --encrypt` | | `CASAMA_CLOUD_URL` | Casama Cloud address for `selfhost remote`, when `--cloud` isn't given | | `CASAMA_GALLERY_URL` | Gallery address for `gallery` and `init --from-gallery`, when `--gallery` isn't given | | `CASAMA_GALLERY_PUBLIC_KEY` | Public key `gallery mirror` checks `manifest.sig` with, when `--public-key` isn't given | ## Exit codes | Code | Meaning | | --- | --- | | 0 | Success | | 1 | An error (printed to stderr), a run that failed (`chat`, `runs watch`), a failing key (`credential test`), or files with errors (`files import`) | | 64 | Wrong usage: a missing argument or unknown option | | 130 | You pressed Ctrl+C twice during a run | Most `selfhost` commands exit with the code of the program they ran (`docker`, `git`, `install.sh`). ## Related - [HTTP API](/develop/api): what the CLI calls - [Dart SDK](/develop/sdk): the library the CLI is built on - [Routines and skills as files](/develop/workspace-files) - [Self-hosting](/self-hosting/) - [Computers](/guide/computers) # Contribute to Casama Casama is open source, and bug reports, docs fixes, tests and features are all welcome. This page gets a development machine running, shows how to run every test suite, and explains how to send a change. For a map of the code, read [How Casama is built](/develop/architecture) first. - Found a bug? [Open an issue](https://github.com/stackwares/casama/issues/new/choose) with steps to reproduce it. - Planning a large change? Start a [discussion](https://github.com/stackwares/casama/discussions) first, so you agree on the approach before you write it. - Found a security issue? Don't open an issue. Follow [SECURITY.md](https://github.com/stackwares/casama/blob/main/SECURITY.md). ## What you need | Tool | Version | Used for | | ------------------------------------- | -------------------------------- | ------------------------------------------- | | Node.js | 24 or newer (see `.nvmrc`) | The API, worker, supervisor and packages | | pnpm | 12 (`packageManager` in `package.json`) | JavaScript dependencies | | Docker | recent | Supabase, computers, the self-host stack | | Supabase CLI | recent | Local Postgres, Auth, Realtime and Storage | | Dart | 3 (stable) | The CLI, SDK and `computerd` | | Flutter | 3.50 | The app | | PostgreSQL 17 with pgvector and pgTAP | 17 | Tests start a throwaway database from it | On macOS: ```sh brew install node pnpm supabase/tap/supabase postgresql@17 pgvector pgtap ``` Then install Docker Desktop and Flutter. ## Run the backend Clone the repository, install dependencies and start Supabase: ```sh git clone https://github.com/stackwares/casama.git cd casama pnpm install supabase start # Postgres on :54322, the Supabase API on :54321, Studio on :54323 cp .env.example .env ``` Fill in `.env` from the output of `supabase status`: the API needs at least `DATABASE_URL`, `SUPABASE_URL` and `SUPABASE_ANON_KEY`. The comments in `.env.example` explain every setting. Start the API and the worker, each in its own terminal: ```sh pnpm --filter @casama/server dev # the API on http://localhost:8787 pnpm --filter @casama/server dev:worker # the worker ``` Node.js runs the TypeScript directly, so there's no build step, and both restart when you save a file. The API serves its reference at `http://localhost:8787/docs`, and `curl http://localhost:8787/readyz` tells you it's up. **No model key?** Set `CASAMA_MODEL_FIXTURES=apps/server/test/fixtures/chat.json` in `.env`, and the worker replays recorded model answers instead of calling a provider. **Computers** need the supervisor, the egress proxy, the TURN relay and the computer images. Run them next to Supabase: ```sh docker compose -f infra/compose/docker-compose.dev.yml up --build ``` On a Mac, `scripts/dev-up.sh` does all of this in one command: it starts Docker and Supabase, builds the computer images on first run, starts the computer services, then runs the API and worker until you press Ctrl-C. `scripts/dev-up.sh --down` stops Supabase and the computer services too. ## Run the app ```sh cd client flutter run -d macos --dart-define=CASAMA_API_URL=http://localhost:8787 ``` Use `-d chrome`, an iOS simulator or an Android emulator instead of `macos` if you prefer. The app gets the Supabase address and key from the API, so the API address is the only setting. On a physical phone, `localhost` is the phone itself. Give the app an address that reaches your computer instead: an https tunnel, `adb reverse tcp:8787 tcp:8787` for an Android phone on USB, or your computer's LAN address (iOS blocks plain http unless you allow it). The `SUPABASE_URL` in your `.env` must be reachable from the phone too, because the app signs in there. ## Run the CLI ```sh cd dart/cli dart run bin/casama.dart config --api-url http://localhost:8787 dart run bin/casama.dart signup --email you@example.com dart run bin/casama.dart org create "My team" dart run bin/casama.dart org use my-team dart run bin/casama.dart credential add --provider openrouter dart run bin/casama.dart bot create Ada --credential dart run bin/casama.dart chat Ada "What can you do?" ``` See [CLI](/develop/cli) for every command. ## Run the docs ```sh pnpm --filter @casama/docs dev # http://localhost:5173 pnpm --filter @casama/docs build # fails on broken links ``` ## Run the tests Run everything that applies to your change before you push. CI runs all of it. ```sh pnpm lint # Biome pnpm typecheck # TypeScript, every package pnpm test # unit and API tests, every package pnpm --filter @casama/db test:pgtap # row-level security tests in supabase/tests pnpm gen && git diff --exit-code # generated code is up to date (cd dart && dart pub get && dart analyze && dart test cli casama_sdk) (cd client && flutter pub get && flutter gen-l10n && flutter analyze && flutter test) ``` Some things to know: - **Tests start their own Postgres.** Server and database tests start a throwaway cluster from your PostgreSQL 17 binaries and apply every migration. They look in Homebrew's `postgresql@17` folder; set `PG_BIN` if yours is elsewhere, or set `TEST_DATABASE_URL` to use a database you already run. On macOS, set `LC_ALL=en_US.UTF-8` if Postgres refuses to start. - **No test calls a real model.** Model calls replay recorded fixtures. `scripts/live-check.sh` runs the few live checks against a real model with your own key. - **Computer tests need Docker.** The sandbox and computer tests, `dart test computerd`, and the CLI end-to-end run (`scripts/e2e-cli.sh`) need the computer images built. - **The web build** in CI is `scripts/build-web.sh`. ## Rules for every change 1. **Contracts first.** Change routes and schemas in `packages/contracts`, run `pnpm gen`, then implement. Never hand-write duplicate types or edit the generated Dart client. 2. **Database changes only through migrations** in `supabase/migrations`. Turn on row-level security for every new table in the same migration, add pgTAP tests in `supabase/tests`, and grant the worker access with `public.allow_worker` if it needs the table. 3. **No secrets** in code, logs, prompts, fixtures or test output. 4. **Tests with every change.** If a test fails, fix the cause; don't skip the test. 5. **Text in the app** goes in `client/lib/l10n/app_en.arb`. 6. **New dependencies** at their latest compatible version, listed in `THIRD_PARTY_NOTICES.md`. Put upgrades in their own commit. 7. **Docs change with the behavior** they describe. User docs live in `docs-site/`. 8. **Format only what you touch.** Run `npx biome check --write ` on TypeScript you changed and `dart format ` on Dart you changed. Don't reformat whole folders. ## How decisions are recorded `docs/DECISIONS.md` is the decision log. Each entry has a number (`D-001` onward), what was decided and why. When your change makes a choice the code doesn't explain by itself, add a short entry. Before you change a behavior that looks deliberate, search the log for it; there's usually a reason, and the entry tells you what to weigh. `docs/ARCHITECTURE.md` maps each feature to the files behind it. Update it when you add a feature or move one. ## Send a change 1. Fork the repository and create a branch from `main`. 2. Make your change in small, focused commits, with tests. 3. Sign off every commit: ```sh git commit -s -m "Add bot budget checks" ``` This adds a `Signed-off-by` line certifying the [Developer Certificate of Origin](https://developercertificate.org/): that you wrote the change or have the right to submit it. Casama uses the DCO instead of a contributor license agreement. 4. Open a pull request and fill in the template: what changed, why, and how you tested it. A maintainer reviews it, usually within a few days. Small pull requests get reviewed fastest. ## Licenses Everything in the repository is Apache-2.0, except the `ee/` folder, which is under the Casama Enterprise License: you can read it and try it, and production use needs a license key. By contributing, you agree your contribution is licensed under Apache-2.0, or under the Casama Enterprise License for changes inside `ee/`. # Gallery catalog format The [gallery](https://gallery.casama.ai) is a folder of items that anyone can add to by pull request to [stackwares/casama-gallery](https://github.com/stackwares/casama-gallery). A checker turns the folders into a few JSON files that Casama servers, the app and the web gallery read. This page describes the folders, every `item.json` field, skill tests, starter sets and the files the checker writes. Any folder laid out the same way is a valid catalog, so you can run your own. ## Folders Each item is a folder named by its id (lowercase letters, digits and dashes): | Kind | Folder | Files next to `item.json` | Licenses | | --- | --- | --- | --- | | Theme | `themes//` | `theme.json` | CC0-1.0, CC-BY-4.0 | | Color scheme | `schemes//` | `scheme.json` | CC0-1.0, CC-BY-4.0 | | Wallpaper | `wallpapers//` | `wallpaper.json`, its image | CC0-1.0, CC-BY-4.0 | | Skill | `skills//` | `SKILL.md`, any files it uses, optional `tests.json` | MIT, Apache-2.0 | | App | `apps//` | `app.json`, optional `logo.svg` | CC0-1.0 | | Starter bot | `bots//` | `bot.json` | MIT, Apache-2.0, CC0-1.0, CC-BY-4.0 | | Routine idea | `routines//` | `routine.json` | MIT, Apache-2.0, CC0-1.0, CC-BY-4.0 | | Plugin | `plugins//` | `plugin.json` | CC0-1.0 | | Starter set | `sets//` | `set.json` | CC0-1.0, CC-BY-4.0 | The documents for each kind (`theme.json`, `app.json`, `bot.json` and the rest) are described in the catalog's [README](https://github.com/stackwares/casama-gallery#readme). ## item.json ```json { "name": "Morning plan", "author": { "name": "Casama", "url": "https://casama.ai", "handle": "casama" }, "license": "Apache-2.0", "tags": ["planning", "calendar"], "featured": true, "pick": "Five lines each morning: meetings, deadlines, weather, and where to start.", "version": 1, "added": "2026-11-13", "access": { "reads": ["calendar", "tickets", "memory", "the web"], "credits": "low" }, "inputs": [ { "key": "time", "label": "What time should it arrive?", "type": "time", "default": "07:30" }, { "key": "city", "label": "Your city, for the weather", "type": "text", "default": "my city" } ] } ``` | Field | Shape | Rule | | --- | --- | --- | | `name` | string | 1 to 60 characters. | | `author` | `{ name, url?, handle? }` | `name` up to 80 characters, `url` https. `handle` (`[a-z0-9-]`, up to 39) groups the author's items on one author page; without it, items group by a slug of the name. | | `license` | string | One of the kind's licenses above. | | `tags` | string[] | Up to 8, each `[a-z0-9-]` up to 24 characters. | | `category`, `icon` | string | A skill's catalog category (required for skills) and a Lucide icon name. | | `featured` | boolean | Shown as a pick. | | `pick` | string | Up to 140 characters: why it's a pick. Only with `featured: true`. | | `retired` | boolean | Hidden from lists; people who added it keep it. | | `replaced_by` | `{ type, id }` | For a retired item, what to use instead. Must exist. | | `version` | integer | Starts at 1. Raise it when the item changes in a way people should update to. | | `added` | `YYYY-MM-DD` | **Required.** The day it joined the gallery. | | `updated` | `YYYY-MM-DD` | Optional. Defaults to the newest changelog date, else `added`. | | `changelog` | `[{ version, date, note, breaking? }]` | Newest first, versions going down, the top one equal to `version`. Required once `version` is above 1. `note` up to 160 characters. `breaking: true` makes the app ask before updating. | | `examples` | string[] | 1 to 3 prompts up to 160 characters people can try. Skills, apps and bots. | | `access` | object | What the item can touch. Skills, apps, routines, bots and plugins. See below. | | `needs` | `{ apps?, skills? }` | What a routine or bot needs first. See below. | | `inputs` | question[] | Up to 6 questions asked when a routine or bot is added. See below. | | `remix_of` | `{ type, id }` | The gallery item it's based on. Must exist. | | `min_app`, `min_server` | `x.y.z` | Lowest app or server version that can use it. Older apps hide it; older servers leave it out. | | `season` | `{ from: "MM-DD", to: "MM-DD" }` | Shown in the seasonal row between these days. May wrap the year end (`12-01` to `01-06`). | ### access ```json "access": { "reads": ["email", "calendar"], "writes": ["sends email"], "runs_code": false, "computer": false, "credits": "low" } ``` - `reads` and `writes`: up to 8 plain phrases of at most 40 characters each, written for the person adding it ("files you share", "creates and edits Word files"). - `runs_code` and `computer`: whether it runs code and needs the bot's computer. A skill that brings scripts (`.py`, `.sh`, `.js` and similar files) always gets both, and saying `false` is an error. - `credits`: `none`, `low`, `medium` or `high`, a rough guide to what a run costs. When an update grows `access` (a new read or write, or code where there was none), the app shows the difference and asks before updating. ### needs ```json "needs": { "apps": ["google_calendar"], "skills": ["meeting-notes"] } ``` `apps` are gallery app ids or built-in app ids (`gmail`, `google_calendar`, `slack`, `github` and the rest). `skills` are gallery skill ids. Installing the item installs the skills too, and walks the person through connecting each app. ### inputs Questions asked when a routine or bot is added. Each answer fills `{{key}}` in a routine's `instructions_md` or a bot's `persona` and `starters`. | Field | Rule | | --- | --- | | `key` | `^[a-z][a-z0-9_]{0,31}$`, unique. | | `label` | 1 to 60 characters. | | `type` | `text`, `choice`, `time` (`HH:MM`, 24-hour) or `timezone` (`Europe/Berlin`, `UTC`). | | `options` | `choice` only: 2 to 8 options of at most 60 characters. | | `default` | Required, 1 to 120 characters, fitting the type. The form starts with it, and servers from before inputs use it. | | `help` | Optional, up to 120 characters. | A `time` input named `time` can also set a routine's schedule: ```json "schedule_cron": "{{time.minute}} {{time.hour}} * * 1-5" ``` Every placeholder needs an input, and every input has to be used. Answers can't contain `{` or `}`. ## Skill tests A skill folder may hold `tests.json` with 1 to 5 cases: ```json { "cases": [ { "prompt": "Proofread this: 'Their going to the meeting tomorow.'", "expect": "Fixes they're and tomorrow, keeps the meaning and voice, and lists what changed." } ] } ``` `prompt` is up to 500 characters and `expect`, a plain-words rubric, up to 300. The file is part of the skill like any other. In the Casama repo, `node scripts/gallery-skill-tests.mts` runs each prompt with the skill loaded and has a model check the answer against `expect` (it needs `OPENROUTER_API_KEY`; `GALLERY_TEST_MODEL` and `GALLERY_JUDGE_MODEL` pick the models). It writes `tested.json`: ```json { "proofread": { "version": 1, "passed": true, "date": "2026-11-16" } } ``` A skill that passed on its current version gets `tested: { version, date }` in its record, which the app shows as **Reviewed**. ## Starter sets `sets//set.json` bundles items people often add together: ```json { "description": "Decide, plan and report without a chief of staff.", "icon": "rocket", "items": [ { "type": "skill", "id": "decision-memo" }, { "type": "routine", "id": "weekly-review" }, { "type": "app", "id": "todoist" } ] } ``` `description` up to 200 characters, `icon` a Lucide name, and 2 to 12 items of type `app`, `skill`, `routine`, `bot`, `theme`, `scheme`, `wallpaper` or `plugin`. Each must be in the gallery and not retired. ## Files the checker writes ```sh node check.mjs # write the files node check.mjs --check # fail when an item is wrong or a file is out of date ``` | File | Holds | | --- | --- | | `index.json` | Themes, color schemes, wallpapers and skills. | | `apps.json`, `bots.json`, `routines.json`, `plugins.json`, `sets.json` | The other kinds, one file each. | | `authors.json` | `{ schema: 1, authors: [{ handle, name, url?, items: [{ type, id }] }] }`. | | `manifest.json` | `{ schema: 1, created, files: { "": "" } }` over every file above. `created` is the newest `updated` date in the catalog. | | `manifest.sig` | Written in CI by `node sign.mjs`, never committed. | `index.json` only ever holds the four original types, because apps and servers from before the other kinds can't read them; every new kind gets its own file. Every list file is `{ "schema": 1, "items": [...] }`, and each record looks like this: ```json { "id": "morning-plan", "type": "routine", "name": "Morning plan", "author": { "name": "Casama", "url": "https://casama.ai", "handle": "casama" }, "license": "Apache-2.0", "tags": ["planning", "calendar"], "featured": true, "retired": false, "version": 1, "added": "2026-11-13", "updated": "2026-11-13", "sha256": "…", "size": 1343, "description": "Each weekday morning: today's meetings, deadlines and the one thing to get done first.", "pick": "Five lines each morning: meetings, deadlines, weather, and where to start.", "access": { "reads": ["calendar", "tickets", "memory", "the web"], "credits": "low" }, "inputs": [{ "key": "time", "label": "What time should it arrive?", "type": "time", "default": "07:30" }], "document": { "instructions_md": "… today's weather in my city …", "schedule_cron": "30 7 * * 1-5" }, "template": { "instructions_md": "… today's weather in {{city}} …", "schedule_cron": "{{time.minute}} {{time.hour}} * * 1-5" }, "files": ["routines/morning-plan/item.json", "routines/morning-plan/routine.json"] } ``` Fields appear only when the item has them: `category`, `icon`, `description`, `requires` (what a look needs from the app), `changelog`, `pick`, `examples`, `access`, `needs`, `inputs`, `remix_of`, `replaced_by`, `min_app`, `min_server`, `season` and `tested`. `document` is what a card or install needs without another request; for a routine or bot with inputs it has the defaults filled in, and `template` keeps the fields with their placeholders. `sha256` covers every file in the folder (sorted path, length and bytes), and installs check it. ## Signing A Casama server checks `manifest.sig`, a base64 Ed25519 signature over the exact bytes of `manifest.json`, with the catalog's public key, then checks each JSON file it reads against the hashes in the manifest. To sign your own catalog: ```sh node sign.mjs --gen-key # prints a private key (PEM) and a public key GALLERY_SIGNING_KEY="$(cat key.pem)" node sign.mjs # writes manifest.sig node sign.mjs --verify # checks it ``` `GALLERY_SIGNING_KEY` is a PKCS8 PEM or a base64 raw 32-byte seed; the public key is the base64 raw 32 bytes. Keep the private key in your CI's secrets, never in the repository. ## Related - [Bot template format](/develop/bot-templates) - [Plugins](/develop/plugins) - [Build with AI agents](/develop/agents): the `casama-gallery` skill adds items for you # Plugins A plugin gives a bot new skills and new tools in one install. Casama reads the open [Agent Plugins 1.0](https://agent-plugins.org) format, so a plugin is a folder on GitHub with a `plugin.json`, and optionally an `mcp.json` (tool servers) and a `skills/` folder. A plugin written for another app that reads the format works in Casama too. People install a plugin by pasting its GitHub link in a bot's settings, under **Plugins**. They see what it adds before anything runs, and Casama installs exactly the commit they reviewed. The quickest start is the example, [`examples/hello-plugin`](https://github.com/stackwares/casama/tree/main/examples/hello-plugin): a stand-up skill plus a small notes server with one secret. ## What's in a plugin ```text my-plugin/ ├── plugin.json required: name, version, description, secrets ├── mcp.json optional: MCP tool servers ├── skills/ │ └── weekly-report/ │ ├── SKILL.md one folder per skill │ └── template.md files the skill uses └── server/ └── notes.mjs code for a server that runs on the bot's computer ``` ### plugin.json ```json { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "hello-casama", "version": "1.0.0", "description": "A stand-up skill and a notes server.", "author": { "name": "Ana Cruz", "url": "https://example.com" }, "repository": "https://github.com/you/hello-casama", "license": "MIT", "keywords": ["notes"] } ``` - `$schema` must be the 1.0.0 address above. Other versions are refused. - `name`: lowercase letters, digits, dots and dashes, up to 64 characters, starting and ending with a letter or digit, with no `--` or `..`. It can't change between versions: an update with a new name is refused. - `version`, `description`, `homepage`, `repository` and `license` are strings; `keywords` is a list of strings; `author` has only `name`, `email` and `url`. - Other top-level fields are ignored, with a warning. Put app-specific settings under `extensions`. ### Skills Each immediate folder of `skills/` that holds a `SKILL.md` is a skill, in the open [Agent Skills](https://agentskills.io) layout: ```markdown --- name: weekly-report description: Turn the week's notes into a one-page report. --- 1. Read the notes with `list_notes` and `read_note`... ``` - `name`: lowercase letters, digits, `-` and `_`, up to 63 characters. Use the folder's name. - `description` is required; Casama keeps the first 300 characters. The bot sees it when choosing a skill, so say when to use it. - The skill's other files go with it to the bot's computer (`~/skills//`), keeping the executable bit. Up to 60 files, 1 MB each and 5 MB in all, with names made of letters, digits, `.`, `_`, `-` and `/`. - A broken skill is skipped with a warning; the rest of the plugin still installs. ### MCP servers (mcp.json) ```json { "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", "mcpServers": { "notes": { "type": "stdio", "command": "node", "args": ["${PLUGIN_ROOT}/server/notes.mjs"], "env": { "NOTES_DIR": "${PLUGIN_DATA}/notes" } }, "search": { "type": "streamable-http", "url": "https://mcp.example.com/mcp" } } } ``` Two kinds of server: | Kind | Where it runs | Fields | | --- | --- | --- | | `stdio` | Inside the bot's computer, started by Casama | `command`, `args`, `env`, `cwd` | | `streamable-http` or `sse` | Your own server, called by Casama | `url`, `headers` | Rules for `stdio` servers: - `command` is one program (`node`, `python3`) or a path inside the plugin starting with `./` (`./bin/server`). No shell lines, no spaces. - `${PLUGIN_ROOT}` (where the plugin's files are) and `${PLUGIN_DATA}` (a folder that survives updates) are filled in, in `args`, `env` values and `cwd` only. The server also gets them as the `PLUGIN_ROOT` and `PLUGIN_DATA` environment variables; `env` can't set those two itself. - `cwd` stays inside the plugin or its data folder. Without one, the server starts in `PLUGIN_ROOT`. Rules for remote servers: - `url` uses https (plain http only for `localhost`, `127.x` and `::1`), with no user name, password or `#fragment`. - Header names must be valid and not repeated. A server with any other field, or one that breaks a rule, is skipped with a warning. A broken `mcp.json` (not JSON, another `$schema`, no `mcpServers`, or another top-level field) turns off only the plugin's servers; its skills still install. ## Secrets The format has no way to declare secrets, and it forbids putting them in `env` or `headers`. Casama adds one, under its own extension: ```json { "extensions": { "com.casama": { "secrets": [ { "name": "NOTES_SIGNATURE", "description": "A line added to every saved note.", "server": "notes", "env": "NOTES_SIGNATURE" }, { "name": "SEARCH_API_KEY", "description": "Your key from example.com/settings/keys.", "server": "search", "header": "Authorization", "format": "Bearer {{value}}" } ] } } } ``` - `name`: uppercase letters, digits and `_`, starting with a letter, up to 64 characters. - `server`: the key of a server in `mcp.json`. - For a `stdio` server, `env` names the environment variable the value goes in. For a remote server, `header` names the header, and `format` (optional, must contain `{{value}}`) shapes it. - `description` is shown to the person installing (first 300 characters). Say where to get the value. - A secret without a valid `name`, a known `server`, or the `env` or `header` its server needs is ignored with a warning. The person installing is asked for every secret before install. Values are stored in Casama's vault, never in the plugin's settings and never shown to the model, and they carry over to updates. ## The bot's computer `stdio` servers run inside the bot's sandboxed Linux computer, never on Casama's servers. Write them for this environment: - **Ubuntu 24.04** with **Node.js 24**, **Python 3** (with `pip` and `venv`), bash, git, curl, jq and ripgrep, plus Chromium and Playwright. Anything else, ship inside the plugin. - Runs as an unprivileged user (`casama`). The home folder is the only lasting, writable place, plus `/tmp`. Your files are at `~/.casama/plugins//` and your data at `~/.casama/plugin-data//`. - **Nothing is installed for you.** Casama copies the plugin's files; it doesn't run `npm install` or `pip install`. Bundle your server into one file (for Node, `esbuild --bundle --platform=node`) or commit what it needs. `npx` works, but downloads the package on first start, and the server has **30 seconds** to answer `initialize`. - **Network** goes through an egress proxy that blocks private and cloud-metadata addresses. A plugin's local servers can't reach private networks, by design. - The computer sleeps after 5 idle minutes by default (people can choose 15, 30 or 60), and an idle server is stopped after 10 minutes; Casama starts it again on the next call. Keep state in `PLUGIN_DATA`, not in memory. - Write logs to stderr. stdout is the MCP channel (one JSON-RPC message per line). - Mark executable files executable in git (`git update-index --chmod=+x bin/server`), or start them with `node` or `python3`. ## Tools and approvals Casama lists each server's tools at install (it starts the bot's computer to list `stdio` tools) and again on every update. Each tool's risk comes from its MCP annotations: | Annotation | Risk | | --- | --- | | `readOnlyHint: true` | low | | `destructiveHint: true` | high | | neither | medium | The bot's autonomy setting decides which risks need someone's approval first (see [Autonomy and approvals](/guide/autonomy)), and people can change any tool's risk, as with any connection. Annotate honestly: a read-only tool that runs without asking makes a plugin pleasant to use. ## Check your plugin `casama-plugin-check` runs the same checks Casama runs at install, and adds tips for things that install fine but would fail on the bot's computer (a missing file, a program the image doesn't have, a script that isn't executable, files you haven't committed). On GitHub, add it to your plugin's workflow: ```yaml # .github/workflows/check.yml name: Check plugin on: [push, pull_request] jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: stackwares/casama/.github/actions/plugin-check@main with: path: . # the plugin folder ``` It fails when Casama would refuse the plugin, and (with the default `strict: true`) when it would skip or ignore anything. Locally (Node 20+): ```sh npx @casama/plugin-check ../my-plugin ``` Coding agents can run the same check through the `check_plugin` tool of the [Casama MCP server](/guide/mcp#docs-tools-for-building-on-casama). Add `--json` for the result as JSON, and `--strict` to also fail when Casama would skip or ignore something, as the GitHub Action does by default. ## Publish and install 1. Push the plugin to a **public** GitHub repository. It can be the whole repository or one folder in it. 2. Share the link: `https://github.com/you/my-plugin`, or a folder or branch with `https://github.com/you/repo/tree/main/plugins/my-plugin`. 3. In Casama, open the bot's settings → **Plugins** → **Add a plugin**, and paste the link. Casama shows the skills, each server's command or address, the hosts it talks to, the secrets it needs and any warnings, then installs that exact commit. **The plugin directory:** a bot's **Add a plugin** sheet also lists **Reviewed plugins** from the [open gallery](https://gallery.casama.ai/#plugin). To list yours, open a pull request to [stackwares/casama-gallery](https://github.com/stackwares/casama-gallery) with `plugins//plugin.json` naming the repository folder and the exact commit to review. People who add it from the directory get that commit; a newer version is another pull request that changes `commit`. A bot can also suggest a plugin in chat. The card opens the same install sheet, so the person still sees what it adds and enters its secrets. **Updates:** push a new commit. People press **Check for update** on the plugin's page and see what changed (skills and servers added, changed or removed, new hosts, new secrets) before updating. Tag releases and keep `version` current so the change is easy to read. **Uninstall** removes the plugin's skills, files, servers and secrets. ### Install with the API The app's steps map to the [HTTP API](/develop/api), which is handy for testing a plugin from a script. Preview first; the preview names the commit to install: ```sh curl -s -X POST "https://casama.example.com/v1/plugins/preview" \ -H "authorization: Bearer $TOKEN" -H "content-type: application/json" \ -d '{"org_id": "'"$ORG"'", "url": "https://github.com/you/my-plugin"}' ``` The response lists `name`, `version`, `description`, `repo`, `path`, `commit`, `skills`, `servers`, `secrets`, `hosts` and `warnings`. Install that commit for a bot, with a value for each secret: ```sh curl -s -X POST "https://casama.example.com/v1/plugins" \ -H "authorization: Bearer $TOKEN" -H "content-type: application/json" \ -d '{"org_id": "'"$ORG"'", "bot_id": "'"$BOT"'", "url": "https://github.com/you/my-plugin", "commit": "<40-character commit from the preview>", "secrets": {"NOTES_SIGNATURE": "Ana"}}' ``` | Endpoint | What it does | | --- | --- | | `GET /v1/plugin-directory` | The reviewed plugins from the gallery, each with its pinned commit | | `POST /v1/plugins/preview` | What a plugin at a GitHub URL would add, at the latest commit or the `commit` you pass | | `POST /v1/plugins` | Install it for a bot, pinned to a commit | | `GET /v1/plugins?bot_id=...` | A bot's plugins, with each server's status and tools | | `GET /v1/plugins/{id}/update` | The latest commit and what would change | | `POST /v1/plugins/{id}/update` | Update to a commit (`commit`, plus `secrets` for new ones) | | `DELETE /v1/plugins/{id}` | Uninstall | ## Limits - Up to 400 files and 10 MB per plugin. Symlinks are left out. - Public GitHub repositories only. - Plugins are installed per bot, not for a whole workspace. - `stdio` servers run on the bot's computer; running them on a person's own computer through the desktop companion isn't supported yet. ## Related - [Skills](/guide/skills) - [Hosted MCP](/guide/mcp) - [Computers](/guide/computers): the environment `stdio` servers run in - [Autonomy and approvals](/guide/autonomy) - [Connections](/guide/connections) # Dart SDK `casama_sdk` is the Dart and Flutter library for Casama. It gives you a typed client for the whole [HTTP API](/develop/api), sign-in with automatic token refresh, and `watchRun`, which streams a bot's run live and recovers from dropped connections. The [CLI](/develop/cli) is built on it. The typed client comes from a separate package, `casama_api`, generated from the API's OpenAPI document. `casama_sdk` re-exports it, so one import gives you everything. ## Install ```yaml # pubspec.yaml dependencies: casama_sdk: ^0.1.0 ``` ```sh dart pub get ``` It needs Dart 3.13 or later. Keep the SDK's version in step with your server's `api_version` (from `GET /v1/config`): the client is generated from that server version's routes. ::: details Using a clone of the repository instead To build against unreleased changes, point both packages at a clone with `dependency_overrides`, as the sample app does: ```yaml dependency_overrides: casama_sdk: path: ../casama/dart/casama_sdk casama_api: path: ../casama/dart/casama_api ``` ::: ## Connect and sign in ```dart import 'package:casama_sdk/casama_sdk.dart'; Future main() async { final casama = await CasamaClient.connect('https://casama.example.com'); await casama.signIn('ana@example.com', 'correct-horse-battery'); final me = (await casama.workspaces.getMe()).data!; print('Signed in as ${me.email}'); } ``` `CasamaClient.connect` loads the server's [public configuration](/develop/api#public-configuration) (`casama.config`), which says where to sign in. After that, every API call carries your access token, and the client refreshes it a minute before it expires. | Member | What it does | | --- | --- | | `CasamaClient.connect(url, {sessions, config})` | Connect to a server. Pass `config` if you already have it to save a request. | | `signIn(email, password)` | Sign in with email and password; returns an `AuthSession` | | `signUp(email, password)` | Create an account. Returns `null` when the server sends a confirmation email first. Adds a sign-up proof when the server asks for one. | | `signOut()` | Forget the session | | `currentSession()` | The session, refreshed if it's about to expire, or `null` | | `config` | The server's `PublicConfig`: `productName`, `apiVersion`, `defaultModels`, `billingEnabled`, ... | | `auth` | The lower-level `AuthClient`: magic-link codes (`sendMagicLink`, `verifyEmailOtp`), two-step sign-in (`verifiedTotpFactors`, `verifyTotp`), `refresh` | | `api` | The generated `CasamaApi`, and `api.dio` for raw requests | ### Keep the session By default the session lives in memory, so your program signs in each time it starts. Pass a `SessionStore` to keep it: ```dart class FileStore implements SessionStore { FileStore(this.file); final File file; @override Future load() async => file.existsSync() ? AuthSession.fromAuthResponse(jsonDecode(file.readAsStringSync())) : null; @override Future save(AuthSession s) async => file.writeAsStringSync(jsonEncode(s.toJson())); @override Future clear() async { if (file.existsSync()) file.deleteSync(); } } final casama = await CasamaClient.connect(url, sessions: FileStore(File('session.json'))); ``` The SDK also has `MemorySessionStore` (the default) and `CallbackSessionStore`, which reads the session from another auth library. A Flutter app that already uses `supabase_flutter` can hand its session over this way and let that library refresh it. ## Workspaces and bots The client has one property per API area, named after the reference's tags: `workspaces`, `bots`, `chat`, `runs`, `credentials`, `approvals`, `memory`, `routines`, `skills`, `projects`, `files`, `computers`, `integrations`, `usage`, `billing`, `privacy` and more. A few names differ from their tag: `signInCodes` (the `auth` tag, scan-to-sign-in codes), `casamaLink` (`casama-link`), `imports` (`import`) and `localComputer` (`local computer`). Areas without a property, such as `webhooks` and `gallery`, are on the generated client: `casama.api.getWebhooksApi()`. Each method returns a Dio `Response`; the parsed body is in `.data`. ```dart final orgs = (await casama.workspaces.listOrgs()).data!.items; final org = orgs.firstWhere((o) => o.slug == 'acme'); final bots = (await casama.bots.listBots(orgId: org.id)).data!.items; for (final b in bots) { print('${b.name}: ${b.status.value}'); } ``` Create a bot with a model key: ```dart final key = (await casama.credentials.createCredential( createCredentialRequest: CreateCredentialRequest( orgId: org.id, provider: ProviderId.openrouter, label: 'Main', apiKey: openRouterKey, ), )).data!; final bot = (await casama.bots.createBot( createBotRequest: CreateBotRequest( orgId: org.id, name: 'Invoicer', personaMd: 'You chase unpaid invoices politely.', modelPolicy: ModelPolicy( primary: ModelChoice( credentialId: key.id, model: casama.config.defaultModels['openrouter']!, ), ), ), )).data!; ``` ## Send a message and stream the run ```dart final conversation = (await casama.chat.createConversation( createConversationRequest: CreateConversationRequest(botId: bot.id), )).data!; final sent = (await casama.chat.sendMessage( id: conversation.id, sendMessageRequest: SendMessageRequest(text: 'Which invoices are overdue?'), )).data!; await for (final e in watchRun(casama, sent.runId)) { switch (e) { case MessageDeltaItem(:final event): stdout.write(event.payload.text); case ToolStartedItem(:final event): print('\n[tool] ${event.payload.tool}'); case RunFailedItem(:final event): print('\nFailed: ${event.payload.message} (${event.payload.errorCode})'); case RunCompletedItem(): print(''); default: break; } } ``` ### `watchRun` ```dart Stream watchRun(CasamaClient client, String runId, {int afterSeq = 0, int maxRetries = 8}) ``` - **Catch-up first.** It asks for events after `afterSeq`, so you get everything that already happened, then live events as they come. - **In order, once.** Events arrive strictly by `seq`, with duplicates dropped. - **Reconnects.** If the connection drops, it reconnects with backoff (250 ms, doubling up to 8 seconds) and resumes after the last event it delivered. After `maxRetries` failures in a row, the stream ends with the error. Client errors (4xx, apart from 408 and 429) end it at once. - **Ends with the run.** The stream closes after `run.completed`, `run.failed` or `run.cancelled`. To resume watching later, for example after your program restarts, pass the last `seq` you processed as `afterSeq`. ### Run event types Each event is a `RunEventItem`, a sealed class with one subclass per event type, so `switch` can check you've handled them. Every item has `seq`, `type`, `runId`, the raw `envelope` and, for known types, a typed `event` whose `payload` has the fields. | Class | Event type | | --- | --- | | `RunStartedItem` | `run.started` | | `MessageDeltaItem`, `MessageCompletedItem` | `message.delta`, `message.completed` | | `ToolStartedItem`, `ToolOutputItem`, `ToolCompletedItem`, `ToolFailedItem` | `tool.*` | | `ApprovalRequestedItem`, `ApprovalResolvedItem` | `approval.*` | | `UsageItem` | `usage` | | `NoticeItem` | `notice` | | `RunCompletedItem`, `RunFailedItem`, `RunCancelledItem` | `run.completed`, `run.failed`, `run.cancelled` | | `UnknownRunEventItem` | A type this SDK version doesn't know | There are classes for the other types too (`SecretRequestedItem`, `SubrunStartedItem`, `MemoryWrittenItem`, `SkillLoadedItem`, `ModelFallbackItem`, `CheckpointCreatedItem`, `TakeoverRequestedItem`, `UiShownItem`, ...). A newer server can send types an older SDK doesn't know; they arrive as `UnknownRunEventItem` instead of breaking your app. The [HTTP API page](/develop/api#event-types) describes each type. ### Your own event source `RunEventBuffer` is the ordering logic behind `watchRun`: feed it events from any source (a Realtime subscription, a page from `GET /v1/runs/{id}/events`) and it releases them in `seq` order with duplicates dropped. `addAll` takes a list, such as a page of catch-up events. `hasGap` tells you when an event is missing and you should fetch the gap. ```dart final buffer = RunEventBuffer(lastSeq: 0); for (final e in buffer.add(incoming)) { render(e); } ``` ## Approvals When the bot needs a person to approve a step, you get an `ApprovalRequestedItem`. Approve or deny it, and the run carries on: ```dart await for (final e in watchRun(casama, runId)) { if (e is ApprovalRequestedItem) { final p = e.event.payload; final ok = await askUser('Allow ${p.tool} (${p.risk.value} risk)?'); await casama.approvals.decideApproval( id: p.approvalId, approvalDecisionRequest: ApprovalDecisionRequest( decision: ok ? ApprovalDecisionRequestDecisionEnum.approved : ApprovalDecisionRequestDecisionEnum.denied, ), ); } } ``` Set `alwaysAllow: true` to stop asking about that tool for that bot. Denying fails only that step. `casama.approvals.listApprovals(orgId: org.id, status: 'pending')` lists everything waiting. See [Autonomy and approvals](/guide/autonomy). ## Cancel a run ```dart await casama.runs.cancelRun(id: runId); ``` The run stops within about two seconds and `watchRun` ends with a `RunCancelledItem`. ## Errors API calls throw Dio's `DioException`. `problemOf` turns it into the API's [problem details](/develop/api#errors), with a stable `code`: ```dart try { await casama.runs.cancelRun(id: runId); } on DioException catch (e) { final problem = problemOf(e); if (problem?.code == 'run_finished') { print('Already done.'); } else if (problem != null) { print('${problem.code}: ${problem.detail ?? problem.title}'); for (final field in problem.errors ?? const []) { print(' ${field.path}: ${field.message}'); } } else { rethrow; // a network error, not an API answer } } ``` Sign-in failures throw `AuthException`, with the auth server's `message` and `statusCode`. ## Other helpers | Method | What it does | | --- | --- | | `uploadComputerFile(computerId, path, bytes)` | Upload a file to a bot's computer | | `downloadComputerFile(computerId, path)` | Download a file as bytes | | `terminalEndpoint(computerId, {cols, rows})` | The WebSocket URL and headers for an interactive terminal | | `transcribe(botId, audio, {mime, language})` | Turn a voice recording into text with the workspace's speech-to-text key | Two more libraries need `dart:io`, so they're separate imports and don't work on the web: - `package:casama_sdk/chatgpt_sign_in.dart` has `signInWithChatGpt`, which connects a ChatGPT plan through the browser, as `casama credential chatgpt` does. It listens on a loopback port for the sign-in to come back and gives up after `timeout` (default 10 minutes). The tokens stay on the server. - `package:casama_sdk/casama_link.dart` is Casama Link for a self-hosted server, the part `casama selfhost remote` and the desktop app share: `CasamaLinkClient` for the calls to Casama Cloud, and `RemoteAccessSetup`, which links a server and turns remote access on or off for the stack in a folder. See [Use your server on your phone](/self-hosting/remote-access). ## The sample app [`examples/sdk_sample`](https://github.com/stackwares/casama/tree/main/examples/sdk_sample) is a small external program that depends on `casama_sdk` the way your app would. It signs up (or in), creates a workspace, adds an OpenRouter key, creates a bot, sends one message and streams the run: ```sh cd examples/sdk_sample dart pub get dart run bin/sample.dart --api https://casama.example.com \ --email ana@example.com --password correct-horse-battery \ --key "$OPENROUTER_API_KEY" --message "Say hello" ``` `--api` defaults to `http://localhost:8787`, a server running on your machine. `--model` picks the model; without it, the server's default for OpenRouter keys. The package also has a shorter example in `dart/casama_sdk/example/example.dart`: send a message to an existing conversation and print the reply. ## Related - [HTTP API](/develop/api): authentication, errors and the event protocol - [API reference](/api/): every endpoint, which maps one to one to the client's methods - [CLI](/develop/cli): built on this SDK - [Autonomy and approvals](/guide/autonomy) # TypeScript client `@casama/client` is the TypeScript and JavaScript library for Casama. It gives you a typed client for the whole [HTTP API](/develop/api), plus helpers to ask a bot and wait for its reply, follow a run live and decide approvals. Your editor completes every path, parameter and field, and the compiler checks them. The types are generated from the API's OpenAPI document, and requests go through [openapi-fetch](https://openapi-ts.dev/openapi-fetch/), a thin typed layer over `fetch`. It runs anywhere `fetch` does: Node 20 or later, Bun, Deno, browsers and edge runtimes. ## Install ```sh npm i @casama/client ``` Keep the client's version in step with your server's `api_version` (from `GET /v1/config`): it's generated from that server version's routes. ## Connect ```ts import { createCasamaClient } from "@casama/client"; const casama = createCasamaClient({ apiUrl: "https://casama.example.com", token: process.env.CASAMA_TOKEN, }); const { data: me } = await casama.GET("/v1/me"); console.log(`Signed in as ${me?.email}`); ``` `apiUrl` defaults to Casama Cloud, `https://api.casama.ai`. | Option | What it does | | --- | --- | | `apiUrl` | The server's API address | | `token` | A fixed access token, sent as `Authorization: Bearer` | | `getToken` | A function called before every request for the current token. Use it when tokens refresh. | | `fetch` | Your own `fetch`, for tests, proxies or retries | | `headers` | Extra headers on every request | ## Sign in The API takes a Casama sign-in token: the access token from the Supabase Auth server named in `GET /v1/config` (see [Authentication](/develop/api#authentication)). The easiest way to get one and keep it fresh is `@supabase/supabase-js`: ```ts import { createClient } from "@supabase/supabase-js"; import { createCasamaClient } from "@casama/client"; const apiUrl = "https://casama.example.com"; const { data: config } = await createCasamaClient({ apiUrl }).GET("/v1/config"); const supabase = createClient(config!.supabase_url, config!.supabase_anon_key); await supabase.auth.signInWithPassword({ email: "ana@example.com", password: "correct-horse-battery" }); const casama = createCasamaClient({ apiUrl, getToken: async () => (await supabase.auth.getSession()).data.session?.access_token, }); ``` Supabase refreshes the session for you, and `getToken` hands the client the current token on every request. For a quick script, `token` with a token you copied is enough; it lasts about an hour. Workspace API keys (`ksk_...`) don't work on the HTTP API. They're for the [hosted MCP endpoint](/guide/mcp) and [agent-to-agent](/develop/a2a) calls. ## List workspaces and bots Raw calls name the path as it appears in the [API reference](/api/). They return `{ data, error, response }`: ```ts const { data: orgs } = await casama.GET("/v1/orgs"); const org = orgs!.items.find((o) => o.slug === "acme")!; const { data: bots, error } = await casama.GET("/v1/bots", { params: { query: { org_id: org.id } }, }); if (error) throw new Error(error.detail ?? error.code); for (const b of bots.items) console.log(`${b.name}: ${b.status}`); ``` ## Ask a bot `ask` starts a conversation (or continues one), sends your message, waits for the run to end and returns the reply: ```ts const reply = await casama.ask(botId, "Which invoices are overdue?"); console.log(reply.text); console.log(reply.run.status, `$${reply.run.cost_usd.toFixed(4)}`); // Carry on in the same conversation. const more = await casama.ask(botId, "Draft a reminder for the oldest one.", { conversationId: reply.conversationId, }); ``` | Option | What it does | | --- | --- | | `conversationId` | Continue this conversation. Without it, `ask` starts a new one. | | `title` | The new conversation's title | | `timeoutMs` | Stop waiting after this long (default 10 minutes) and return what arrived, with `timedOut: true` | | `onEvent` | Called for every event as it arrives, for example to print the reply live | | `onApproval` | Called when the bot asks for approval (see [below](#approvals)) | | `message` | Extra message fields, such as `attachments` or `skills` | | `transport` | `sse` (default) streams the run; `poll` asks for new events every `pollIntervalMs` | | `signal` | An `AbortSignal` to give up early | The result has `text` (the text of the bot's finished messages), `run` (status, tokens, cost and any error), `runId`, `conversationId`, `messageId`, every `events` it saw and `timedOut`. Each message carries an `Idempotency-Key`, so a retry never sends it twice. Print the reply as it's written: ```ts await casama.ask(botId, "Write a haiku about invoices.", { onEvent: (e) => { if (e.type === "message.delta") process.stdout.write(e.payload.text); }, }); ``` ## Watch a run `watchRun` follows a run you started some other way, for example from `POST /v1/conversations/{id}/messages`, a routine or another app: ```ts for await (const e of casama.watchRun(runId)) { switch (e.type) { case "message.delta": process.stdout.write(e.payload.text); break; case "tool.started": console.log(`\n[tool] ${e.payload.tool}`); break; case "run.failed": console.log(`\nFailed: ${e.payload.message} (${e.payload.error_code})`); break; } } ``` - **Catch-up first.** You get everything that already happened, then live events as they come. - **In order, once.** Events arrive by `seq`, with no repeats. - **Reconnects.** If the stream drops, it reconnects with backoff (250 ms, doubling up to 8 seconds) and picks up after the last event. After 8 failures in a row (`maxRetries`) it throws. Client errors, such as 404 `run_not_found`, throw at once. - **Ends with the run.** The loop ends after `run.completed`, `run.failed` or `run.cancelled`. `switch (e.type)` narrows `e.payload` to that event's fields. A newer server can send event types this version doesn't list; ignore what you don't know. To resume later, pass the last `seq` you handled as `afterSeq`. The [HTTP API page](/develop/api#event-types) describes each type. ## Approvals When the bot needs a person to approve a step, the run waits on an `approval.requested` event. Give `ask` an `onApproval` function and it answers for you: ```ts const reply = await casama.ask(botId, "Clean up the old build folders.", { onApproval: async (req) => { const ok = await confirm(`Allow ${req.tool} (${req.risk} risk)?`); return ok ? "approved" : "denied"; }, }); ``` Return `{ decision: "approved", alwaysAllow: true }` to stop asking about that tool for that bot. Denying fails only that step. Without `onApproval`, `ask` returns as soon as the run waits, with the request in `pendingApproval`; decide it later with `decideApproval`: ```ts if (reply.pendingApproval) { await casama.decideApproval(reply.pendingApproval.approval_id, "approved"); } ``` List everything waiting with `casama.GET("/v1/approvals", { params: { query: { org_id: org.id, status: "pending" } } })`. See [Autonomy and approvals](/guide/autonomy). ## Cancel a run ```ts await casama.cancelRun(runId); ``` The run stops within about two seconds and `watchRun` ends with `run.cancelled`. ## Errors Helpers (`ask`, `watchRun`, `decideApproval`, `cancelRun`) throw `CasamaError`, built from the API's [problem details](/develop/api#errors). Match on `code`, which is stable: ```ts import { CasamaError } from "@casama/client"; try { await casama.cancelRun(runId); } catch (e) { if (e instanceof CasamaError && e.code === "run_finished") { console.log("Already done."); } else if (e instanceof CasamaError) { console.log(`${e.code}: ${e.detail ?? e.title}`); for (const f of e.errors) console.log(` ${f.path}: ${f.message}`); } else { throw e; // a network error, not an API answer } } ``` | Field | Meaning | | --- | --- | | `status` | The HTTP status | | `code` | Stable code, such as `bot_not_found` or `rate_limited`. `http_502` and the like when the answer wasn't problem details (a proxy's error page). | | `detail`, `title` | Sentences for people | | `errors` | For `validation_failed`: one entry per bad field | | `retryAfter` | For 429: seconds to wait | | `requestId` | The `x-request-id`; include it when you report a problem | Raw calls don't throw for API errors; they return `error`. Wrap one in `casama.unwrap` to get `data` or a thrown `CasamaError`: ```ts const run = await casama.unwrap(casama.GET("/v1/runs/{id}", { params: { path: { id: runId } } })); console.log(run.status, run.tokens_in, run.tokens_out); ``` ## Raw typed calls Everything else in the [API reference](/api/) is a raw call: `GET`, `POST`, `PUT`, `PATCH` and `DELETE`, with the path's parameters and body checked against the schema. ```ts const { data: conversation } = await casama.POST("/v1/conversations", { body: { bot_id: botId, title: "From TypeScript" }, }); const { data: sent } = await casama.POST("/v1/conversations/{id}/messages", { params: { path: { id: conversation!.id } }, headers: { "idempotency-key": crypto.randomUUID() }, body: { text: "Summarise this week's tickets." }, }); const { data: page } = await casama.GET("/v1/runs/{id}/events", { params: { path: { id: sent!.run_id }, query: { after_seq: 0, limit: 500 } }, }); ``` The schema types are exported too, for your own functions: ```ts import type { Schemas, RunEvent } from "@casama/client"; type Bot = Schemas["Bot"]; function show(e: RunEvent) { /* ... */ } ``` `casama.api` is the underlying openapi-fetch client, for middleware such as logging or retries: `casama.api.use({ onResponse: ({ response }) => console.log(response.status) })`. ## Related - [HTTP API](/develop/api): authentication, errors and the event protocol - [API reference](/api/): every endpoint, each one a raw call here - [Dart SDK](/develop/sdk): the same for Dart and Flutter - [Hosted MCP](/guide/mcp): use bots from AI apps without code # Webhooks Webhooks let other services start work in Casama. The main kind is a **routine webhook**: a routine whose trigger is an HTTP request instead of a schedule. GitHub can call it on a push or a new issue, or your own system can call it when something happens, and the bot gets the request's body as context. This page is about webhooks coming **into** Casama. Every one is checked with an HMAC signature, so only senders who know the secret can trigger anything. ## Routine webhooks There are two kinds: | Trigger | URL | Signature header | | --- | --- | --- | | `github` | `https://casama.example.com/hooks/github/` | `X-Hub-Signature-256` (sent by GitHub) | | `webhook` | `https://casama.example.com/hooks/custom/` | `X-Casama-Signature` (you compute it) | Both use the same signature: `sha256=` followed by the hex HMAC-SHA256 of the raw request body, keyed with the routine's secret. ### Create one In the app, create a routine and pick a webhook or GitHub trigger (see [Routines](/guide/routines)). Or use the API: ```sh curl -s -X POST "https://casama.example.com/v1/routines" \ -H "authorization: Bearer $TOKEN" \ -H "content-type: application/json" \ -d '{ "bot_id": "'"$BOT"'", "name": "Triage new orders", "instructions": "A new order came in. Check stock and draft a confirmation email.", "trigger": "webhook" }' ``` The response is the routine, plus two fields shown **only this once**: ```json { "id": "8c3e5f0a-2b1d-4c6e-9f7a-1d2c3b4a5e6f", "name": "Triage new orders", "webhook_url": "https://casama.example.com/hooks/custom/8c3e5f0a-2b1d-4c6e-9f7a-1d2c3b4a5e6f", "webhook_secret": "4b1f0c9e8d7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a", "...": "..." } ``` Store the secret somewhere safe. Casama keeps it in its vault and never shows it again. If you lose it, create a new routine. For a GitHub routine, set `"trigger": "github"` and optionally `"events"`: the GitHub event names to accept, such as `["push", "issues"]` (up to 20). Without `events`, every event starts a run. A webhook routine can also end on its own. Add `ends_at` (a time with its offset) to switch it off for good at that time, or `max_runs` (1 to 10,000) to switch it off after that many runs. Change or remove either later with `PATCH /v1/routines/{id}`, where `null` removes it. Runs you start by hand with **Run now** don't count toward `max_runs`. ::: tip Behind a proxy `webhook_url` is built from the address your request reached. If the API sits behind a proxy, check that the URL uses your public address before you hand it out. ::: ### GitHub In the repository (or organization), open **Settings → Webhooks → Add webhook** and fill in: | Field | Value | | --- | --- | | Payload URL | The routine's `webhook_url` | | Content type | `application/json` | | Secret | The routine's `webhook_secret` | | Events | The ones you listed in `events`, or the ones you want | GitHub signs each delivery with `X-Hub-Signature-256` and names the event in `X-GitHub-Event`. Casama checks both. ### Your own service Send a `POST` with any body (JSON is typical) and the signature in `X-Casama-Signature`. You can also name the event in `X-Casama-Event`: the bot sees it, and if the routine has `events`, only those event names start a run. **Shell (OpenSSL):** ```sh URL=https://casama.example.com/hooks/custom/8c3e5f0a-2b1d-4c6e-9f7a-1d2c3b4a5e6f SECRET=4b1f0c9e8d7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a BODY='{"order_id": 1042, "customer": "Ana Cruz", "total": "129.00"}' SIG="sha256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')" curl -s -X POST "$URL" \ -H "content-type: application/json" \ -H "x-casama-signature: $SIG" \ -H "x-casama-event: order.created" \ --data-binary "$BODY" ``` **Node.js:** ```js import { createHmac } from "node:crypto"; const url = "https://casama.example.com/hooks/custom/8c3e5f0a-2b1d-4c6e-9f7a-1d2c3b4a5e6f"; const secret = process.env.CASAMA_WEBHOOK_SECRET; const body = JSON.stringify({ order_id: 1042, customer: "Ana Cruz", total: "129.00" }); const signature = `sha256=${createHmac("sha256", secret).update(body).digest("hex")}`; const res = await fetch(url, { method: "POST", headers: { "content-type": "application/json", "x-casama-signature": signature, "x-casama-event": "order.created", }, body, }); console.log(res.status); // 202 ``` **Python:** ```python import hashlib import hmac import json import os import urllib.request url = "https://casama.example.com/hooks/custom/8c3e5f0a-2b1d-4c6e-9f7a-1d2c3b4a5e6f" secret = os.environ["CASAMA_WEBHOOK_SECRET"].encode() body = json.dumps({"order_id": 1042, "customer": "Ana Cruz", "total": "129.00"}).encode() signature = "sha256=" + hmac.new(secret, body, hashlib.sha256).hexdigest() req = urllib.request.Request( url, data=body, method="POST", headers={ "content-type": "application/json", "x-casama-signature": signature, "x-casama-event": "order.created", }, ) print(urllib.request.urlopen(req).status) # 202 ``` Sign the exact bytes you send. If you serialize the JSON twice, or a library reformats it, the signature won't match. ### What happens 1. Casama answers **202** `{"accepted": true}` right away, before it checks anything. It answers the same way for a bad signature or a routine that doesn't exist, so nobody can probe which routines exist. 2. The worker checks the signature with a constant-time comparison. The request is dropped silently if the signature is wrong, the routine is turned off, past its `ends_at` or has another trigger, or the event isn't one the routine accepts. 3. Otherwise the bot starts a run. It sees the routine's instructions, then the event: an `Event: ` line (from `X-GitHub-Event` or `X-Casama-Event`) and the body, up to its first 50,000 characters. The body is marked as untrusted outside content, so the bot treats it as data, not as instructions from you. 4. Like any routine run, it happens in the routine's conversation: by default the latest chat between the routine's creator and the bot, or a new one named after the routine. Because a bad request also gets a 202, test a new webhook by checking that a run appears in the bot's chat. If nothing shows up, check the secret and that you signed the raw body. ### Retries and duplicates Casama doesn't deduplicate deliveries: each request with a valid signature starts its own run. A 202 tells GitHub and most senders that the delivery succeeded, so they won't retry it. If your own sender retries on network errors, expect an occasional second run, or make the instructions safe to repeat (for example "skip orders you've already confirmed"). Casama answers something other than 202 only when: | Status | When | What to do | | --- | --- | --- | | 413 | The body is over 1 MB | Send less: an id and a link instead of the whole object | | 429 | Too many requests from one address in a minute | Wait for `Retry-After` seconds, then retry | ## Git sync webhook [Git sync](/develop/workspace-files#git-sync) keeps a workspace's routines and skills in a GitHub repository. Casama checks the repository every 10 minutes anyway; a push webhook makes it pick up changes within a minute. When an admin first sets up git sync, Casama shows a webhook URL and secret, once: | Field | Value | | --- | --- | | Payload URL | `https://casama.example.com/hooks/git-sync/` | | Content type | `application/json` | | Secret | The secret shown at setup | | Events | Just the push event | Unlike routine webhooks, this one answers right away: **202** `{"ok": true}` when the `X-Hub-Signature-256` signature matches, and **401** `bad_signature` when it doesn't (or git sync isn't set up or is off). GitHub's delivery log shows which. ## Other inbound webhooks Some features receive webhooks from a provider you connect. Casama shows the URL when you set the feature up, and checks each provider's own signature: | Feature | URL | Checked with | | --- | --- | --- | | [Chat apps](/guide/chat-apps) | `/hooks/channels/` | The provider's own signature (each adapter verifies its platform's scheme) | | [Slack](/guide/chat-apps), with the server's own Slack app | `/hooks/slack/events` and `/hooks/slack/interact` | The Slack app's signing secret (`SLACK_SIGNING_SECRET`) | | [Payments](/guide/payments) | `/hooks/payments/` | `Stripe-Signature`, with the signing secret of the Stripe webhook you created | Paste these URLs into the provider's settings as the feature's guide describes. You don't call them yourself. ## Limits | What | Limit | | --- | --- | | Body size | 1 MB (413 above it) | | Body the bot sees | The first 50,000 characters | | Requests | 120 a minute per sender IP address by default, shared by all `/hooks/` URLs | | GitHub `events` per routine | 20 | ## Related - [Routines](/guide/routines): schedules, triggers and where results go - [Routines and skills as files](/develop/workspace-files): git sync setup - [HTTP API](/develop/api): creating routines from code - [Autonomy and approvals](/guide/autonomy): what a webhook-started run may do on its own # Routines and skills as files Every routine and skill in a workspace can live as a Markdown file. Export them to a folder, edit them in any editor, review changes in pull requests, and import them back. Or connect a GitHub repository and let Casama keep both sides in sync. Exporting, importing and git sync are for workspace owners and admins, because the files cover every bot in the workspace. ## The folder layout ```text casama-files/ ├── casama.json which folder is which bot ├── invoicer/ one folder per bot │ ├── routines/ │ │ └── weekly-chase.md one file per routine │ └── skills/ │ └── dunning/ │ ├── SKILL.md one folder per skill │ └── templates/ │ └── reminder.md files the skill uses └── workspace/ └── skills/ └── house-style/ └── SKILL.md a skill every bot in the workspace has ``` Bot folders are named after the bot (lowercase, with dashes). `workspace/` is reserved for skills the whole workspace shares. ### casama.json The index that ties folders to bots: ```json { "format": "casama.files", "version": 1, "bots": { "invoicer": { "id": "5d0c1e6a-8b7f-4e8a-a1d2-3c4b5a6f7e80", "name": "Invoicer" } } } ``` On import, a folder matches a bot by the `id` in `casama.json`. Without a match there (or without `casama.json` at all), Casama matches the folder name against the bot names. Renaming a bot in the app doesn't break the link, as long as `casama.json` keeps its id. ### Routine files `/routines/.md`: front matter between `---` lines, then the instructions. ```markdown --- id: 8c3e5f0a-2b1d-4c6e-9f7a-1d2c3b4a5e6f name: Weekly chase schedule: 0 9 * * 1 timezone: America/Chicago trigger: schedule enabled: true notify: true ends_at: null max_runs: null --- Check for overdue invoices and follow the dunning skill. Send me a short summary of who you contacted. ``` | Field | Required | Meaning | | --- | --- | --- | | `id` | no | The routine's id. Casama writes it on export; leave it out for a new routine. | | `name` | yes | Up to 120 characters | | `schedule` | for `schedule` triggers | A 5-field cron expression; `null` for other triggers | | `run_at` | for `once` triggers | When a one-time routine runs, such as `2027-01-15T09:00:00.000Z`. See [One-time routines](#one-time-routines). | | `timezone` | no | An IANA time zone, such as `America/Chicago`. Defaults to `UTC`. | | `trigger` | no | `schedule` (default), `once`, `webhook`, `github`, `calendar_event`, `message` or `device` | | `calendar`, `message`, `device` | for those triggers | The trigger's settings. See [Event triggers](#event-triggers). | | `enabled` | no | `true` (default) or `false` | | `notify` | no | Whether to notify you when it runs: `true` (default) or `false` | | `ends_at` | no | When the routine switches itself off, or `null` for never. Not for `once`. | | `max_runs` | no | How many more runs before it switches itself off (1 to 10,000), or `null` for no limit. Not for `once`. | The body after the front matter is the instructions: required, up to 20,000 characters. #### One-time routines ```markdown --- name: Renew the passport schedule: null run_at: 2027-01-15T09:00:00.000Z timezone: Asia/Manila trigger: once enabled: true notify: true --- Remind me to renew my passport and list the documents I need. ``` Export writes the pending run as `run_at`, and `null` once the routine has run. On import, a `run_at` moves the run; a missing `run_at` (or `null`) keeps the routine's pending run, so editing the instructions doesn't cancel it. Switching on a one-time routine needs a `run_at` in the future. Changing `trigger` between `schedule` and `once` switches the routine between repeating and running once, as in the app. #### Event triggers Calendar, message and device routines keep their settings under a key named after the trigger: `calendar` for `calendar_event`, `message` and `device`. Export writes them as one line of JSON (which is also YAML); the fields are the same as the API's [`calendar`, `message` and `device` fields](/develop/api): ```markdown --- name: Arrive home schedule: null timezone: Asia/Manila trigger: device device: {"event":"arrive","place":"Home"} enabled: true notify: true ends_at: null max_runs: 20 --- Turn on the porch light routine and tell me what's on tonight. ``` By hand, an indented map works too: ```yaml trigger: message message: channel_kind: email sender: "*@acme.com" ``` Import checks them like the API does: a message routine needs at least one filter, arrive and leave need a `place`, notification routines need an `app`, file routines need a `folder`, and a calendar routine's `integration_id` must be a calendar connected in this workspace (so a calendar routine from another workspace needs its id changed first). Git sync can't create device routines, because they follow one person's phone or computer: import those from the app or the CLI. #### When a routine ends `ends_at` and `max_runs` work as in the app's **When It Ends** and `PATCH /v1/routines/{id}`: - Export writes both for every routine but `once`, `null` when there's no end. - On import, `null` removes the end and a missing key leaves it as it is (files from before ends existed don't carry them). - A changed `max_runs` counts from the import, so `max_runs: 3` means three more runs. An unchanged one keeps counting. - A routine can't be switched on (`enabled: true`) past its `ends_at` or after it ran its `max_runs` times. The file is reported in `errors` and the routine stays off until the file moves the end, raises the runs or removes them. A paused routine may keep a past `ends_at`, so exports of ended routines import back as they are. ::: warning Webhook and GitHub triggers A file can't create a webhook or GitHub routine, or switch a routine to one, because those need a secret that only the app shows. Create them in the app or the API (see [Webhooks](/develop/webhooks)); after that, their files can update the name, instructions and other fields like any routine. ::: ::: tip Changing the trigger A file can switch a routine between `schedule` and `once`. Calendar, message, device, webhook and GitHub routines keep their trigger kind (their settings can change); to change the kind, create a new routine. ::: ### Skill files `/skills//SKILL.md` for one bot's skill, or `workspace/skills//SKILL.md` for a skill every bot in the workspace has. It's a normal [Agent Skills](https://agentskills.io) `SKILL.md`, plus Casama's `id` and `enabled`: ```markdown --- name: dunning description: Follow-up cadence for overdue invoices. Use when an invoice is past due. id: 0f9e8d7c-6b5a-4c3d-2e1f-0a9b8c7d6e5f enabled: true --- 1. Day 7: a friendly reminder, using templates/reminder.md. 2. Day 14: a firmer note with the invoice attached. 3. Day 30: tell me before sending anything else. ``` | Field | Required | Meaning | | --- | --- | --- | | `name` | yes | Lowercase letters, digits, `-` and `_`, up to 63 characters. Must match the folder's name. | | `description` | yes | When to use the skill. Casama keeps the first 300 characters. | | `id` | no | Written on export | | `enabled` | no | `true` (default) or `false` | The body is the skill's instructions (up to 50,000 characters). Every other file in the skill's folder goes with it, so the bot finds it on its computer. Files imported this way aren't marked executable, so start scripts with their interpreter (`bash scripts/check.sh`, `python3 tool.py`). See [Skills](/guide/skills). ### What's left out Export skips skills installed by [plugins](/develop/plugins) (change the plugin instead) and check-in routines, which Casama manages for you. Archived bots aren't exported. Routine files don't carry a routine's run count (how many times it ran toward `max_runs`), a webhook's secret or a GitHub routine's event list; those stay as they are. ## Export **In the app:** Workspace settings → **Routines and skills as files** → **Export as files** saves a ZIP. **With the CLI:** ```sh casama files export ./casama-files --org acme ``` **With the API:** `POST /v1/orgs/{id}/files/export` returns the same files both as one ZIP and one by one, base64-encoded: ```sh curl -s -X POST "https://casama.example.com/v1/orgs/$ORG/files/export" \ -H "authorization: Bearer $TOKEN" | jq -r .zip_base64 | base64 --decode > casama-files.zip ``` ```json { "zip_base64": "UEsDBBQ...", "count": 4, "files": [{ "path": "casama.json", "content_base64": "ewogICJmb3JtYXQi..." }] } ``` ## Import **In the app:** Workspace settings → **Routines and skills as files** → **Import files**, pick a ZIP, review the preview (new, changed and unchanged), then **Apply**. **With the CLI:** ```sh casama files import ./casama-files --dry-run casama files import ./casama-files ``` The CLI skips files and folders whose names start with `.`, such as `.git`. **With the API:** `POST /v1/orgs/{id}/files/import` takes either a ZIP or a list of files: ```sh jq -n --arg zip "$(base64 < casama-files.zip | tr -d '\n')" '{zip_base64: $zip, dry_run: true}' | curl -s -X POST "https://casama.example.com/v1/orgs/$ORG/files/import" \ -H "authorization: Bearer $TOKEN" \ -H "content-type: application/json" \ -d @- ``` | Field | Meaning | | --- | --- | | `zip_base64` | A ZIP of the folder, base64-encoded. A ZIP whose files all sit in one top folder with `casama.json` inside works too. | | `files` | Instead of a ZIP: `[{ "path": "invoicer/routines/weekly-chase.md", "content_base64": "..." }]` | | `dry_run` | `true` to see what would change without changing anything | ```json { "created": ["invoicer/routines/month-end.md"], "updated": ["invoicer/skills/dunning/SKILL.md"], "deleted": [], "unchanged": 2, "errors": ["invoicer/routines/bad.md: \"0 9 * *\" isn't a valid cron schedule"], "dry_run": true } ``` ### How import decides - **Matching.** A routine matches by its `id`, else by bot and name. A skill matches by bot and name. - **Changes.** A changed file updates its routine or skill; a new file creates one. Changing a schedule or time zone moves the next run. - **Nothing is deleted.** Removing a file and importing leaves the routine or skill in place. Delete it in the app. (Git sync is different; see below.) - **Bad files are skipped.** Every file is checked: front matter, cron, time zone, names, trigger settings, ends (as above), and that a skill's folder matches its name. Problems are listed in `errors`, and the other files still apply. The CLI exits with code 1 when there are errors. - **Plugin skills stay as they are.** A file for a skill that came from a plugin is reported as an error. ## Git sync Git sync keeps a workspace's routines and skills in a GitHub repository, both ways. Edit a routine in the app and Casama commits the change; push a change to the repository and Casama applies it. ### Set it up 1. **Add a GitHub token.** In workspace secrets, add a secret named `GITHUB_TOKEN`, allowed for the host `api.github.com`, with a token that can push to the repository and open pull requests. 2. **Connect the repository.** In Workspace settings → **Routines and skills as files** → **Git sync**, enter the repository (`owner/name`), the branch (default `main`) and, optionally, a folder inside the repository. Or use the API: ```sh curl -s -X PUT "https://casama.example.com/v1/orgs/$ORG/git-sync" \ -H "authorization: Bearer $TOKEN" \ -H "content-type: application/json" \ -d '{"repo": "acme/casama-config", "branch": "main", "path": "bots"}' ``` 3. **Add the webhook.** The first setup returns a `webhook_url` and a `webhook_secret`, shown only this once. In the repository's **Settings → Webhooks**, add a webhook for push events with that payload URL and secret, and the content type `application/json`. See [Git sync webhook](/develop/webhooks#git-sync-webhook). The webhook is optional but makes changes from the repository arrive within a minute instead of within 10 minutes. ### How sync works Each sync compares three versions of every file: what was synced last time, what Casama has now, and what the branch has now. | Changed in | Result | | --- | --- | | Casama only | Casama commits the change to the branch | | The repository only | Casama checks the file and applies it. A bad file is reported and retried once it's fixed. | | Both | Casama keeps its version and opens a pull request with it on a `casama/sync-...` branch. Merging it makes both sides agree. | - **When.** Changes in Casama sync within about a minute. Casama also checks the repository every 10 minutes, and a push webhook makes it check on the next minute. **Sync now** in the app (or `POST /v1/orgs/{id}/git-sync/run`) does the same. - **Same rules as import.** Git sync applies the repository's files with the checks above, so a push can't switch on a routine past its end or out of runs either. - **Deletions.** Unlike import, git sync deletes a routine or skill when you remove its file from the repository (only files that carry an `id`). - **Moving.** Changing the repository, branch or folder starts over, as if syncing for the first time. `GET /v1/orgs/{id}/git-sync` shows the state: `last_synced_at`, `last_commit`, `last_error` (bad files and other problems) and `open_pr_url` when a pull request is waiting for you. `has_token` tells you whether the `GITHUB_TOKEN` secret is in place. `DELETE /v1/orgs/{id}/git-sync` stops syncing and leaves the repository as it is. ## Limits | What | Limit | | --- | --- | | Routine name | 120 characters | | Routine instructions | 20,000 characters | | Skill name | 63 characters | | Skill description | 300 characters kept | | Skill body | 50,000 characters kept | | Files in an API import's `files` list | 5,000 | | Who | Workspace owners and admins | ## Related - [Routines](/guide/routines) - [Skills](/guide/skills) - [Webhooks](/develop/webhooks) - [Bot template format](/develop/bot-templates): one bot as a shareable file - [CLI](/develop/cli#routines-and-skills-as-files-files) # FAQ ## General ### How is Casama different from a chat assistant? A chat assistant answers while you watch. A Casama bot keeps its own memory and computer, works on schedules and triggers when you're not there, reaches out first with a morning brief and suggestions, uses your tools through connections, and asks you before risky steps. What it makes is kept in the [Library](/guide/library). You can run it yourself, on any model. ### Is it free? Self-hosting is free, with no paywall or limits; you pay only your model provider and your server. A local model costs nothing at all. [Casama Link](/self-hosting/remote-access), which puts a server on your own computer on your phone, is free too. Casama Cloud, the hosted service, has a Free plan and three paid plans: Plus ($15 a month), Pro ($49) and Max ($99), each cheaper by the year. Models, computers and voice there are paid from credits, counted in dollars (1 credit = $1), and each plan adds credits every month. Pro has a 7-day free trial. See [Usage, budgets and plans](/guide/usage). ### Which models can I use? Any model you have a key for: OpenAI, Anthropic, Google, xAI, OpenRouter, or any OpenAI-compatible endpoint (Ollama, vLLM, LM Studio and others). Each bot picks its own model, with fallbacks. See [Bots and models](/guide/bots). On Casama Cloud, Casama picks the models, so you don't need a key. ### Can I use my ChatGPT plan? Yes, on a self-hosted server. In the desktop app, open **Settings** → **Model keys** and choose **Continue with ChatGPT**, or run `casama credential chatgpt` in the CLI. Bots' model calls then count toward your plan's limits, and only you can use it. Casama Cloud doesn't offer it. ### Can I run it fully offline or with local models? You can run the server on your own network and use a local model through an OpenAI-compatible endpoint, and calls to it are free. Bots that browse the web or use cloud apps still need internet access for those tasks. ### Does a bot join my meetings? No. Casama doesn't send a bot into your calls. A bot can work from the notes your meeting app already takes, or from your calendar, and file a summary with decisions and action items. See [Meeting notes](/guide/meetings). ## Privacy and safety ### Who can see my data? On a self-hosted server, only people with access to your server. Every table uses row-level security, so one workspace can't read another's data. Message content can be encrypted at rest. The server sends no telemetry unless its owner turns it on. The official apps connected to your server send only crash reports and one anonymous daily ping. See [Privacy and security](/guide/privacy). ### Does the model see my passwords and API keys? No. Secrets live in a vault and are filled in at the moment a tool uses them, inside the computer or the request. They're redacted from logs and never put into the model's input. ### Can a bot do something I didn't want? Every action has a risk level, and the bot's autonomy level decides which actions need your approval first. Action rules can allow an action (optionally within limits, such as recipients at one domain or a maximum amount), always ask, or hand it to you to finish. You can also set budgets and stop a run at any time. Destructive commands take a checkpoint first, so you can roll the computer back. See [Autonomy and approvals](/guide/autonomy). ### What stops a bot's computer from reaching my network? Computers reach the internet only through an egress proxy that blocks private and cloud-metadata addresses, so a bot's computer can't reach your home or office network. See [Computer providers](/self-hosting/computers). ## Self-hosting ### Can I use a server on my own computer from my phone? Yes. [Casama Link](/self-hosting/remote-access) gives a server installed with `--local` an address like `https://k7qm2xfd9abc.casama.link`, with no domain and no open ports. Your phone signs in by scanning a QR code. Phone traffic goes through Cloudflare to your computer, never through Casama's servers. It's free on every plan, including Free. ### What do I need to self-host? A Linux server (or a Mac, for a trial) with Docker, and a domain if other people will connect. See [Self-hosting](/self-hosting/) for sizing. To try it on your own Mac or Linux computer without a terminal, use **Run on This Mac** (or **Run on This Computer**) on the desktop app's sign-in screen. It walks you through Docker, the server, your account, a model and your phone. ### How do I upgrade? Re-run `./install.sh`, or `casama selfhost upgrade`. Your settings and data are kept. See [Operations](/self-hosting/operations). ### Can I use Casama Cloud computers from my own server? Yes, with [Casama Link](/guide/casama-link). Computer time and model calls are paid from the cloud workspace's credits, and your bots, chats and data stay on your server. ## Building on Casama ### Is there an API? Yes. Everything the apps do goes through a documented HTTP API. See [HTTP API](/develop/api) and the [API reference](/api/). ### Can I extend what bots can do? Yes: connect MCP servers, write [plugins](/develop/plugins) (skills plus tool servers), share [bot templates](/develop/bot-templates), or call other agents over [A2A](/develop/a2a). ### Can my coding agent learn Casama? Yes. Give it the agent kit (skills for plugins, the API and more) and the docs MCP server, or point it at [llms.txt](https://docs.casama.ai/llms.txt). See [Build with AI agents](/develop/agents). ### How do I contribute? Read [Contribute to Casama](/develop/contributing), and [How Casama is built](/develop/architecture) for a map of the code. Bug reports, docs fixes and code are all welcome. ### How do I get help in the app? Open **Settings > Help & support**. On Casama Cloud, **Casama Help** answers straight away: it knows these guides and can check your account and the workspace you have open: your plan and its limits, purchases, this month's usage, credit history, connected apps and chat channels, invites, and a bot's settings, routines and recent errors. It sees what the app would show you and never reads your chats. When a person should take over, it writes up the problem and you send it to our support team with one tap; we reply by email. You can also choose **Contact support** there at any time. The same page shows your **support IDs**. Your workspace ID is also your purchase ID in the App Store and Google Play, so share it if we ask about a purchase. ### Is Casama Cloud down? [status.casama.ai](https://status.casama.ai) shows whether the API, web app, sign-in and docs are working right now, with 90 days of uptime and a note when we know about a problem. It runs outside our servers, so it stays up when they don't. If the app can't reach Casama Cloud, the bar at the top has a **Status** button that opens it. For a self-hosted server, see [Troubleshooting](/self-hosting/troubleshooting). ### How do I reach the Casama team? | For | Email | | -------------------------------- | --------------------------------------------- | | Anything else, or not sure | [hello@casama.ai](mailto:hello@casama.ai) | | Help with the apps or your account | [support@casama.ai](mailto:support@casama.ai) | | Plans, invoices and refunds | [billing@casama.ai](mailto:billing@casama.ai) | | Your data and privacy requests | [privacy@casama.ai](mailto:privacy@casama.ai) | | Security issues | [security@casama.ai](mailto:security@casama.ai) (see `SECURITY.md`) | # Appearance and themes Make Casama look the way you like: pick a whole theme in one tap, then change its colors, background and fonts. Everything lives in one place, **Settings → Appearance**, under **App**. Your look is saved on each device, so your phone and laptop can look different. ## Pick a theme 1. Open **Settings**, and under **App**, tap **Appearance**. 2. Choose **Light**, **System** or **Dark**. 3. Under **Themes**, tap a theme card. Each card is drawn in the theme's own colors, fonts and background, so what you see is what you get. The cards show your own themes first, then the built-in ones (such as **Plain**, **Casama**, **Editorial** and **Ocean**), then **From the Gallery** (tap **Show All** for the rest). A new install starts with the **Plain** theme: neutral grays with one quiet accent, Google Sans for headings and text, a flat background with no pattern, and fewer effects. Light or dark follows your system until you choose. The **Casama** theme, with its orchid and rose colors and clouds, is one tap away under **Themes**. Trying themes never loses work. If tapping a theme replaces changes you hadn't saved, a message offers **Undo**. At the top, a small chat shows the look in use, with its name, or **Custom look** once you've changed it. Tap **Save** there to keep a custom look as one of your themes. ## Customize a look Tap **Customize** under the preview. The page has three tabs, under a live preview that stays in view: | Tab | What you can change | | --- | --- | | **Colors** | The color scheme. Search, or filter by family; the **Gallery** chip adds schemes from the gallery. | | **Background** | Wallpapers from the gallery, a doodle **Pattern** and its **Pattern Strength**, **Colors**, or **Your Photo** (with **Blur** and **Dim** so text stays readable). Turn off **Show on every screen** to keep it behind chats only. **Reset to Default** goes back to Plain's flat background. | | **Fonts** | **Headings** and **Text**. Google Sans and Noto Serif work offline; other Google Fonts download the first time you pick them. **Use the Defaults** goes back to Google Sans. | The sun and moon button in the header previews the other brightness without changing your setting. Once the look is your own, **Save** appears in the header. ## Share and import themes - **Share code:** in one of your themes' menu, copy a code that starts with `casama-theme:`. Anyone can paste it into **Appearance → Import a Theme**. - **Share to Gallery:** propose your look for everyone, through the [open gallery](https://gallery.casama.ai). - **Delete** removes one of your own themes. - A gallery theme's menu has **About this theme**, with who made it. A gallery theme you use is kept with your themes, so it works offline. ## Fewer effects Turn on **Fewer Effects** to drop celebrations, bouncing tabs and animated bots. Casama also follows your system's reduced motion setting. ## Ask a bot for a new look Bots can suggest a look, such as "make it calmer" or "something dark and green". The suggestion shows as a card in the chat; **Apply** changes the look on that device only, with **Undo**. See [Bots that change their own setup](/guide/bots#bots-that-change-their-own-setup). ## Make your own **Make a look** on the gallery ([gallery.casama.ai/make.html](https://gallery.casama.ai/make.html)) builds a theme, color scheme or wallpaper in your browser, with live contrast checks and light and dark previews. It gives you the files to propose on GitHub. ## Limits - Your look stays on the device where you set it. It doesn't follow you to your other devices; use a theme code to copy it. - Some newer gallery looks need a newer version of the app. Older versions hide the ones they can't draw. ## Related - [Chatting with a bot](/guide/chat) - [Bots and models](/guide/bots) - [Skills](/guide/skills) # Notifications and attention Bots tell you when they need a decision, when work is done, and when they notice something. Casama decides how loudly to tell you: a push notification now, a push later, or a quiet note in your inbox that waits for your next brief. Use this page to set quiet hours, choose which bots may interrupt you, and understand why a message did or didn't buzz your phone. ## Where notifications go Every notification lands in one of three places at the top of **Chats**: | Where | What's in it | | --- | --- | | A bot's chat | What a bot tells you: briefs, routine results, suggestions and its replies land in your **General** chat with it (or the topic they belong to). Opening the chat marks them read. | | **Needs you** | Approvals, take-over and secret requests, suggestions and skill ideas, across all your bots. It shows only while something is waiting. See [Autonomy and approvals](/guide/autonomy). | | **Updates** | Workspace notices that belong to no chat (someone joined, missed calls, referrals, server alerts) and the pages your bots published. Everything bots make is also in the [Library](/guide/library). | In **Updates**, tap **Mark All as Read** to clear its unread count. Approvals, take-over requests and secret requests are marked read automatically once anyone answers them, and opening a bot's chat marks its results read. If you belong to several workspaces, the workspace switcher shows a dot when another workspace has pending approvals or unread notifications. ## Turn on push notifications The first time the app has something worth telling you, it shows **Turn on notifications**. 1. Tap **Turn on**. 2. Allow notifications in your system's prompt. Tap **Not now** to skip; the app offers again later. Push works in the iOS, Android and macOS apps, and in the web app when the server's build includes web push. The Windows and Linux apps use the in-app inbox only. ::: tip Self-hosting Push needs a Firebase project: the server needs its service account and the apps must be built with the same project. Without it, the in-app inbox still works. See [Configuration](/self-hosting/configuration). ::: ## Set quiet hours Quiet hours hold pushes overnight (or whenever you choose). The app still fills; the pushes arrive when the window ends. They're **on by default, from 22:00 to 07:00** in your timezone, which follows your phone. Bots don't run their scheduled check-ins during them either; your morning brief covers the night. To change them: 1. Open **Settings**, and under **App**, tap **Quiet hours**. 2. Turn quiet hours on or off. 3. Set **From** and **Until**. The window can cross midnight, for example 22:00 to 07:00. 4. Tap **Save**. When quiet hours end, Casama sends the pushes that waited, except ones you already read in the app. ### Choose per bot 1. Open the bot's chat, tap its name, and tap **Notifications from this bot**. You can also ask the bot to go quiet; turning itself quieter happens at once, but going back to your usual hours asks you first. 2. Pick one: | Option | What it does | | --- | --- | | **Follow my quiet hours** (default) | Uses your quiet hours from Settings | | **Always notify me** | This bot pushes even during your quiet hours | | **Its own quiet hours** | This bot uses its own window instead of yours | These settings are yours alone. Other people in the workspace set their own. ## What interrupts you, and when Notifications fall into three groups. **Urgent ones push right away**, even during quiet hours: - Approvals from a chat or voice call, because someone is waiting in the conversation. - Missed calls from a bot. - Proactive messages a bot marked urgent, such as an urgent suggestion. **Direct updates follow quiet hours**: approvals from routines and other background work, messages a bot sends you, take-over and secret requests, and similar. They push now, or when your quiet hours end. **Proactive messages follow attention rules.** These are messages you didn't ask for in the moment: routine results, suggestions from check-ins and similar. A suggestion's push comes from the bot, in its own words ("Want me to book a ride to the show at 7?"), and some wait until the time they matter, such as an hour before an event. Each has an urgency: | Urgency | What happens | | --- | --- | | Urgent | Pushes now, even during quiet hours | | Normal | Pushes, unless you're busy (see below). During quiet hours, the push waits for the window to end. | | Low | Never pushes. It waits in your inbox for your next brief. | ## Attention rules: when you're busy A normal-urgency proactive message doesn't push while any of these is true. It goes to your inbox and waits for your next brief instead. | You're busy when | How Casama knows | | --- | --- | | Focus is on | The latest Focus event from your devices in the last 12 hours is "on" | | You're driving | The latest driving event in the last 3 hours is "on" | | You're in a meeting | A timed event on the calendar you share from your devices is happening now | | The bot has said enough today | That bot already sent 5 non-urgent pushes today, in your timezone (the morning brief doesn't count) | Focus, driving and calendar data come from what you share under **Settings → Advanced → Device connections**. See [Your devices](/guide/devices). The daily limit counts per bot, so one chatty bot doesn't use up another's. ### Your brief carries what waited Your morning brief comes from a bot's **Check-Ins** (in its **Bot profile**). When a brief runs, it includes the messages that waited in the last 36 hours, each with the reason it waited, so nothing is lost. See [Routines](/guide/routines). ## Why am I seeing this? Proactive messages in the inbox have an info button. Tap it to open **Why am I seeing this?**, which shows: - The rule that sent it: a routine and its trigger in words (for example "when you arrive at Home"), your morning brief, or a suggestion from a check-in. - **Used:** the kinds of device data the bot looked at, if any. - **Urgency:** low, normal or urgent. - Why it waited, if it did. For example: "It waited while you were in a meeting and came with your brief." To hear less from a bot, tap **Less like this**. The bot saves a pinned preference to send these only when they really matter, or fold them into your brief. Only you can do this for your own notifications. ## Limits - Quiet hours follow the time zone your devices report. The app saves it after you sign in and whenever you come back to it, so after you travel, open the app once to move your quiet hours, brief and the routines on your old zone to the new one. - Messages that wait for a brief are only delivered by a brief. If no bot has **Check-Ins** on, they stay in your inbox without a push. - Focus and driving need a device that reports them. See [Your devices](/guide/devices) for which platforms do. - Push on Windows and Linux isn't available. ## Related - [Autonomy, approvals and action rules](/guide/autonomy) - [Routines](/guide/routines) - [Your devices](/guide/devices) - [Voice](/guide/voice) # Autonomy, approvals and action rules Every bot decides for itself when to act and when to check with you first. You control that with three things: the bot's **autonomy** level, the **risk** of each tool, and **action rules** for specific kinds of actions. Use this page to choose how much a bot may do on its own and to understand exactly when it will stop and ask. ## Choose a bot's autonomy 1. Open the bot's chat and tap its name at the top (or open the menu and choose **Bot profile**). 2. Under **Autonomy**, pick a level. 3. Tap **Save Changes**. | Level in the app | Value in the API and CLI | The bot asks before | | --- | --- | --- | | **Ask before acting** | `ask_always` | Every action that changes something | | **Ask for risky actions** (default) | `ask_risky` | Only really risky actions (listed below), paid data lookups, and, after it has read untrusted content, actions that send data out of Casama | | **Act on its own** | `autonomous` | Nothing, except high-risk actions on your own computer | Under **Ask for risky actions**, a bot does most work without asking. The high-risk actions that still ask are: sending through chat apps or email, calling other people, making a page public, creating or archiving bots, raising a bot's autonomy or budget, setup changes, opening pull requests, deleting things outside the bot's `~/workspace` folder, and connected-app tools marked **Always asks**. Payments always ask, whatever the level. Under every level, a bot never asks for built-in tools that only look at things (reading, listing, searching, taking screenshots) or for the [self-only actions](#actions-that-never-ask) below. Tools from connected apps marked **Read-only** still ask under **Ask before acting**. With the CLI, set the level when you create a bot: ```sh casama bot create "Ada" --credential --autonomy ask_always ``` A bot that manages other bots can change autonomy too, but it can never give any bot, itself included, more autonomy than it has. ## How risk is decided Each tool has a risk level: low, medium or high. Some tools work out their risk from the arguments. For example, a shell command is low risk inside the bot's workspace folder, and high risk when it deletes things outside it. Tools from apps you connect get a level per tool. On the connection's page you can set each tool to **Read-only**, **Makes changes** or **Always asks**, which map to low, medium and high risk. See [Connections](/guide/connections). Buying a call to a paid data service asks under **Ask for risky actions** whatever its risk, because it costs money, and the approval shows the price. Image and video generation and changes to your calendar don't ask by default; your credits and the bot's budget still apply. Making spoken audio does ask first under **Ask for risky actions**. ## Approvals When a bot needs your OK, the run pauses and an approval request appears in two places: - The chat, as a card under the bot's message. - **Needs you**, at the top of **Chats**, for every bot you can use. It shows a count when something is waiting. Each request shows the bot, the tool, its risk (**Low risk**, **Medium risk** or **High risk**) and the arguments it wants to use, with secrets removed. To answer it: 1. Open the card in the chat, or tap **Needs you** at the top of **Chats**. 2. Read what the bot wants to do. 3. Tap **Approve**, **Deny** or **Always Allow**. | Choice | What happens | | --- | --- | | **Approve** | The step runs and the bot carries on. | | **Deny** | Only that step fails. The bot is told, and it continues without it. | | **Always Allow** | The step runs, and Casama adds an action rule so this bot runs this tool without asking from now on. | | No answer for 24 hours | The request expires and is treated like a deny. | Once answered, the card folds into one quiet line in the chat, such as "Allowed: Making an image". Requests for a key, a sign-in code, a takeover or device access fold the same way. A run that waits for approval costs nothing while it waits, and it survives server restarts. Anyone who can use the bot can answer. If someone already answered, you see **This request was already decided or has expired.** ### Push notifications for approvals The person who started the run and the bot's owner both get a push notification. Approvals from a chat or voice call come through even during quiet hours, because someone is waiting in the conversation. Approvals from routines and other background work wait until your quiet hours end. See [Notifications and attention](/guide/attention). You can also approve or deny from an AI app connected over MCP, if your workspace allows it. See [Connect AI apps to Casama](/guide/mcp). ## Action rules Action rules decide per action instead of per bot. Use them when one autonomy level doesn't fit, for example "send email to my own company without asking, but always ask before emailing anyone else." ### Add a rule 1. Open **Bot profile → Action rules**. 2. Tap **Add a rule**. 3. Under **When the bot is**, pick a category: **Sending messages**, **Payments**, **Deleting**, **Publishing**, **Sharing and invites** or **Signing in**. 4. Under **It should**, pick a behavior. 5. Optionally limit it with **Only to these domains (comma separated)** or **Up to this amount**. 6. Turn on **For every bot in the workspace** to make it a workspace rule. 7. Tap **Save**. | Behavior | What it does | | --- | --- | | **Go ahead** | Runs without asking, whatever the autonomy. | | **Go ahead within limits** | Runs without asking only when every recipient is in an allowed domain (subdomains count) and the amount is under the limit. Outside the limits, the rule doesn't apply. Needs at least one limit. | | **Ask me first** | Always asks, even under **Act on its own**. | | **Hand it to me to finish** | The bot never does the step itself. It prepares everything and asks you to finish, taking over its computer screen if it's working there. | Each rule shows a plain-language summary, such as "Sends messages to anyone at example.com without asking". The list groups rules by category, with tool rules (from **Always Allow**) under **Specific tools**. ### Who can change rules - Workspace rules need a workspace owner or admin. - A bot's own rules need someone who manages that bot. - A bot can add and remove its own rules (never workspace rules). A more careful rule (**Ask me first**, **Hand it to me to finish**) applies at once. A rule that lets it skip approval always asks you first, and a bot can never allow payments or sign-ins this way. See [Bots that change their own setup](/guide/bots#bots-that-change-their-own-setup). Deleting a rule is recorded in the workspace's audit log. ### Which rule wins 1. Casama finds the rules that match the call: by exact tool, by tool group (for example every tool from one connected app), or by category. 2. A rule with limits only matches when the call is within them. 3. The most specific rule wins: the bot's own rule over a workspace rule, then tool over group over category, then a rule with limits over one without. 4. On a tie, **Ask me first** or **Hand it to me to finish** wins. 5. If no rule matches, the bot's autonomy decides. Categories come from the tool's own declaration, or from words in its name (for example `send`, `email`, `pay`, `delete`, `publish`, `share`, `password`). Recipients and amounts are read from argument fields such as `to`, `cc`, `recipients` and `amount`. Rules by exact tool or tool group, and limits by exact recipient, can be created through the API. See [API](/develop/api). ## Actions that never ask Some actions change only the bot's own state inside Casama, where you can see and undo them. These never ask for approval under any autonomy level, including **Ask before acting**: - Its notes (memory) and its own routines. What a routine then does still goes through approvals. One exception: once a run has read untrusted content (below), creating or changing a routine asks first under **Ask before acting** and **Ask for risky actions**, so text in a web page or email can't schedule work for later. - Messages, notifications and cards for you. - Board tickets, comments and suggestions. - Housekeeping: loading a skill, making a checkpoint, organizing the sidebar. Anything that reaches outside Casama or costs money still follows the normal rules: sending through chat apps or email, web requests, the shell, browsing, payments, publishing or sharing pages, calls, and creating, archiving or rewriting bots. An **Ask me first** rule still wins over a self-only action. ## Actions that always ask or always go to you | Action | Rule | | --- | --- | | Paying with a virtual card | Always asks, whatever the autonomy or rules. **Always Allow** doesn't apply. See [Payments](/guide/payments). | | Changing a password or two-step settings | Always handed to you to finish. A rule can't change this. | | High-risk actions on your own computer | Always ask, even under **Act on its own**. See [Your own computer](/guide/companion). | ## Untrusted content Web pages, emails, files and output from connected apps can contain text written to trick a bot. Casama protects against this in three ways: - Untrusted content reaches the model inside labeled blocks, and the bot is told never to follow instructions found inside them. - Under **Ask for risky actions**, once a run has read untrusted content, medium-risk actions that send data out of Casama ask for approval until you approve something again. These are web requests that post or change data, tools from connected apps, and questions to linked bots. Reading the web, publishing inside the workspace and the like still run. - Secrets never reach the model. Bots use placeholders such as `{{secret:NAME}}`, and Casama fills in the value only when the request goes to a host the secret allows. See [Privacy and security](/guide/privacy). ## The loop guard A bot that keeps retrying the same thing wastes your budget. On top of the step, time and budget limits, each run has a loop guard: - The same action with the same arguments a third time in one run isn't run. The bot is told it already tried twice and to change approach or say what's blocking it. Looking-only actions (reads, lists, searches, snapshots, screenshots) are exempt, since they repeat normally. - Five failed steps in a row (errors, refusals or skipped repeats) end the run. You see a message that the bot kept hitting the same problem and stopped to save your budget. ## Checkpoints as a safety net Before a shell command that deletes data (such as `rm -rf`, `git reset --hard` or uninstalling packages), Casama saves a checkpoint of the bot's computer. Bots can also make checkpoints themselves before risky work. Restoring a checkpoint puts the computer's files back as they were. See [Computers](/guide/computers). ## Limits - The app adds action rules by category only. Rules for a specific tool come from **Always Allow**; rules for a tool group or exact recipients need the API. - Approvals can't be answered from the CLI. Use the app, or an AI app connected over MCP. - Checkpoints are automatic only before destructive shell commands, not before every high-risk action. ## Related - [Bots](/guide/bots) - [Notifications and attention](/guide/attention) - [Usage, budgets and plans](/guide/usage) - [Computers](/guide/computers) - [Connections](/guide/connections) # Bots working together Bots can split up work, hand tasks to each other, manage other bots, and talk to bots outside your workspace. Use this when one job is too big for one context, when a specialist bot should take part of it, or when your bot needs something from a contact's bot. ## Subagents A bot can start a subagent: a short-lived copy of itself with a fresh context, for a self-contained task such as researching one question. The subagent returns a summary, and the parent bot carries on. - **Budget:** 20% of what the parent run has left, unless the bot asks for less. - **Time limit:** 10 minutes by default, up to an hour. - **Tools:** the same as the parent's, or fewer if the bot narrows them. For work that splits into independent parts, such as researching several companies, a bot can start up to 5 subagents at once and wait for all of them. Together they get 40% of what the parent run has left, in equal shares, and the bot gets every summary back in order, ready to merge into one table. Subagents show on the parent run's timeline, with their status and summary. ## Hand a task to another bot A bot can delegate a task to another bot in your workspace by name, then wait for its result. For example, a planner bot can ask a writer bot for a draft. - The task appears in the other bot's chats as a new conversation titled "Task from" and the delegating bot's name. - The other bot works under its own settings and approvals, with a budget taken from the delegating run, as with subagents. - Delegation can go at most 3 levels deep. A bot can't hand a task back to a bot that's already working on the same chain, so loops are refused. In a group chat, bots can also @mention each other. See [Group chats](/guide/group-chats). ## Turn off bot-to-bot messages Owners and admins can stop bots from talking to each other. 1. Open **Settings** → **Workspace settings**. 2. Turn off **Bots can talk to each other**. When it's off: - A bot's @mentions of other bots in a group chat start nothing. The chat shows an info line naming the bots that weren't told. - Delegating to another bot fails, and the failure shows on the timeline. - Subagents still work, and people can still @mention bots. The switch is on by default, and changes are recorded in the audit log. ## Bots that manage bots A bot can list, create, update and archive bots, and organize the sidebar into folders. It can also manage another bot's routines. | Action | Risk | | ---------------------------- | -------------------------------------------- | | List bots | Read-only | | Organize folders | Low | | Update a bot | Medium; high when it changes autonomy or budget | | Create a bot | High | | Archive a bot | High (a bot can't archive itself) | High-risk actions ask first under the default autonomy. See [Autonomy and approvals](/guide/autonomy). A bot can never give any bot, itself included, more than it has: - No higher autonomy level than its own. - No larger per-run or daily budget than its own. - No more tools. A new bot starts with no connections unless the creating bot copies its own. A new bot copies the creating bot's model settings, belongs to the person the bot is working for, and counts toward the workspace's bot limit. Every action is in the audit log. ### Undo a change Every change to a bot's settings is kept, with who made it: a person or a bot. 1. Open **Bot profile** → **Settings history**. 2. Find the change and tap **Restore**, then confirm. The current settings stay in the history, so you can undo the restore too. ### Folders and archived bots - **Bot profile** → **Folder** moves a bot into a folder in the sidebar. - **Bot profile** → **Archive Bot** hides a bot from the sidebar. Archived bots can't run and don't count toward the bot limit. - To restore one, open **Archived bots** from the bot list and tap **Bring Back**. ## Linked bots Link your bot with a trusted contact's bot, so they can ask each other for things, like finding a dinner slot. Each bot answers under its own person's rules and shares only what the request needs. Both of you see every exchange. ### Link two bots 1. Open **Bot profile** → **Advanced** → **Linked bots** and tap **Invite a contact**. 2. Enter your **Contact's name**, the name your bot will use for them. 3. Copy the invite and send it to your contact. It works once, for 7 days. 4. Your contact opens **Linked bots** on one of their bots, taps **Accept an invite**, pastes it and enters your name. Until then the link shows "Waiting for your contact to accept". Inviting and accepting are the two approvals: nobody is linked without both. Your contact can be on the same Casama server or a different one. ### How asking works - Your bot sends a request to the linked bot by the contact's name. Sending is a medium-risk action in the send category, so it follows your bot's approval rules. - The other bot receives it as a request from your bot on your behalf. It runs as its owner, with their approvals, rules and budgets, so it may wait for its person to approve. - On the same server, your bot waits up to 5 minutes for the answer. - Every exchange is listed under **Exchanges** on both sides, and the receiving person gets a notification. Each of you sees only your own side. To end a link, tap **Unlink**. It ends for both of you, on both servers. ## Agent-to-agent (A2A) A2A is an open protocol for AI agents to give each other tasks. Casama speaks A2A 1.0 in both directions. ### Let outside agents use a bot 1. An owner or admin opens **Settings** → **Workspace settings** and turns on **Agent-to-Agent (A2A)**. It's off by default. 2. Someone who manages the bot opens **Bot profile** → **Advanced** → **Publish as an A2A Agent** and turns it on. 3. Copy the **Agent card** address and give it to whoever runs the outside agent. 4. The outside agent also needs a workspace API key, created under **Connect AI Apps** in workspace settings. See [Connect AI apps](/guide/mcp). The outside agent acts as the person who owns the API key, and that person must be able to use the bot. Each task becomes a run with the bot's usual approvals, budgets and rules, and is recorded in the audit log. Sending the same context again continues the same conversation. If a task is waiting for an approval, the outside agent sees it as still working. Turning the workspace switch off unpublishes every bot. ### Give a bot an outside agent 1. Open **Settings** → **Integrations**, expand **Advanced** and choose **Custom Server**. 2. Set **Type** to **AI agent (A2A)**. 3. Enter a **Name**, the **Agent address or agent card URL**, and an optional **Access token**. 4. Tap **Save**, then give it to the bot from the **Apps** tile on its profile. The bot gets one tool for that agent, described from the agent's card. It waits up to 10 minutes for the task to finish, then returns the answer, or says the agent needs more input. Calling an outside agent is a medium-risk action. For the protocol details, see [Agent-to-agent (A2A)](/develop/a2a). ## Limits - A2A streaming and push notifications aren't offered yet. Outside agents wait for a reply, or poll for a long task. - A bot can't grant another bot more autonomy, budget or tools than it has, even with your approval. ## Related - [Group chats](/guide/group-chats) - [Autonomy and approvals](/guide/autonomy) - [Apps and connections](/guide/connections) - [Agent-to-agent (A2A)](/develop/a2a) - [Sharing bots](/guide/sharing) # 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 | Part | What it is | | --- | --- | | Name and icon | A cloud mascot or initials, shown in the sidebar and on every reply. | | Instructions | Standing instructions (its system prompt): its role, how it works, its style and limits. | | Model | A 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. | | Autonomy | How often it asks before acting. See [Autonomy and approvals](/guide/autonomy). | | Budget | A cost cap per run and per day. See [Budgets and run limits](#budgets-and-run-limits). | | Computer | Where it runs commands, browses and keeps files. See [Computers](/guide/computers). | | Memory, skills, routines | What 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](#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 \ --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](/develop/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](/guide/usage#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: | Provider | Notes | | --- | --- | | OpenRouter | Recommended. One key reaches models from many providers. | | OpenAI | Its first OpenAI key also gives the workspace embeddings for memory and knowledge search. | | Anthropic | | | Google Gemini | | | xAI | | | OpenAI-compatible server | Ollama, LM Studio, vLLM or any server with an OpenAI-style API. Needs a **Base URL**. Its calls are recorded in Usage at $0. | | ChatGPT | Your 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](/self-hosting/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 `/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: | Key | Default model | Model id | | --- | --- | --- | | OpenRouter | DeepSeek V4.1 Flash 1017 | `deepseek/deepseek-v4.1-flash-1017` | | OpenAI | GPT-6 Luna | `gpt-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. | Group | Personas | | --- | --- | | Work | Assistant, Briefing (morning briefing routine), Support, Sales, Product, Ops (hourly health check routine), Inbox triage (weekday morning inbox routine), Outbound prospector, Recruiting screener, Coordinator | | Research | Researcher (research-report skill), Analyst, Tutor | | Build | Coder (code-change skill), QA, Designer, Bug triage | | Create | Writer, Marketer, Social (weekly content plan routine), Translator | | Life | Travel, Budget, Coach, Chef, Expense matcher | The Coordinator plans bigger jobs, splits them into tickets and hands them to other bots. See [Bots working together](/guide/bots-together). More personas come from the [open gallery](https://gallery.casama.ai/#bot), 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](https://github.com/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](/guide/chat) 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](/guide/routines#check-ins) turned on, so it can reach out when something needs you. - Run the [setup interview](#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](/guide/library)). Below them: | Row | What it does | | --- | --- | | **Folder** | Groups bots in the sidebar. | | **Sharing** | Who can chat with, edit or manage it. See [Templates, sharing and import](/guide/sharing). | | **Computer** | Which computer the bot uses. **Automatic** means its private computer if it has one, otherwise the team computer. | | **Voice** | Its read-aloud voice and the tools it has on calls. See [Voice and calls](/guide/voice). | | **Knowledge** | Documents it can search and cite. See [Memory and knowledge](/guide/memory). | | **Check-Ins**, **Notifications from this bot** | Its morning brief and suggestions, and its quiet hours. | Under **Advanced**: | Row | What it does | | --- | --- | | **Action rules**, **Watchers** | What it may do without asking, and what it keeps an eye on. | | **Plugins** | Skills and tools from plugin packages. See [Plugins](/develop/plugins). | | **Chat apps**, **Linked bots**, **Publish as an A2A Agent** | Outside chat apps, trusted contacts' bots and outside agents. | | **Share as Template** | A file or link with its instructions, skills and routines. | | **Activity** | Every run, step by step. | | **Replays** | Recorded steps it runs without thinking. See [Teach by showing](/guide/teach#replays). | | **Settings history** | Every change to its settings and who made it, with **Restore These Settings**. | | **Run Setup Again** | Starts a new setup interview. | At the bottom: | Row | What it does | | --- | --- | | **Delete All Chats** | Deletes 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](/guide/chat#delete-a-chat). | | **Archive Bot** | Removes 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. | Limit | Default | Error code | | --- | --- | --- | | Cost of one run | $1 | `budget_exceeded` | | A bot's cost per day (UTC) | $10 | `daily_budget_exceeded` | | Workspace monthly cost quota | None | `quota_exceeded` | | Model steps in one run | 40 | `max_steps_exceeded` | | Time for one run | 30 minutes | `wall_time_exceeded` | | No model set | | `no_model_configured` | On hosted plans, a run can also stop with `out_of_credits` or `computer_hours_exceeded`. See [Usage, budgets and plans](/guide/usage) 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 can | How 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-server` | Always asks | | Start using one of the workspace's connections, optionally only some of its tools | Always asks | | Suggest a plugin | Shows 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 itself | **Ask 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 knowledge | Like any other medium-risk action | | Stop notifying you, or set its own quiet hours | Quieter applies at once. Going back to your usual hours asks | | Remove a server it added, stop using a connection, remove its own knowledge | Never 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. ## Related - [Chatting with a bot](/guide/chat) - [Autonomy and approvals](/guide/autonomy) - [Usage, budgets and plans](/guide/usage) - [Templates, sharing and import](/guide/sharing) - [CLI](/develop/cli) # Casama Link Casama Link connects a Casama server you run yourself to a Casama Cloud workspace. It used to be called Casama Connect, and its paid part Cloud Connect. It has two parts. You can use either one, or both. | Part | What it gives your server | Cost | Where to start | | --- | --- | --- | --- | | **Remote access** | An `https://….casama.link` address your phone can reach with no domain or open ports, sign-in by scanning a code, and notifications in the apps from the App Store and Google Play | Free on every plan. Live video away from the computer comes with Plus and up. | [Use your server on your phone](/self-hosting/remote-access) | | **Cloud computers and credits** | Bot computers that run on Casama Cloud, and model calls paid from Casama Cloud credits | Billed to the cloud workspace | [Cloud computers and credits](/self-hosting/casama-link-cloud) | Your bots, chats, memory and files stay on your server either way. Casama Cloud keeps a record of the linked server (its name, its address and when it last checked in) and passes on what the part you use needs: notifications for remote access, computer commands and model calls for the paid part. ## Which one do I need? - **My server runs on my Mac or PC, and I want to use it from my phone.** Remote access. Run `casama selfhost remote on`, or choose **Use on Your Phone** under **Settings → Casama Link** in the desktop app. - **My server has its own domain, but notifications don't reach the store apps.** Remote access's notification part alone: `casama selfhost remote link`. See [Link without an address](/self-hosting/remote-access#link-without-an-address). - **I don't want to host bot computers or manage model keys.** Cloud computers and credits. - **My server runs on a platform without Docker (Render, Railway, DigitalOcean App Platform).** Cloud computers give its bots somewhere to run. See [Other ways to deploy](/self-hosting/#other-ways-to-deploy). ## Keys Every linked server holds one key (`kcc_…`) in `CASAMA_CLOUD_KEY`. What the key may do depends on how it was made: | Made by | Can do | Spends credits | | --- | --- | --- | | Linking (`casama selfhost remote on` or `remote link`, or the desktop app) | Hold an address, send notifications | No | | **New Casama Link Key** in Casama Cloud's Billing screen | Cloud computers, model credits | Yes | | The API (`POST /v1/orgs/{id}/link/keys` with `scopes`) | Any mix of the four | If it includes computers or models | Workspace owners and admins see their linked servers and keys in Casama Cloud under **Settings → Billing**, in **Charges by server, Casama Link servers and keys**. Revoking a key stops that server from using it at once, and removes its address if it had one. ## Related - [Use your server on your phone](/self-hosting/remote-access) - [Cloud computers and credits](/self-hosting/casama-link-cloud) - [Self-hosting](/self-hosting/) - [Usage, budgets and plans](/guide/usage) - [Privacy and security](/guide/privacy) # Chat apps Chat apps let people reach a bot from the messaging tools they already use: Telegram, email, SMS, Slack, WhatsApp, Messenger, Feishu, iMessage, Microsoft Teams and Discord. The bot answers in the same thread, and every conversation also shows up in the Casama app. Linear and Jira work the same way: assign an issue to the bot and it replies with a comment (see [Give a bot a Linear or Jira issue](#give-a-bot-a-linear-or-jira-issue)). ## How it works - Each chat app is connected to one bot. - A bot only answers people on the chat app's **Allowed senders** list. Messages from anyone else get no reply and are logged in the chat app's **Activity** as "Ignored: not on the allowed list". - Each outside thread becomes one Casama conversation, titled with the app and the sender or subject, such as "Telegram: Ana". Follow-up messages in that thread continue the same conversation. - Each message reaches the bot prefixed with where it came from, such as `(Telegram, from Ana)`, and starts a run. When the run finishes, its final reply goes back to the thread. - If an app delivers the same message twice (Slack retries after a few seconds, for example), the bot answers it once. - The conversation belongs to the person who connected the chat app, and runs act for them. That person sees these chats in the app. ## Connect a chat app You need to manage the bot to connect a chat app. 1. Open the bot, then **Bot profile** → **Advanced** → **Chat apps**. 2. Tap **Connect a chat app**. 3. Choose the **App** and give the connection a **Name**. 4. Paste the credentials from the app's developer settings (see the table below). They're stored encrypted and never shown again. 5. Under **Allowed senders**, add one per line: email addresses (or `*@example.com` for a whole domain), phone numbers, or user ids. 6. Tap **Add**. 7. Casama shows the **Webhook address**. Paste it into the app's webhook settings. Telegram is the exception: Casama sets its webhook for you. | App | What you paste | Where the webhook goes | | --------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------- | | Telegram | **Bot token** from @BotFather | Set automatically | | Email | **Email address**, Resend **API key**, and the webhook's **Signing secret** | A Resend inbound webhook for received email | | SMS | Twilio **Phone number**, **Account SID** and **Auth token** | The number's incoming-message webhook in Twilio | | Slack | **Bot token** and **Signing secret** | Event Subscriptions request URL, subscribed to `message.im` and `app_mention` | | WhatsApp | **Phone number ID**, **Access token** and **App secret** from the Cloud API | Meta webhook callback URL, with the **Verify token** | | Messenger | **Page access token** and **App secret** | Meta webhook callback URL, with the **Verify token** | | Feishu | **App ID**, **App secret**, **Encrypt key** and **Verification token** | The app's event subscription request URL | | iMessage | Nothing; pick your **Mac** | None | | Microsoft Teams | The Azure bot's **App ID** and client secret (**App secret**) | The Azure bot's messaging endpoint | | Discord | **App ID** (application id), **Public key** and **Bot token** | The application's Interactions Endpoint URL | | Linear | **The bot's user ID in the tracker**, an **API key** and the webhook's **Signing secret** | A Linear webhook for issues and comments | | Jira | **Site address (https://…)**, **Account email**, **The bot's user ID in the tracker**, an **API key** (API token) and the webhook's **Signing secret** | A Jira webhook for issue created, issue updated and comment created | For WhatsApp and Messenger, Casama generates a **Verify token** for Meta's setup and shows it once, right after you connect. Copy it then. Each app's requests are checked before anything happens: Telegram's secret token, the Svix-style signature on email, Twilio's signature on SMS, Slack's signed requests, Meta's `X-Hub-Signature-256`, Feishu's request signature, Microsoft's signed token on Teams, Discord's Ed25519 signature, `Linear-Signature` and Jira's `X-Hub-Signature`. A request that fails the check is refused. Feishu must have an encrypt key set; Casama decrypts its messages. ::: tip Not sure what a sender's id looks like? Ask them to message the bot first. The message shows in **Activity** as ignored, with their id. Add that id to **Allowed senders**. ::: ## Allowed senders Matching is exact and ignores case. `*@example.com` matches any email address at that domain. | App | Use | | --------- | ---------------------------------------------------------------------- | | Telegram | The person's numeric Telegram user id | | Email | Their email address, or `*@example.com` | | SMS | Their phone number in international format, such as `+13125550123` | | Slack | Their Slack user id | | WhatsApp | Their WhatsApp number as Meta sends it: digits only, no `+` | | Messenger | Their page-scoped sender id | | Feishu | Their open id | | iMessage | The phone number or email address they message from | | Microsoft Teams | Their Microsoft Entra object id | | Discord | Their Discord user id | | Linear | Their Linear user id | | Jira | Their Atlassian account id | To change the list later, tap the chat app on the **Chat apps** screen, edit **Allowed senders** and tap **Save**. ## Threads and replies | App | One conversation per | How the reply goes back | | --------- | ------------------------------------------------------------ | --------------------------------------------- | | Telegram | Chat | A message in the same chat | | Email | Sender plus subject (`Re:` and `Fwd:` are ignored) | A reply email with `Re:` and threading headers | | SMS | Phone number | A text message | | Slack | Slack thread | A reply in that thread | | WhatsApp | Phone number | A WhatsApp message | | Messenger | Sender | A Messenger message | | Feishu | Chat | A message in the same chat | | iMessage | Handle | An iMessage from your Mac | | Microsoft Teams | Teams chat or channel conversation | A reply in the same conversation | | Discord | Channel | A reply to the `/ask` command, or a channel message after 15 minutes | | Linear | Issue | A comment on the issue | | Jira | Issue | A comment on the issue | Long replies are sent in parts, split at a paragraph, line, sentence or word, so nothing is cut off. Each part fits the app's limit: 1,600 characters on SMS, 2,000 on Messenger and Discord, 4,096 on Telegram and WhatsApp, 10,000 on Feishu, 25,000 on Teams, 39,000 on Slack, 30,000 on Jira and 50,000 on Linear. When someone sends a photo, file or voice note, the bot gets the caption, if there is one, and a note that the attachment doesn't come through yet, so it can ask them to describe it or send it in the Casama app. If a reply can't be sent, the error shows on the chat app in the list and in its **Activity**. ## Bots sending first A bot can start a new message through one of its chat apps, for example to tell you a long job is done. It can only message people on that chat app's allowed list, and sending is a high-risk action, so under the default autonomy it asks you first. See [Autonomy and approvals](/guide/autonomy). ## Routines on messages A routine can start when a matching message arrives. Filter by chat app, sender (`*@example.com` works), subject or message text. Without a sender filter, a routine only hears people on the chat app's allowed list. With one, it also hears that sender when they aren't on the list: for example, a routine can file every invoice a vendor emails, although the vendor can't chat with the bot. A message that starts a routine isn't also answered. In the routine sheet, choose **Messages**. See [Routines](/guide/routines). ## Slack In Slack, people can message the bot directly or @mention it in a channel. The mention is removed before the bot reads the message. An eyes reaction on the message shows it arrived. When a run started from a Slack thread needs your approval, the request is also posted in that thread with **Approve** and **Deny** buttons. Only people on the chat app's allowed list can press them; the decision counts as made by the person who connected the chat app, and the message then says who approved or denied it. The usual notification and the card in the app still work. To use the buttons with your own Slack app, turn on **Interactivity** in the Slack app's settings and set its request URL to the **Webhook address** followed by `/interact`. Give the bot token the scopes `app_mentions:read`, `chat:write`, `im:history`, `im:read` and `reactions:write`. ### Install Casama's Slack app A server can run its own Slack app, so people connect Slack with one click instead of pasting a bot token. Whoever runs the server registers the Slack app and sets `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET` and `SLACK_SIGNING_SECRET`. The Slack app's addresses are, on the server's public API address: | Slack setting | Address | | -------------------------- | ---------------------- | | OAuth redirect URL | `/hooks/slack/oauth` | | Event Subscriptions | `/hooks/slack/events` | | Interactivity request URL | `/hooks/slack/interact` | `GET /v1/channels/slack/install?bot_id=…` returns Slack's sign-in address. After you approve it in Slack, the chat app is made for that bot, with you on its allowed list. Each Slack workspace talks to one Casama bot through the server's app; installing again for another bot moves it. Without those settings the request answers that the server has no Slack app, and you connect your own Slack app with a bot token as above. The app has no install button yet. ## Microsoft Teams People message the bot in Teams chats and channels. In a channel, @mention it; the mention is removed before the bot reads the message. 1. In Azure, create an Azure bot and a client secret for it. 2. In Casama, connect **Microsoft Teams** with the bot's **App ID** and the client secret as **App secret**. 3. Paste the **Webhook address** as the Azure bot's messaging endpoint, and add the Teams channel to the Azure bot. ## Discord Discord only delivers ordinary messages to bots that keep a live connection open, which a webhook server doesn't. So people talk to the bot through a slash command, such as `/ask`, with one text option for the question. 1. In the Discord Developer Portal, copy the application's **Application ID** and **Public key**, and the bot's token. 2. In Casama, connect **Discord** with those as **App ID**, **Public key** and **Bot token**. 3. Paste the **Webhook address** as the application's **Interactions Endpoint URL**. 4. Register a slash command for the application with one string option. Discord shows "thinking…" while the bot works. The reply answers the command if it's ready within 15 minutes, and otherwise arrives as a message in the channel. ## Give a bot a Linear or Jira issue Connect Linear or Jira as a chat app and you can hand a bot an issue the way you would a teammate. - **Assign an issue** to the tracker user that stands for the bot, or create it assigned. The bot starts work with the issue's title and description. - **Comment** on an issue the bot holds to continue the conversation. Each issue is one Casama conversation, so the bot keeps the context. - **The bot's reply** is posted as a comment on the issue. Changes the bot makes itself are ignored, so it doesn't answer its own comments. People who assign issues or comment need to be on the **Allowed senders** list, by their Linear user id or Atlassian account id. ### Linear 1. Create a Linear user for the bot and copy its user id. Create a personal **API key** for that user; the bot comments with it. 2. In Linear's settings, add a webhook for **Issues** and **Comments** pointing to the **Webhook address**, and copy its signing secret. 3. In Casama, connect **Linear** with **The bot's user ID in the tracker**, the **API key** and the **Signing secret**. ### Jira Cloud 1. Create an Atlassian account for the bot and an API token for it. 2. In Casama, connect **Jira** with your **Site address (https://…)**, the bot account's **Account email**, its account id as **The bot's user ID in the tracker**, the API token as **API key**, and a **Signing secret** you make up. 3. In Jira's system settings, add a webhook to the **Webhook address** with that secret, for issue created, issue updated and comment created. The bot doesn't move the issue's status as it works; it says where things stand in its comment. To have a bot use Linear or Jira as a tool instead (search issues, file new ones), connect the app from [Apps and connections](/guide/connections). ## iMessage iMessage has no bot API, so your own Mac does the work through the desktop app. 1. On your Mac, open the desktop app and turn on **Use this computer for bots**. 2. Under **What bots may do**, allow **Messages (iMessage)**. 3. Give the desktop app Full Disk Access in macOS System Settings, so it can read Messages. 4. In the bot's **Chat apps**, connect **iMessage** and pick your **Mac**. Your Mac reads new messages and sends replies through Messages. Casama checks for new messages every minute. The first check only takes a starting point, so old messages are never answered. Only the Mac's owner can connect it, and only bots allowed on that Mac can use it. See [Your own computer](/guide/companion). ## Manage a chat app On the **Chat apps** screen: - Use the switch next to a chat app to turn it off and on. - Tap a chat app to see its **Webhook address**, edit **Allowed senders**, and read its **Activity**: answered, sent, started a routine, ignored or failed. - Tap **Disconnect** to remove it. Its saved credentials are deleted. ## Limits - Text only: attachments and images aren't passed on yet. The bot is told one was sent. - Feishu has no one-click install. Slack has one only on servers that run their own Slack app, and only through the API for now. - Approval buttons are in Slack only. In Teams and Discord, approvals arrive in the app as usual. - On Discord, the bot hears only its slash command, not ordinary messages. - Group chats on WhatsApp and iMessage aren't supported. - iMessage needs your Mac to be on, with the desktop app running. - The adapters follow each provider's public docs and have been tested against stand-ins, not yet against every live provider. Teams and Discord have been tested with signed test requests only. - If your server sits behind a proxy, set `PUBLIC_API_URL` so signatures and webhook addresses use your public address. See [Configuration](/self-hosting/configuration). ## Related - [Chat](/guide/chat) - [Routines](/guide/routines) - [Your own computer](/guide/companion) - [Autonomy and approvals](/guide/autonomy) - [Voice and calls](/guide/voice) # Chatting with a bot A chat is where you give a bot work and see it happen: its replies, each step it takes, the files it makes and any questions it has for you. Each bot keeps its own conversations, and what it learns in one chat it can recall in the others. ## Start a conversation 1. Select a bot in the sidebar (on a phone, tap it in **Chats**). 2. Type in the message field and send. Opening a bot takes you to your **General** chat with it. That's where you talk day to day, and where the bot reaches out: morning briefs, routine results and suggestions land there. Work that needs its own space runs in a **topic**: - **Do it** on a suggestion opens a topic where the bot does the work, then posts a one-line result back in General with a link to the topic. - To start a topic yourself, select **New topic**. - Topics with something going on show as chips at the top of General. **Needs you** comes first, then those the bot is working on. - **All topics** lists every one. Topics idle for a week move under **Older**. - Inside a topic, the **General** chip takes you back. New topics get a title from their first messages. To rename or pin a topic, open **Topics** from the chat's **More** menu (**…**) and use the menu on its row: **Rename**, **Pin** or **Unpin**. Pinned topics stay near the top, after General and anything that needs you, and never move under **Older**. General can't be renamed or pinned. Long chats stay quick and cheap: once a chat's history passes about 16,000 tokens, the bot keeps the most recent part word for word and a summary of the rest. An open chat stays live on every device. A message you send from your phone shows up, with the bot's reply streaming in, on your laptop with the same chat open, and the same goes for a teammate in a shared chat or a routine that posts into it. The bot list updates live too, so a bot made on one device appears on the others. On the desktop and the web, **Enter** sends and **Shift+Enter** starts a new line. On phones, use the send button. A message you haven't sent yet is kept as a draft, on the web too, until you send it or sign out. ## While the bot works A bot first says in one short line what it's about to do, then works without running commentary. Each tool it uses (a command, a file, the browser, a web search) shows as a step in the chat, and longer runs collapse earlier steps behind **Show … earlier steps**. Any text the bot writes between steps stays in the thread as its own message. - **Stop** ends the current run. It shows in place of **Send** while the message field is empty. A stopped request stays stopped: the bot won't pick it back up on your next message unless you ask again. - **Activity** (open the **More** menu, then **Bot profile** → **Advanced** → **Activity**) lists every run of the bot. Each run opens a **Run timeline** with every event, its cost and tokens. - If a run fails, the chat says why in plain words, with **Details** and **Open run timeline**. - If a run uses all its steps or time, the bot still replies with what it got done, what blocked it and what it suggests. - Ask a bot what it's doing from another chat and it knows about its work elsewhere. ### Send more while it works You don't have to wait. In a chat with one bot, start typing while it works and **Stop** turns into **Send**. Your message joins the run in progress: before its next step the bot reads it, marked as sent while it was working, and decides whether to fold it in, switch to it, or finish first. If the run ends before it sees your message, the message gets its own follow-up run. Group chats work differently: every message there starts new runs for the bots it wakes. See [Group chats](/guide/group-chats). ## Attach files 1. Select **Attach**, then **Files**, **Photo library** or **Take photo**. On the desktop and the web you can also drop files onto the chat, or paste a picture with **Cmd+V** (macOS) or **Ctrl+V**. On Android, you can share a picture, video or file into Casama from another app. 2. Files upload straight away to `~/workspace/uploads` on the bot's computer. Send waits until they finish. 3. Write your message and send. | Rule | Limit | | --- | --- | | Files per message | 10 | | Size of one file | 25 MB | | Images also shown to vision models | First 4, up to 5 MB each | Every model sees the list of attached files (path, name, type and size) and can open them on its computer. **Photo library** is available on mobile and macOS, and **Take photo** on mobile. A bot with no computer can't take attachments. Files go to the bot's default computer, or else its own computer, or else the team computer; never to another computer in the workspace. ## Files the bot shares When a bot makes a file, it links it by its path on the bot's computer, like `[report.md](workspace/report.md)`. Those files appear under the reply: images (PNG, JPEG, GIF, WebP) as thumbnails, and documents, data, code, archives, audio and video as file cards, up to 8 per reply. Images and videos a bot generates show under its reply by themselves, even when the bot has no computer. Videos on a bot's computer show a first frame and their length once the computer is awake; looking at them never wakes a sleeping computer. Tap a file to open the preview, then choose **Open**, **Save** or **Share**. Files without a preview can still be opened or saved. Everything a bot makes on its computer also stays in its **Files**; see [Computers](/guide/computers). Files a reply links to are also kept in the [Library](/guide/library). If a bot's reply links to a file that isn't there, Casama makes the bot fix the reply before you see it. A bot can also make spoken audio, such as a voiceover, which plays under its reply. See [Voice and calls](/guide/voice#bots-that-make-spoken-audio). ## Interactive cards For choices and short forms, a bot can show an interactive card in the chat instead of asking you to type: buttons, option chips, a few fields. The setup interview and the welcome chat use them. - Tap a button or fill in the fields and submit. Your answer is sent as a normal message that sums up what you chose. - A list of answers is lettered (A, B, C…). A card with two or more questions asks them one at a time: answer and tap **Next**, or **Skip**; the last step has the card's own button. - An answered card stays in the thread, dimmed and marked **Sent**. - A bot shows one card at a time and waits for your answer before going on. - Links on a card open in your browser, and only for web addresses. - If a card can't be drawn, you see "This part of the reply couldn't be shown." Cards use the open A2UI protocol and are drawn natively by the app, in its own theme. Showing a card never needs your approval. ## Use a skill with / To make sure a bot follows a particular skill, attach it to your message. 1. Type `/` in an empty message field. The bot's enabled skills appear under **Attach a skill**. 2. Keep typing to filter, then pick a skill. It shows as a chip above the field. 3. Write your message and send. The bot loads the skill's instructions before it starts. You can attach up to five skills to one message. See [Skills](/guide/skills). ## Edit and resend You can change a message you sent and rerun the conversation from that point. 1. Long-press your message (or right-click it with a mouse) and choose **Edit**. 2. Change the text and send. The bot answers the new version. The original version and its replies are kept. Messages with more than one version show arrows (**Previous version**, **Next version**) to switch between them. Attachments and skills from the original come along. Only the shown version reaches the model. Edit works on your own messages in chats with one bot, and not while a run is going. ## Message actions With a mouse, hover over a message to see its actions in a small bar under it. Right-click adds them to the text menu. On a touch screen, long-press a message: the bubble shrinks a little as you hold, then the menu opens. | Action | What it does | | --- | --- | | **Copy** | Copies the text. | | **Edit** | Your own messages only; see above. | | **Read aloud** | Reads a reply with the bot's voice. See [Voice and calls](/guide/voice). | | **Select text** | Opens the text so you can select part of it (menu only). | | **Share** | Opens your system's share sheet. | | **Regenerate** | On a bot's reply: asks the same question again. The old reply stays one arrow away, like an edit. Chats with one bot only. | | **Delete Message** | Removes one message for everyone in the chat. The messages around it stay. | Regenerate and Delete Message are hidden while the bot is working. You can delete your own messages; the person who started the chat and the bot's managers can delete any message in it. ## Find in a chat Open the **More** menu (**…**) and choose **Find in Chat**, or press **Cmd+F** (macOS) or **Ctrl+F**. Type to see matches and step through them. Find looks through the messages loaded so far; scroll up to load older ones. ## Delete a chat 1. In the chat, open the **More** menu (**…**) and choose **Delete Chat**. You can also delete a chat from **Topics**: use the menu on its row. If you delete General, your most recent topic becomes General. 2. If the bot made things in this chat, the confirmation counts them and offers **Also delete the N things made here**. It's off unless you tick it. 3. Confirm. The chat's messages, photos and files are deleted for everyone who can see it. Usage records stay, and anything the bot remembered from the chat stays in its memory. A deleted chat with one bot starts fresh; a deleted group chat takes you back to your chats. You can't delete a chat while the bot is working in it. You can delete chats you started. People who manage a bot can delete any chat with it. To clear everything at once, open the bot's profile and choose **Delete All Chats**; group chats and chats the bot is busy in are left alone. To remove one message instead, use **Delete Message** (see [Message actions](#message-actions)). ## Export or share a chat These work through the [API](/develop/api) for now; the app has no button for them yet. - **Export:** `GET /v1/conversations/{id}/export` downloads the chat as Markdown, or as JSON with `?format=json`. Each message has its author, time, text and the names of attached files. It holds only the version of the chat that's shown, and only what you can see. - **Read-only link:** `POST /v1/conversations/{id}/share` with `{"public": true}` returns a link that shows the chat read-only to anyone who has it. Attachments are listed by name, not shared. Sharing again gives a new link and stops the old one; `{"public": false}` stops sharing. Only the person who started the chat and the bot's managers can share it. A private chat that holds personal data from your devices can't be shared. ## Routines in your chat When you ask a bot in chat to do something later ("remind me in an hour", "every weekday at 9"), it creates a routine without asking you first. The routine's results come back to that same chat, with a notification. In the thread, a run started by a routine shows as **Routine "…" ran** instead of a message from you. Routines made in Settings, and morning briefs, post to your **General** chat with that bot. See [Routines](/guide/routines). ## Search Search finds messages, chats, memories, skills, routines, tickets and files across the workspace. - **Desktop and web:** press **Cmd+K** (macOS) or **Ctrl+K**, or use the search button in the sidebar. - **Phones:** the search button in the **Chats** header, next to **+**. Before you type, search suggests where to go: **Recent** searches (kept on this device), **Jump back in** with the bots you talked to last, **Needs you** when something is waiting for you, and **Go to** for Quick ask, Tasks, Skills and Settings. From the first letter, matching bots and places show under **Top hits**. From two letters, the server's results join them, grouped by type. Tap a chip under the field (**All**, **Chats**, **Memories**, **Skills**, **Routines**, **Tickets** or **Files**) to search only that kind; each chip shows how many it found. If nothing matches, **Ask … about "…"** starts a Quick ask with the bot you talked to last. Results open the item itself: a message opens its chat scrolled to it, a memory opens its editor, a routine is highlighted in its list, a ticket opens its sheet, and files open in the preview. On a tablet or computer, use the arrow keys and **Enter** to open a result, and **Esc** to clear or close. Search covers only bots and chats you can see. File search looks at names and contents under `~/workspace` on up to three computers that are awake. Sleeping computers aren't woken for a search; start one to include its files. With encryption at rest turned on, search matches titles and meaning, not exact words in encrypted text. See [Privacy and security](/guide/privacy). ## Shortcuts | Shortcut | Where | What it does | | --- | --- | --- | | **Cmd+K** / **Ctrl+K** | Desktop and web app | Opens search. | | **Cmd+F** / **Ctrl+F** | In a chat, desktop and web app | Find in Chat. | | **Cmd+V** / **Ctrl+V** | In a chat, desktop and web app | Attaches a picture from the clipboard. | | **Cmd+Shift+K** / **Ctrl+Shift+K** | Desktop app, anywhere on the computer | Opens **Quick ask**: a quick request that starts a new chat with the bot you pick. | | **Ask a bot**, **Run a routine** | Siri, Spotlight and Shortcuts on iOS 16 and macOS 13 or later | Asks a bot a question, or runs a routine and opens the chat where its results arrive. | | **Quick ask**, **Ask …**, **Run …** | Long-press the app icon on Android | Quick ask, ask one of your first two bots, or run your first routine. | ## Offline The mobile and desktop apps keep a copy of what they've shown you: your workspaces, your bots, and the last 100 messages of each chat you've opened. Chats open instantly from this copy and refresh from the server. When you're offline, the app still opens and stays signed in. Saved bots and messages stay visible, and the chat shows **Offline. Showing saved messages.** with **Try again**. Interactive cards aren't saved. The copy is deleted when you sign out. ## Limits - The web app keeps no offline copy, only your unsent drafts. - Edit and resend, and Regenerate, work only in chats with one bot. In group chats, messages are kept in one line. - Sharing files into Casama from another app passes files on Android. On iOS it passes text only. - Export and read-only links aren't in the app yet; use the API. - Skills you pick with `/` don't come along on a message you send while the bot is working. - A conversation summary made before an edit (long chats are summarized as they grow) may still mention the other version. - Siri phrases need iOS 16 or macOS 13; older systems don't offer them. ## Related - [Bots and models](/guide/bots) - [Group chats](/guide/group-chats) - [Skills](/guide/skills) - [Routines](/guide/routines) - [Autonomy and approvals](/guide/autonomy) # Coding agents A bot can hand a coding task to a dedicated coding agent (Claude Code, Codex or Cursor) and report back with a summary, the files that changed and, for cloud agents, a pull request link. Use it when a task is real software work, like fixing a bug across a repository, and you'd rather a coding agent do it than the bot's general tools. ## Where the agent runs You choose where by asking the bot ("use Claude Code on my computer to..."). There are three places: | Where | What it uses | Keys and sign-ins | Agents | | --- | --- | --- | --- | | Your computer | Your own machine through the [desktop app](/guide/companion) | Your own sign-ins; no keys are passed | Claude Code, Codex, Cursor | | The bot's computer | The bot's sandboxed [computer](/guide/computers) | An API key from a named secret | Claude Code, Codex, Cursor | | Cloud | Cursor's cloud agents, working on a GitHub repository | `CURSOR_API_KEY` secret | Cursor | ## Use a coding agent on your computer The agent works in your shared folders with your own sign-ins, and the on-screen overlay shows it working. 1. Install the agent's command-line tool on your computer: `claude`, `codex` or `cursor-agent`. 2. In the desktop app, open **Settings → Advanced → Use this computer for bots**, allow the bot under **Bots Allowed**, and share the project folder under **Shared Folders**. 3. Under **Coding Agents**, check that your agent is listed. If you see "Coding agents run as commands, so they need Run commands turned on.", tap **Turn On**. 4. Ask the bot, for example: "Use Claude Code on my computer to fix the failing tests in `~/code/app`." The app looks for the agents on your `PATH` and in the usual install folders, such as `/opt/homebrew/bin`, `/usr/local/bin`, `~/.local/bin` and `~/.npm-global/bin`. ## Use a coding agent on the bot's computer The first time, the bot installs the agent's command-line tool on its computer. It passes the API key only to that one command, and the key is redacted from output like every secret. 1. Open **Settings → Advanced → Secrets** and add a secret the bot can use, named for the agent: | Agent | Secret name | | --- | --- | | Claude Code | `ANTHROPIC_API_KEY` | | Codex | `OPENAI_API_KEY` | | Cursor | `CURSOR_API_KEY` | 2. Ask the bot, for example: "Clone `https://github.com/example/app` and have Codex add input validation to the signup form." If the secret is missing, the bot is told which one to add. ## Use a Cursor cloud agent Cursor's cloud agents work on a GitHub repository in Cursor's cloud and can open a pull request when they finish. 1. Add a secret named `CURSOR_API_KEY` in **Settings → Advanced → Secrets**. 2. Ask the bot with the repository URL, for example: "Have a Cursor cloud agent fix issue 42 in `https://github.com/example/app` and open a pull request." ## What you get back The agent's output streams into the run's timeline while it works. When it's done, the bot gets: - the agent's summary (its final result when it reports one, otherwise the end of its output), - the changed files from `git diff --stat`, - the branch it worked on, if one was named, - for cloud agents, the pull request link. Cancelling the run stops the agent, including a cloud agent. ## Options the bot can set | Option | Meaning | | --- | --- | | Folder | The project folder. On your computer it must be inside a shared folder. | | Branch | A branch to work on. It's created if it doesn't exist. | | Repository | Cloud only: the GitHub repository URL. Required for cloud agents. | | Open a pull request | Cloud only: open a pull request when done. | | Timeout | 1 to 120 minutes. Defaults to 30 minutes on a computer and 60 minutes in the cloud. | ## Approvals and safety Handing off a coding task is a medium-risk action, and high risk when it may open a pull request, so it follows your bot's [autonomy](/guide/autonomy) and approval settings. How much each agent may do on its own depends on where it runs: - On your computer, Claude Code runs with `--permission-mode acceptEdits`, so it can edit files without asking. Codex runs with `--full-auto` and Cursor with `--force`. Your shared folders and the desktop app's **Run commands** permission still apply, and high-risk actions on your computer always ask. - On the bot's computer, Claude Code runs with `--dangerously-skip-permissions`, since the computer is a sandbox. ## Limits - Cloud agents are Cursor only. Other agents can be added when they publish an API to start a task. - Codex on the bot's computer needs an `OPENAI_API_KEY`; signing in with a ChatGPT plan there isn't supported yet. - Only cloud agents open pull requests. On a computer, the agent works on a branch, and you or the bot push it. - Cursor's cloud agent support was built from Cursor's public documentation and tested against a stand-in service, not yet against Cursor itself. ## Related - [Your own computer](/guide/companion) - [Computers](/guide/computers) - [Autonomy and approvals](/guide/autonomy) - [Projects and the ticket board](/guide/projects) # Your own computer The Casama desktop app for macOS, Windows and Linux can lend your machine to the bots you choose. They can run commands and edit files in folders you share, use their own browser, use desktop apps and reach MCP servers running on your machine. Use it when a bot needs your local files, apps or sign-ins rather than its sandboxed [computer](/guide/computers). Everything a bot does on your machine shows on screen and can be stopped, and nothing is allowed until you turn it on. ## Turn it on 1. In the desktop app, open **Settings → Advanced → Use this computer for bots**. 2. Tap **Use this computer for bots** to pair this machine with your account. 3. Under **What Bots May Do**, turn on only the capabilities you want (see below). 4. Under **Shared Folders**, tap **Add a Folder** and pick each folder bots may reach. 5. Under **Bots Allowed**, check each bot that may use this computer. The switch at the top turns the whole feature on or off without unpairing. Its status reads **On: bots you allow can use this computer**, **Connecting…**, **Cannot reach Casama; retrying** or **Off**. Allowing a bot makes this computer that bot's computer, so its commands, files and browsing happen here from then on. Unchecking it sends the bot back to its usual computer. The computer appears in your computer lists as **This device**, with its system (for example `macOS 26.2 · This device`) and what bots may use on it. ### In the app From any of your devices, the computer's panel shows **Connected** or **Offline** instead of awake or asleep. While it's connected you see a screenshot that refreshes every 5 seconds, and **Files** for your shared folders. You can open, play and list files there yourself, without a bot; changing files still needs a bot you allowed. The panel offers only what works on your own computer, so there's no live view, terminal, restore points or sleep. When it's offline, it says to open Casama on that computer and turn the setting on. To stop for good, tap **Stop using this computer and unpair it** at the bottom of the screen. ::: tip The app needs to be running and online for bots to reach your computer. Your computer never sleeps the way a sandboxed computer does, and bots get a clear error when it's offline. ::: ## Capabilities Each capability is off until you approve it. | Capability | What bots can do | | --- | --- | | **Run commands (inside shared folders)** | Run shell commands. The working folder must be inside a shared folder. | | **Read and edit files in shared folders** | Read, write and search files, only inside shared folders. | | **Use a browser (its own, separate from yours)** | Drive a browser session of its own. It never touches your other browser sessions. | | **Use desktop apps** | Open and operate apps on your desktop. | | **Local tools (MCP)** | Call MCP servers you add on this computer. | | **Messages (iMessage)** | Mac only. Read and send iMessages for a connected iMessage chat app. | High-risk actions always ask for your approval on your own computer, whatever the bot's [autonomy](/guide/autonomy) setting. ## Shared folders Bots can only reach the folders you share. File paths and working folders are checked against them, with symbolic links resolved, so a link can't point a bot outside a shared folder. Remove a folder with the **x** next to it. ## The overlay and Stop While a bot acts on your computer, a bar stays on top of your windows: "{bot} is working on this computer: {action}". Tap **Stop** to cancel that bot's run immediately. The tray or menu bar icon also shows which bot is acting. ## Local MCP servers Bots can use MCP servers that run on your machine, such as tools for a design app or a coding agent, without exposing them to the internet. Tokens and environment values stay on your computer. 1. Turn on **Local tools (MCP)** under **What Bots May Do**. 2. Under **Local Tools (MCP)**, tap **Add a Local MCP Server**. 3. Enter a **Name**, then choose how to reach the server: - **A Command**: the **Command** that starts it, for example `npx -y @example/mcp-server`. You can pick a **Working Folder (Optional)** inside a shared folder and add **Environment** values, one `KEY=value` per line. - **An Address on This Computer**: an **Address** such as `http://127.0.0.1:3845/mcp`. Only `127.0.0.1` and `::1` are accepted. 4. Tap **Add a Local MCP Server**. How it works: - A command-based server starts the first time a bot uses it and stops after 10 idle minutes. - New servers are attached to the bots this computer allows. Only you can attach them to other bots. - The command is visible to your workspace. Environment values are kept in the app's secure storage and never leave your machine. - A call can run up to 30 minutes by default and stays alive while the server reports progress. Progress shows in the bot's timeline, and cancelling the run cancels the call. - If your computer is offline, the bot gets a clear error and the server stays connected for next time. - Bots can use local MCP servers from any device, including phones and the web, while this computer is online. Adding one works only in the desktop app. For hosted MCP servers and connecting AI apps to Casama, see [MCP](/guide/mcp). ## Coding agents The **Coding Agents** section lists the coding agents the app finds on this computer: Claude Code (`claude`), Codex (`codex`) and Cursor's command-line agent (`cursor-agent`). Bots can hand coding tasks to them, and they run with your own sign-ins in your shared folders. Coding agents run as commands, so they need **Run commands** turned on. If it's off, tap **Turn On** in this section. See [Coding agents](/guide/coding-agents). ## Desktop context in Quick ask Press Cmd+Shift+K on macOS or Ctrl+Shift+K on Windows and Linux to open **Quick ask** from anywhere. Just before Casama's window comes forward, the app reads what you were looking at: - the app and window title in front, - the text you had selected (**Selected Text**), - the current browser tab's title and address. Each part appears as a chip you can switch off before sending. The parts you keep are added after your message. Tap **Add a Screenshot** to include an image of your screen; Casama's window steps aside while it's taken, and the image is uploaded to the bot's computer like a chat attachment. Context is read only when you press the shortcut and used once. Missing tools or permissions mean less context, not an error. | Platform | Where it reads from | | --- | --- | | macOS | System Events for the app and window, the Accessibility selection, and Chrome, Arc, Brave, Edge, Vivaldi, Opera or Safari for the tab | | Windows | The foreground window, and UI Automation for the selection | | Linux | `xdotool` and the primary selection | On macOS, the selection and window title need Accessibility permission, the browser tab needs permission to control the browser (Automation), and screenshots need Screen Recording permission. ## Search files on your computer When a bot works on your computer, it can search for files, only inside your shared folders. It uses Spotlight on macOS, the Windows Search index on Windows, and `locate` (or `find`) on Linux. Results are filtered to your shared folders again on the server before the bot sees them. ## Watched folders and activity Two related features live under **Settings → Advanced → Device connections**: - **Watched Folders**: a new file in a folder you pick can start a routine, such as "file new PDFs in Downloads". The app waits until the file stops growing and skips partial downloads and hidden files. Only the folder and file names are shared. See [Routines](/guide/routines#device-triggers). - **Computer activity** (off by default): an hourly summary of which apps you used and for how long, for end-of-day recaps and time tracking. It never includes selections, screenshots or keystrokes. See [Devices](/guide/devices). ## iMessage iMessage has no bot API, so your own Mac does the work. 1. On your Mac, in **Settings → Advanced → Use this computer for bots**, turn on **Messages (iMessage)**. 2. Give Casama Full Disk Access in macOS System Settings, so it can read your Messages history. 3. Connect an iMessage chat app on the bot. See [Chat apps](/guide/chat-apps). Casama checks for new messages every minute through your Mac and sends replies with AppleScript. The first check only records where to start, so old messages are never answered. Only the Mac's owner can connect it, and only for a bot allowed on that Mac. ## Limits - Your own computer has no live view, terminal, checkpoints or sleep. Those need a sandboxed computer. - iMessage is text only (no attachments or images), and group chats aren't supported. - Coding agents and local MCP servers need the desktop app running and online. - The macOS app is distributed with Developer ID signing rather than through the Mac App Store, because it needs to run commands and start a browser outside an app sandbox. - Not yet: the Windows browser tab in Quick ask context, and macOS Calendar and Reminders. ## Related - [Computers](/guide/computers) - [Coding agents](/guide/coding-agents) - [MCP](/guide/mcp) - [Chat apps](/guide/chat-apps) - [Devices](/guide/devices) # Computers Every bot works on its own sandboxed Linux computer: a shell, a home folder that persists between chats, a browser that stays signed in, and on desktop computers, a screen you can watch and control. Use this page to understand what's on a computer, how it sleeps and wakes, and how to step in when a bot needs a hand. If you run your own server, provider setup (Docker, gVisor, E2B, Daytona) lives on [Self-hosting computers](/self-hosting/computers). ## Team, private and personal computers | Kind | Who uses it | Shown in the app as | | --- | --- | --- | | Team computer | Every bot in the workspace that has no computer of its own. One per workspace. | **Team computer** | | Private computer | One bot. Its files stay separate from the team computer. | **{bot}'s computer** | | Your own computer | Bots you allow, through the desktop app. See [Your own computer](/guide/companion). | **This device** | A bot with no setting uses its private computer if it has one, otherwise the team computer. To pick a different one, open the bot's **Bot profile → Computer** and choose **Automatic** or a specific computer. Workspace admins manage the team computer. Whoever manages a bot manages its private computer. Bots never share a computer across workspaces. ## Create a private computer 1. Open **Settings → Advanced → Computers**. 2. Tap **New computer**. 3. Choose the bot under **For bot** and give the computer a **Name**. 4. Turn on **With a desktop** if you want a screen you can watch live. It uses more memory. 5. Tap **Create**. Each computer's card says what the machine is: whose it is, its system and size (for example `Ubuntu 24.04 · 1 CPU · 1 GB RAM · 10 GB disk`), a **Saved** pill when its files are kept while it's stopped, and when it was last used. From the same list, each computer's **More** menu offers **Manage**, **Restart**, **Reset…**, **Live view** (desktop computers), **Switch to Desktop** or **Switch to Headless**, **Rename** and **Delete**. Deleting a computer also deletes its files, snapshots and restore points. The team computer has no **Delete** option. ## What's on a computer Every computer starts from Casama's image, based on Ubuntu 24.04: | Area | Included | | --- | --- | | Shell and tools | bash, git, curl, wget, jq, ripgrep, zip and unzip, nano, vim, OpenSSH client, ffmpeg, build tools | | Languages | Node.js 24, Python 3 with pip and venv | | Documents | LibreOffice, pandoc, Poppler, qpdf and Tesseract, for the PDF, Word, Excel and PowerPoint skills | | Browser | Chromium, driven by the bot through agent-browser | | Desktop computers only | A desktop with a taskbar (**Browser**, **Terminal**, **Text editor**), accessibility tooling so the bot can use apps, and the live view streamer | The bot works as an unprivileged user named `casama`, and its home folder is the only place that persists. On the default Docker provider the rest of the filesystem is read-only, so install extra tools into the home folder: `pip install` installs for the user, and `npm install -g` installs under `~/.npm-global`. `/tmp` is a 1 GB scratch space that's cleared when the computer sleeps. By default, a computer on the Docker provider gets 1 CPU and 1 GB of memory. Your server's operator can change these defaults. On Casama Cloud, your plan sets each computer's size and how many can run at once: | Plan | Size of each computer | Running at once | | --- | --- | --- | | **Free** | 1 CPU, 1 GB | 1 | | **Plus** | 1 CPU, 1 GB | 1 | | **Pro** | 2 CPUs, 2 GB | 2 | | **Max** | 4 CPUs, 4 GB | 2 | When you're at the limit and something needs another computer, Casama puts one that nobody has used for 2 minutes to sleep. If every running computer is in use, the new one doesn't start and the app offers a bigger plan. See [Usage and plans](/guide/usage). Self-hosted servers have no such limits. ## Headless and desktop computers New computers are **Headless** unless you turn on a desktop. A headless computer has a shell, files and a browser, but no screen. Its **Screen** tab shows the bot's open browser page, refreshed every 5 seconds, and stays blank until the bot opens a page. A **Desktop** computer adds a real screen that you can watch and control live, and the bot can use desktop apps. On a desktop computer the bot's browser runs as a visible window, so when you take over you see exactly what the bot sees. To switch, tap **Switch to Desktop** on the Screen tab, or use **Switch to Desktop** or **Switch to Headless** in the computer's **More** menu. A running computer restarts into the new profile, and its files are kept. If a bot on a headless computer asks you to take over, for example to sign in, Casama switches that computer to the desktop profile for you and reopens the bot's current page in a visible window. The next time it sleeps after the takeover, it goes back to headless, since a desktop uses more memory. A desktop you chose yourself stays a desktop. ## The computer panel Open a bot's computer in any of these ways: - In a chat on a wide screen, tap **Show computer** at the far right of the header. The panel opens beside the chat. - In a chat on a phone or narrow window, open the **More** menu and tap **Computer**. While the bot is working on its computer, a computer button with a live dot also shows in the chat header. - From **Settings → Advanced → Computers**, choose **Manage** in a computer's menu. The panel shows the computer's name and state, with **Sleep** or **Wake up**, and four tabs: **Screen**, **Terminal**, **Files** and **Manage**. While the computer is on, the header shows small CPU, memory and disk meters; disk turns amber at 80% and red at 90%, and tapping a meter opens **Manage**. On wide screens you can resize the side panel: drag its left edge. It stays between 360 px and 60% of the window, and the chat always keeps at least 420 px. Double-click the edge to reset it. The width is remembered on this device. ### States you'll see The state shown is checked against the sandbox each time the app lists computers, so a computer that says **Running** really is running. The panel refreshes itself while it's visible: every 3 seconds while the computer wakes, otherwise every 10 seconds, and again when you return to the app. | State | Meaning | | --- | --- | | **Setting up** | The computer is being created for the first time. | | **Starting** | It's waking up and restoring its files. | | **Running** / **Idle** | It's awake and ready. | | **Going to sleep** | Its files are being saved before it stops. | | **Asleep** | Its files are saved and it isn't running. It wakes when needed. | | **Stopped** | It's been stopped. | | **Error** | Something went wrong. The panel shows the error, and **Try again** retries. | ## Sleep and wake A computer goes to sleep after 5 minutes with no bot working on it, no running commands and no one using it. Using it means typing or clicking in the terminal or live view while you're in the app; a live view or terminal left open in the background doesn't count. To pick a longer wait (15, 30 or 60 minutes) for one computer, set **Goes to sleep after** under **Manage**. A longer wait costs more. Sleeping saves the home folder (your files, the bot's workspace and its browser profile) to storage and stops the computer, so an asleep computer costs nothing to keep. It wakes on its own the next time a bot needs it or you open the live view. You can also tap **Wake up** in the panel, or **Sleep** to put it to sleep now. Everything in the home folder comes back, including browser sign-ins. ## Files The **Files** tab browses the computer's home folder. You can open folders, go **Up**, **Download** a file, **Upload** files from your device, and **Delete** files. Files your bots make and files you upload both show up here. Files you attach in a chat are uploaded to `~/workspace/uploads` on the bot's computer. When a bot links a file it made, such as `[report.md](workspace/report.md)`, tap the link to preview it and open, save or share it. See [Chat](/guide/chat). The **Terminal** tab opens a shell on the same computer the bots use, so you can see and fix what they did. Tap **Connect** to start a session. ## The browser and sign-ins The bot's browser keeps its profile in the home folder, so cookies and sign-ins survive sleep, wake and restores. Sign in once, and the bot stays signed in. When a site needs you, for example a password or a two-step code, the bot can ask you to take over. You sign in yourself in the live view, and nothing you type reaches the bot. See [Take control](#take-control-and-hand-back). ## Manage a computer The **Manage** tab is where you fix a computer, see what it costs and holds, and set when it sleeps. Looking at it never wakes the computer or keeps it awake; some parts only fill in while it's on. | Section | What it does | | --- | --- | | **Not working right?** | Fixes to try in order: **Restart** (about 20 seconds, nothing is lost), **Reset system** (a fresh system; `~/workspace` stays) and **Erase everything** (like new). | | **Restore points** | Saved copies of the home folder. Tap **Restore** on one, or **Save a restore point now**. | | **Storage** | What fills the disk: your files, apps and tools, caches, the browser and other. **Free up** removes caches only, never your files, tools, settings or sign-ins. | | **Running now** | Programs on the computer, busiest first. **Stop** ends one; the computer's own parts can't be stopped. | | **Goes to sleep after** | 5, 15, 30 or 60 minutes without use. | | **This month** | How long the computer was on, what it cost and a bar per day. | | **Used by** | The bots that use this computer. | | **History** | What happened, in sentences: woke up, went to sleep, restarted, reset, restore point saved, and who did it. | | **Download all files** | A zip of `~/workspace`, up to 1 GB. | A reset saves a "Before reset" restore point first (on by default) and shows what's kept and what's removed. Erasing also asks you to type the computer's name. The reset runs in the background and shows its steps; when it's done, **Undo** puts everything back from that restore point. Only the people who manage the bot (or admins, for the team computer) can reset it. When a computer breaks, the chat shows **Restart** and more fixes. A bot can also restart its own computer if it gets stuck. ## Restore points A restore point (also called a checkpoint) saves the computer's home folder so you can undo a change. The bot saves one automatically before commands that destroy data, such as `rm -r` or `rm -f`, `git reset --hard`, `git clean -f`, force pushes, package uninstalls, `dd`, `mkfs` and `truncate -s 0`. Bots can also save one on purpose before risky work. To restore one: 1. Open the computer panel and go to **Manage**. 2. Under **Restore points**, tap **Restore** next to the one you want. 3. Confirm. Files changed since then are replaced. Checkpoints also appear in the chat and run timeline with a **Restore** button. Each computer keeps its last 20 restore points or 7 days of them, whichever is fewer. Older ones are deleted. ## Live view Live view streams a desktop computer's screen to the app over WebRTC. Open it from the **Screen** tab (**Open Live View**, or **Wake Up and Watch Live** if it's asleep), from **Live view** in a computer's menu, or from a bot's request for help. Opening it wakes a sleeping computer. The computer's screen comes first. A status chip in the header shows **Live**, **Screenshots**, **Connecting…** or **Paused**, with the latency while live; tap it for details. On wide screens the live view plays right inside the side panel. Tap **Full screen** to expand it and **Back to the side panel** to return. Turn a phone sideways for a bigger screen: the controls move into the black bars beside it. If your network blocks live video, the view falls back to **Screenshots**, which update about once a second. After 5 minutes without input, and with no bot working on the computer, the live view asks **Still watching?**. With no answer it shows **Paused to save power**, so the computer can sleep; **Resume** wakes it again. The stream also pauses while the app is in the background. ### The dock The controls sit in a dock at the bottom, in reach of your thumb. While you watch, it shows who has the screen and **Take Control**. While you're in control: | Action | What it does | | --- | --- | | **Keyboard** | Opens your phone's keyboard. Enter types Return on the computer. Touch screens only. | | **Right-click on next tap** | Makes your next tap a right-click. Touch screens only. | | **Paste** | Sends your device's clipboard to the computer and presses Ctrl+V. | | **Copy** | Presses Ctrl+C on the computer and puts the copied text on your device's clipboard. | | **Hand Back** | Gives control back to the bot. | **More** (**⋯**) holds **Save Screenshot**, and **Teach a task** while you're in control. ## Take control and hand back At any time you can take the mouse and keyboard from the bot. 1. In the live view, tap **Take Control**. The status changes to **You're in control**. 2. Do what you need to, such as signing in. 3. Tap **Hand Back**. Optionally add a **Note for the bot**, for example "I signed in, carry on". 4. Confirm with **Hand Back**. While you're in control, the bot is paused. Its browser and desktop actions wait, and so do its shell and file commands. Nothing you type or see is sent to the bot. When you hand back, the bot reads your note and takes a fresh look at the screen before it continues. Control returns to the bot on its own after 15 minutes without input from you. Only one person can be in control at a time. Others see **Someone else is in control** and can only watch. ### When a bot asks for help A bot can ask you to take over, for example at a sign-in page or a CAPTCHA. You get a notification, and the chat shows the request with **Take Control**. The live view shows "The bot asks: ..." with the reason. Take control and hand back as above, or tap **Dismiss** to decline. A request that no one answers expires after 24 hours. ## Team computer folders On a team computer, each bot works in its own folder, `~/workspace/bots/`, and `~/workspace/shared` holds what the bots share. Both are created the first time the bot needs them. - The folder name comes from the bot's name, such as `research-bot`, with `-2`, `-3` and so on if two bots would clash. It's kept when you rename the bot, so its files don't move. - The bot's commands start in its own folder. Paths starting with `shared/` or `bots/` point into the workspace, so every bot reaches the shared folder the same way. - This is a convention, not a wall. Bots on a team computer share one Linux user and can technically reach each other's folders. Give a bot a private computer when it needs real separation. ### Desktop users at once A team computer has one screen. **Desktop users at once** (1 to 10, default 1) limits how many bots use desktop tools at the same time. When the screen is in use, other bots keep working with the shell, files and browser. Admins change it from the team computer's **More** menu in **Settings → Advanced → Computers**. ## Network and egress On the default Docker provider, a computer has no direct route to the internet. All its traffic goes through Casama's egress proxy, which: - Allows outbound HTTP and HTTPS to public addresses. - Refuses private, loopback, link-local (including cloud metadata), CGNAT, multicast and reserved addresses. It checks the address it actually connects to, so DNS tricks can't get around it. - Has no route for other traffic. SSH and other non-HTTP protocols can't reach the internet, so clone repositories over HTTPS. - Applies per-computer connection and bandwidth rate limits. Computers can't reach each other or Casama's internal services. ## Use computers from the CLI The [CLI](/develop/cli) works with the team computer by default, or another one with `--computer`: ```sh casama computer status # list computers and their state casama computer start # wake (restore) the computer casama computer stop # save files and sleep casama computer shell # interactive terminal casama computer files ls workspace # also get, put and rm casama computer checkpoints # list undo points casama computer restore ``` ## Limits - The 10 GB disk size isn't enforced yet on the Docker provider. - Restore points save the whole home folder each time rather than only what changed. - Personal computers (your own, through the desktop app) have no **Manage** tab. See [Your own computer](/guide/companion). - Bots work mostly from the screen's accessibility tree and page snapshots. Screenshots they take are saved as files, and models that read images also see the newest two in a run. - On E2B and Daytona, computers have their own internet access, so the egress proxy's private-range blocking doesn't apply there. - There's no setting in the app for per-workspace domain allow or deny lists. ## Related - [Your own computer](/guide/companion) - [Teach by showing](/guide/teach) - [Coding agents](/guide/coding-agents) - [Self-hosting computers](/self-hosting/computers) - [Autonomy and approvals](/guide/autonomy) # Apps and connections Connections give your bots tools beyond their own computer: your team's apps, any MCP server or OpenAPI source, logins from a password manager, and keys they use for you. Every connection is stored encrypted, and each bot gets only the connections you give it. ## Connect an app Casama ships with a catalog of apps that run their own hosted MCP servers, so you connect them directly with no middleman. Owners and admins connect apps for the workspace. 1. Open **Settings** → **Integrations**. The screen is called **Apps**. On a phone, the round button beside the tabs opens it too. 2. Pick the **Browse** tab, then search or filter by category. 3. Tap an app. The connect sheet shows what bots can do with it. 4. Connect it one of these ways, depending on the app: - **Continue with** the app: one-click sign-in. The vendor's sign-in page opens: on iPhone and Android in the system's sign-in sheet, which closes by itself when you're done; on computers and the web in your browser. Approve access there and the sheet updates by itself. - **API key**: follow the steps on the sheet, which link to the vendor's key page. Casama tests the key when you save it. - No sign-in: some apps work as soon as you add them. 5. Under **Which bots can use it?**, pick the bots, then tap **Done**. The connection now shows on the **Connected** tab. You can also give a connection to a bot later from the bot's settings: **Bot profile** → **Integrations for this bot**. Its tools show up the next time the bot runs. ### Connect from a chat You don't have to go to Settings. Ask a bot in any chat ("connect my Google", "can you read my inbox?") and, if the app isn't connected yet, the bot shows a card with a **Connect** button for each app it needs, up to four, and **More apps**, which opens the full catalog. Tap a button to sign in as above. Bots never sign in for you, and no admin has to enable an app first. - Ask for "Google" and the bot usually offers Google Calendar and Gmail. - Apps the workspace already has get no button. The bot uses them, or adds them to itself, instead. - The card can offer apps from the gallery too. ### Two accounts of one app To connect a second account of the same app, such as a work and a personal Gmail, tap the app on the **Browse** tab again and connect the other account. The second connection is named after the first with a number, such as `gmail_2`, and has its own tools (`mcp.gmail_2.…`), so you can give each account to different bots. This works for apps connected with their own sign-in or an API key. Apps connected with **Sign in through Composio** share one Composio connection per workspace, so they hold one account each. ### The catalog Each app tile shows how it connects: **One click**, **API key**, **No sign-in** or **Needs setup**. The **Popular** row leads with everyday apps: Gmail, Google Calendar, Google Drive, Google Docs, Google Sheets, Notion, Slack and Zapier (the Google apps only where this server can connect Google). Then the categories, in this order: | Category | Apps | | --------------- | ------------------------------------------------------------------------------------- | | Google | Gmail, Google Calendar, Drive, Docs, Sheets, Slides, Contacts | | Productivity | Notion, Slack, Asana, monday.com, Box, Jira & Confluence | | Data & search | Exa, Airtable | | Automation | Zapier, Composio, Pipedream | | Design | Figma, Webflow | | Sales & support | HubSpot, Intercom | | Payments | Stripe | | Developer | GitHub, Linear, Sentry, Vercel, Supabase, Neon, Cloudflare Docs, Context7, PostHog, Hugging Face | Cloudflare Docs works without signing in. Hugging Face, Context7 and Exa work without signing in and also take an optional API key. More apps come from the [open gallery](https://gallery.casama.ai/#app), such as Canva and DeepWiki. They sit in the same list, with the same tiles, and new ones appear without an app update. ### Add an app to the catalog Anyone can propose a vendor's hosted MCP server for everyone's catalog: 1. Fork [stackwares/casama-gallery](https://github.com/stackwares/casama-gallery). 2. Add a folder under `apps/` with `item.json`, `app.json` and, if you like, the vendor's single-color `logo.svg`. The gallery's README lists every field. 3. Run `node check.mjs`, then open a pull request. Casama checks the server against the vendor's own docs before merging. Once merged, the app shows up in Connections for everyone within about 15 minutes. Only servers the vendor itself runs are accepted; for any other server, use [a custom server](#add-a-custom-server). ### When an app says "Needs setup" Some vendors don't let apps register themselves for one-click sign-in. For those, whoever runs your Casama server registers an OAuth client with the vendor once. The connect sheet says so and shows the redirect address to register, which is `/oauth/callback`. | App | What the server needs | | -------------------------------------------- | --------------------------------------------------------- | | Gmail, Calendar, Drive, Docs, Sheets, Slides, Contacts | `GOOGLE_OAUTH_CLIENT_ID` and `GOOGLE_OAUTH_CLIENT_SECRET` | | GitHub, Slack, Asana, HubSpot, Box, Figma | An entry in `MCP_OAUTH_CLIENTS` | Until that's done there are two other ways in: - **The server has a Composio key** (`COMPOSIO_API_KEY`, as on Casama Cloud): these apps show **Sign in through Composio**. One click, and you sign in to the app itself; Composio handles the connection on the server's account, and the bot gets the app's tools. - **No Composio key:** the connect sheet offers **Composio**, **Pipedream** or **Zapier** with one click (sign in with your own account there), then ask your bot to use the app through it. Vendors only send people back to `https` or `localhost` addresses. A server on a private network address over `http` (local development) uses `http://localhost:/oauth/callback`, so finish the sign-in in a browser on that machine. Set `OAUTH_REDIRECT_URL` to use another address. `MCP_OAUTH_CLIENTS` is JSON keyed by app id: ```json { "slack": { "client_id": "123.456", "client_secret": "your-client-secret" } } ``` GitHub also accepts a fine-grained personal access token, so it works without this setup. See [Configuration](/self-hosting/configuration) for where server settings go. ## Manage a connection Tap a connection on the **Connected** tab to open its page. From there you can: - See its health (**Ready** or **Needs attention**) and **Test connection**, which also refreshes its list of tools. - **Reconnect** when a sign-in expired or was revoked. - Change **Bots with access**. - Set each tool's approval level under **Tools**: | Level | What happens | | ----------------- | ----------------------------------------------------------------------------------- | | **Read-only** | Runs on its own. | | **Makes changes** | Under the default autonomy, runs on its own, but asks first after the bot has read something untrusted, since it could send data out. Asks every time under **Ask before acting**. | | **Always asks** | Waits for you every time. | - **Disconnect**. Bots lose its tools right away, and the saved sign-in is deleted. Signed-in connections refresh their tokens automatically shortly before they expire. On a run's timeline, tools from a connection are named after it, such as `mcp.github.create_issue`. ## Google permissions Casama uses Google's own MCP servers and asks for as little as it can: | Connection | Google scopes | What a bot can do | | ------------------- | ----------------------------------------------------------- | -------------------------------------------------- | | **Gmail** | `gmail.modify`, `gmail.compose` | Search and read email, draft replies, label threads | | **Google Calendar** | `calendar.events`, `calendar.calendarlist.readonly`, `calendar.events.freebusy` | See your schedule, create and move events, find free time | | **Google Drive** | `drive.file` | Only files you pick or that the bot creates | | **Google Docs** | `documents` | Read and edit documents | | **Google Sheets** | `spreadsheets` | Read and update spreadsheets | | **Google Slides** | `presentations` | Read and edit presentations | | **Google Contacts** | `contacts.readonly`, `directory.readonly` | Look up people | Google's Gmail server can't send email: the bot writes drafts and you send them from Gmail. Each Google app is its own connection with its own consent. ::: warning Google Developer Preview Google's MCP servers are in Developer Preview. Tool calls only work once your server's Google Cloud project is enrolled in the [Workspace Developer Preview Program](https://developers.google.com/workspace/preview), which needs a Google Workspace account. When you set up the Google client, turn on **Use this client for an AI-powered agent**, enable each product's API and MCP API (for example `gmail.googleapis.com` and `gmailmcp.googleapis.com`), and add your redirect address. ::: On Casama Cloud, Gmail connects through Composio's Google sign-in until Google's servers are generally available. ## Composio and Pipedream Composio and Pipedream each sign in to hundreds or thousands of apps for you, so you never handle those apps' keys. The quickest way is the **Composio** or **Pipedream** tile in the catalog: one click, sign in with your account there, and each app is connected the first time a bot needs it. If you'd rather use your own API key or Pipedream Connect project: 1. Open **Settings** → **Integrations** → **Browse**, and scroll to **More ways to connect**. 2. Tap **Composio** or **Pipedream**. 3. Tap **Get a free key** to open the provider's site, then paste your key. Pipedream needs a **Project ID**, **Client ID** and **Client secret**. 4. Tap **Connect**. 5. Tap **Add an app**, search the provider's directory and tap **Connect** next to an app. The provider's own sign-in page opens. Connected accounts show with their status: connected, pending or error. ## Add a custom server Connect any MCP server, an OpenAPI spec or another AI agent. 1. Open **Settings** → **Integrations**, then tap **Custom server**. 2. Choose a **Type**: | Type | You fill in | | ------------------ | ------------------------------------------------------------------------------ | | **MCP server** | **Server URL**, and an optional **Authorization header** | | **OpenAPI** | **OpenAPI spec URL**, an optional **Base URL**, and an optional secret's name | | **AI agent (A2A)** | **Agent address or agent card URL**, and an optional **Access token** | | Composio | Toolkits, such as `github, gmail`, and an API key | | Pipedream Connect | Project ID, client ID, client secret and apps | 3. Give it a **Name**: lowercase letters, numbers and underscores. Its tools are named after it. 4. Tap **Save**, then give it to bots from its page or from **Integrations for this bot**. MCP servers can use Streamable HTTP or legacy SSE. For OpenAPI, the secret's name refers to a secret from **Settings** → **Advanced** → **Secrets** and is sent as a bearer token. A bot can also add an MCP server for itself, see [Bots that change their own setup](/guide/bots#bots-that-change-their-own-setup). MCP servers that run on your own computer are added from the desktop app. See [Your own computer](/guide/companion). For agents, see [Bots working together](/guide/bots-together). ## Secrets A secret is a token or password a bot can put into a request without ever seeing it. Each secret is sent only to the hosts you allow. 1. Open **Settings** → **Advanced** → **Secrets** and tap **Add secret**. 2. Choose **Key or password**. 3. Enter a **Name** in uppercase, such as `GITHUB_TOKEN`, and the **Value**. 4. Under **Allowed hosts**, list where it may go, comma-separated, such as `api.github.com`. 5. Tap **Save**. Bots write `{{secret:GITHUB_TOKEN}}` in a request. Casama fills in the real value only when the request goes to an allowed host or one of its subdomains, and refuses otherwise. Secrets can be used in `http.request` (headers or body) and typed into web pages with `browser.fill`. Filled values are scrubbed from tool output, so they never reach the model or the timeline. Owners and admins add secrets. Admins can also keep secrets in the workspace's own Infisical project: **Settings** → **Workspace settings** → **Where secrets are kept**. ### When a bot asks for a secret If a bot needs a key you haven't saved, it can ask for one in the chat. A protected card appears: "Ada needs a Stripe key", with the hosts it's for and the bot's reason. 1. Paste the value into the masked field. The field never suggests, autocorrects or learns. 2. Tap **Save**, or **Decline**. The value goes straight into the vault, limited to that bot and those hosts. The bot only hears that the secret was saved and how to use it. The run waits up to 24 hours for an answer. The person who started the run or an admin can answer. A bot can only ask for hosts under one domain, such as `api.stripe.com` and `files.stripe.com`. If a secret with that name already exists, only an admin can replace it. ## Sign-in codes Bots can sign in to sites that use two-step codes, without holding the two-step key. 1. Open **Settings** → **Advanced** → **Secrets** → **Add secret** and choose **Sign-in code**. 2. Paste the site's **Two-step key or otpauth:// link**. On a phone, tap **Scan QR code** instead. The name is suggested from the site. 3. Add the **Allowed hosts** and tap **Save**. Bots write `{{totp:NAME}}` and get the current code at the moment the tool runs, only on the allowed hosts. The key itself never leaves the vault: `{{secret:NAME}}` on a sign-in code is refused. A bot can also ask for a sign-in code in the chat, with the same card. Casama supports time-based codes: SHA-1, SHA-256 or SHA-512, 6 to 8 digits, with periods from 10 to 300 seconds. ## Password managers Bots can sign in with logins from 1Password or Bitwarden. They never see a password. 1. Open **Settings** → **Workspace settings** → **Password managers**. 2. Tap **Connect a password manager** and choose one: - **1Password**: your **Connect server address** and a service account's **Connect token**. - **Bitwarden**: your **bw serve address** and an optional **Access token**. This uses Bitwarden's Vault Management API for your organization's collections. 3. Choose **Just me** or, as an admin, **For the whole workspace**. 4. Under **Vaults bots may use**, tick the vaults or collections. Nothing is available until you do. Casama checks the token before saving it, and never shows it again. How bots use logins: - A bot lists logins by name, with each login's sites and whether it has one-time codes. - It writes `{{login:Name:username}}`, `{{login:Name:password}}` or `{{login:Name:otp}}` into `browser.fill`. - Casama fills the value only when the page is on one of that login's own sites or their subdomains. Anywhere else it refuses and names the login's sites. - Filled values are scrubbed from output. A **Just me** password manager works only in runs acting for you, such as your own chats and your own routines. ## Paid data services Bots can buy single calls to paid data APIs (places, emails, SEO and more) through Treg's catalog. 1. Open **Settings** → **Model keys** (**Service keys** on Casama Cloud) → **Add Key**. 2. Choose **Treg** as the **Provider** and paste your Treg key. A bot searches the catalog, and each result shows its price. Buying a call asks first under the default autonomy, with the service and price on the approval card, such as "for $0.0040 per call". Treg charges your own account directly, with no Casama markup, and each call shows in [Usage](/guide/usage). A call can't cost much more than the approved price, and failed calls aren't charged. ## Plugins A plugin bundles skills and MCP tools in one install from GitHub. Open **Bot profile** → **Plugins** to add one. Plugin servers run on the bot's computer, never on Casama's servers. To build one, see [Building plugins](/develop/plugins). ## Limits - The Composio and Pipedream connections follow the providers' public API docs and haven't been checked against live accounts yet. - The Treg connection follows Treg's public guides and hasn't been checked against a live account yet. Buying data calls through Casama Cloud credits isn't offered. - Apps from the gallery can't use Google's sign-in, a sign-in client registered by the server's owner, or Composio. Those apps are built in. - Bitwarden Secrets Manager isn't supported. Use named secrets for key-value secrets. - In the app, a secret is available to every bot in the workspace. Limiting a secret to certain bots is possible through the API only. ## Related - [Autonomy and approvals](/guide/autonomy) - [Your own computer](/guide/companion) - [Bots working together](/guide/bots-together) - [Building plugins](/develop/plugins) - [Privacy and data](/guide/privacy) # Device connections and health Device connections let your bots use personal data from your phone or computer, such as your calendar, contacts and daily health summaries. Use them when you want a bot to plan around your schedule, look up a contact, or notice that you slept less than usual. The data is yours alone: even workspace admins can't see it. ## Share data from a device 1. On the device, open **Settings** → **Advanced** → **Device connections**. 2. Turn on a kind of data. The system permission prompt appears only at this point. 3. Optionally set **Keep for** and **Private Models Only** (see below). Each kind is off until you turn it on. Turning a kind on doesn't give any bot access yet. ## Let a bot read it The first time a bot needs a kind of data, it asks in the chat: "Ada would like to use your calendar". Tap **Allow** or **Not Now**. The bot carries on either way. Allowed bots show under each kind in **Device connections**. Tap **×** next to a bot to stop it. The rules: - A bot reads your device data only in runs acting for you: your own chats and your own routines. A teammate chatting with the same bot gets nothing. - You can only allow bots you have access to. - If your device was online in the last 15 minutes, the bot first asks it for a fresh read and waits up to 10 seconds. Otherwise it gets the most recent stored summaries, with their age. - Every read shows on the run's timeline: which kind, how many items, which dates and which devices. - Device data reaches the bot marked as untrusted, since calendar titles and similar text come from other people. ## What each platform shares | Kind | iOS | Android | macOS | Windows | Linux | What's shared | | ----------------- | --- | ------- | ----- | ------- | ----- | ---------------------------------------------------- | | Calendar | Yes | Yes | | | | One summary per day, from yesterday to 30 days ahead | | Contacts | Yes | Yes | Yes | | | Names, phone numbers and email addresses | | Health data | Yes | Yes | | | | Daily and workout summaries (see below) | | Places | Yes | Yes | | | | Arriving at and leaving named places | | Notifications | | Yes | | | | Notifications from apps you pick | | Computer activity | | | Yes | Yes | Yes | Minutes per app and top window titles, per hour | The web app doesn't share device data. Calendar summaries hold up to 100 events a day. Data is refreshed when the app opens or comes back to the foreground. Places and notifications mainly drive device triggers, such as "when I leave work". See [Routines](/guide/routines). Computer activity is part of desktop context. See [Your own computer](/guide/companion). ## Bots adding events A bot can add an event to your calendar. Under the default autonomy it does this without asking; set the bot to **Ask before acting** if you want to approve each one. The event goes to the device's default writable calendar on the device seen most recently. If that device doesn't answer within 20 seconds, the bot is told it will happen when the device is next online. ## Health data Health connects Apple Health on iOS and Health Connect on Android. It shares summaries only, never raw readings such as a heart-rate series or sleep segments. The server refuses anything else. | Summary | What it holds | | ------- | ------------------------------------------------------------------------------------------------------------------ | | Day | Sleep start, end, minutes and stage minutes; steps; active energy; workout count; resting heart rate; heart-rate variability; weight | | Workout | Activity, start, end, minutes, energy, distance and average heart rate | Your device builds these summaries itself. Sleep counts for the morning it ends. Uploads cover the last 7 days each time the app opens or comes back, so a missed morning catches up. **Cycle tracking**, **Blood glucose** and **Blood pressure** are separate switches under Health, off by default. Their system permissions are asked only when you turn them on, and the server drops them unless you did. When a bot reads health data, each day is compared with your own previous 30 days (with at least 5 earlier days), in plain words: "lower than your usual", "about your usual" or "higher than your usual". Bots never give medical advice. ::: warning Health data and encryption On Casama Cloud, health data is stored only when encryption at rest is on for a workspace you own. Otherwise the upload is refused with "Health data needs encryption at rest". Self-hosted servers decide with `HEALTH_REQUIRES_ENCRYPTION` (`auto`, `on` or `off`; `auto` requires it when billing is on). See [Privacy and data](/guide/privacy). ::: ## Privacy settings per kind | Setting | What it does | | ------------------------ | ------------------------------------------------------------------------------------------- | | **Keep for** | How long readings are kept: **Live only**, 7, 30 or 90 days, or a year where that's the default | | **Private Models Only** | Only bots whose models all run on this machine or a private network can read it | Defaults are a year for calendar, contacts and health, and 90 days for places and notifications. With **Live only**, a fresh read goes to the bot without being stored. **Private Models Only** counts every model in the bot's setup, including fallbacks. Each must use a key whose address is local or private, such as `localhost`, a private IP range, or a `.local` or `.internal` name. ## Turn off and forget - Turning a kind off deletes its stored readings. - **Forget this device**, under **Your Other Devices**, deletes everything that device shared. - Expired readings are deleted automatically. - A privacy export includes your devices, readings and bot permissions, and deleting your account removes device data right away. Every device reading is encrypted at rest with the key of the oldest workspace you own that has encryption turned on, when there is one. ## Limits - Reminders and photos have no collector in the app yet, so they don't appear in **Device connections**. A bot asking to add a reminder can't complete it. - Calendar on macOS, Windows and Linux isn't collected yet. - There's no background refresh for calendar, contacts and health. Data updates when you open the app. - Collectors haven't all been checked on real phones yet. ## Related - [Routines](/guide/routines) - [Your own computer](/guide/companion) - [Privacy and data](/guide/privacy) - [Autonomy and approvals](/guide/autonomy) # Group chats A group chat puts several bots in one conversation with you, so they can split a job and build on each other's work. Use one when a task needs more than one specialist, like a researcher, a writer and a designer working on the same launch. ## Create a group chat You need at least two bots in the workspace. 1. In the sidebar, select **Add** (the **+** button), then **New group chat**. 2. Under **Bots**, pick 2 to 10 bots. Each shows what it's doing now, and a number shows the order they join in. With more than six bots, a search field helps you find them. Archived bots aren't offered. 3. The strip at the top shows the group so far. The first bot you pick **Leads the group** and wears a crown. Tap another bot in the strip to make it the lead, or its **x** to take it out. 4. Optional: give it a **Name (optional)**. The field shows the name an unnamed group goes by, made from its bots. 5. Select **Create group chat**. Group chats are listed under **Group chats** in the sidebar, each with its number of bots. ## Choose who answers Who answers depends on how you address the message. As you type `@`, the app suggests the group's bots and `everyone`, and a line above the field says who will answer. | You write | Who answers | | --- | --- | | `@Ana find three examples` | Ana. Mention several bots to wake each of them. | | `@everyone plan the launch post` | The lead. It makes a plan that @mentions a bot for each part, and those bots start on their parts. | | No mention | The last bot that spoke, or the lead if no bot has spoken yet. | Every bot you wake works at the same time, in the same chat. Each reply is headed with the name of the bot that wrote it. Attachments and skills picked with `/` work as in any chat; see [Chatting with a bot](/guide/chat). ## Bots talking to bots When a bot's reply @mentions another bot in the group, that bot starts working too. This lets the lead hand out parts of a plan, or one bot ask another for help. To stop loops, a chain of bot-to-bot mentions stops after 6 hops for each message you send. Then the chat waits for a person. Bots treat each other's messages as chat, not as instructions from you. Each message from another bot reaches a bot labeled with who said it and that it didn't come from you. ### Turn bot-to-bot messages off Owners and admins can stop bots from messaging each other across the whole workspace. 1. Go to **Settings** → **Workspace settings**. 2. Turn off **Bots can talk to each other**. With the switch off: - A bot's @mentions of other bots in a group chat start no work. The chat shows a short note naming the bots that weren't told. - `@everyone` still reaches the lead, which can plan, but the bots it names aren't woken. - People can still @mention any bot, and each bot can still split its own work into subagents. - Bots can't hand work to each other with delegation either. See [Bots working together](/guide/bots-together). Changes to the switch are recorded in the workspace's audit log. ## What each bot keeps A group chat doesn't merge the bots. Each one keeps its own: - instructions, model and computer - memory (what it learns in the group goes to its own memory) - autonomy, action rules and approvals - budget, so one bot's spending never uses another's ## Who can see a group chat You see a group chat only if you can see every bot in it. If one of its bots is private and you're not on its sharing list, the whole group chat is hidden from you. See [Templates, sharing and import](/guide/sharing). ## Limits - You can't add or remove bots after creating a group chat. Create a new one instead. - Up to 10 bots per group chat. - Edit and resend, and Regenerate, aren't available in group chats; messages are kept in one line. - A message you send while bots are working doesn't join their runs. It starts new work for the bots it wakes. - Runs in group chats don't feed skill suggestions. See [Skills](/guide/skills). ## Related - [Chatting with a bot](/guide/chat) - [Bots working together](/guide/bots-together) - [Bots and models](/guide/bots) - [Autonomy and approvals](/guide/autonomy) # The Library The **Library** holds everything your bots make for you: sites and games, reports, pictures, videos, sounds, documents and other files. Things land there by themselves, so you don't have to dig back through a chat to find what a bot made last week. Open **Library** in the main navigation. On phones it's the tab between **Chats** and **Tasks**. ## What lands in the Library | Kind | What it is | How it gets there | | --- | --- | --- | | **Page** | A report, dashboard, site or game. See [Pages](/guide/pages). | Every page a bot publishes. | | **Image**, **Video**, **Audio** | Pictures, videos and spoken audio a bot generated. | Every one a bot makes in a chat. | | **Document** | A PDF, or a Word, PowerPoint or Excel file. | A file the bot links in a reply, or keeps on purpose. | | **File** | Anything else, such as a zip, a CSV or a song. | The same as documents. | Bots give each thing a short label, such as **Site**, **Game**, **Report** or **Source**, which shows on its tile. ### Files from the bot's computer The Library holds only what a bot hands over to you, not everything on its computer. A file reaches the Library when: - **The bot links it in a reply.** Before the reply is saved, Casama copies up to 8 linked files, each up to 50 MB, from the bot's computer. - **The bot keeps it on purpose.** Ask "keep that in my Library" and the bot saves the file without linking it. The copy belongs to the server, so it stays even when the computer sleeps or is reset. When the bot hands over the same file again with new contents, it becomes a new version of the same item. Casama keeps the last 5 versions. Files on [your own computer](/guide/companion) stay there. They are never copied to the Library. ### Documents When a kept file is a PDF or an Office document, the bot's computer also makes a PDF of it and a picture of its first page. The Library shows that first page as the tile's cover. **Open** opens the original file in your own apps. The app doesn't edit documents. To get an Office file you can edit, ask for it by name: "make this a .docx", "put it in a spreadsheet" or "turn this into slides". ## Find things The Library shows newest first: - **Projects** at the top, one card per project. See [Projects](/guide/projects). - **Pinned**, the things you pinned. - Then everything else under **Today**, **Yesterday**, **This week** and **Earlier**. To narrow it down: - **Search the Library** matches titles and labels. - **Kind chips** filter to **Sites & games**, **Images**, **Videos**, **Audio**, **Documents** or **Files**. Only the kinds your workspace has appear. **All** clears the filter. - **One bot's things:** open its **Bot profile** and tap **Library**. - **One project's things:** open the project and tap **See All** next to **Made in this project**. The app's search also has a **Library** scope that finds the same things. From a chat, long-press (or right-click) a page card, picture or video and choose **Show in Library**. After a bot publishes a page, the **Show in Library** button under it opens the Library on that bot's sites and games. If the Library is empty, it suggests a few things to ask for, such as **A small game** or **A one-page site**. Tap one to open **Quick ask** with the request typed in, ready for you to finish and send. ## Open something Tap a tile. On a phone it opens on its own screen; on a wide window it opens beside the grid. You see a preview, the title, which bot made it, when, its version and who can see it. | Kind | Main button | What happens | | --- | --- | --- | | Page | **Open**, or **Play** for a game | Opens in your browser, the same way as in [Pages](/guide/pages#find-and-open-pages). | | Picture, video, sound | **View** | Opens in the app's viewer or player. | | Document, file | **Open** | Opens with your device's own apps. | Below that: - **Project** opens the project it belongs to, when it has one. - **From your chat with** the bot goes back to the conversation it came from. - **Details** shows the kind, size and dimensions. - **Made alongside** lists the other things made in the same bot run. ## Change something Tap **Change It**. The chat it came from opens (or the bot's General chat, if that chat is gone) with `About “Title”: ` typed in. Finish the sentence and send it. The bot finds the item and makes the change, and a page or kept file gets a new version. The **…** menu has the rest: | Item | What it does | | --- | --- | | **Rename** | Changes the title. You can also tap the title. | | **Pin** / **Unpin** | Keeps it on your **Pinned** shelf. Pins are yours alone. | | **Who Can See It** | See [Share something](#share-something). | | **Move to Project** | Files it under a project, or **No Project** to take it out. See [Projects](/guide/projects#move-something-into-or-out-of-a-project). | | **Export PDF** | Pages only. See [Export a PDF](/guide/pages#export-a-pdf). | | **Delete** | See [Delete something](#delete-something). | **Rename**, **Who Can See It**, **Move to Project** and **Delete** appear only for the person it was made for, the people who manage the bot, and workspace admins. ## Share something Everything in the Library has one of three levels: | Level | Who can open it | | --- | --- | | **Only me** | For a page, the person it was made for and the people who manage the bot. For anything else, the people who can open the chat it was made in (a private chat stays private). With no chat, the person it was made for and the bot's managers. | | **Workspace** | Everyone in the workspace. A page goes to everyone who can see the bot. | | **Anyone with the link** | Anyone with the public link, signed in or not. | To make something public: 1. Open it, then open the **…** menu → **Who Can See It** → **Anyone with the link**. 2. Confirm **Make Public**. The **Public Link** appears and is copied for you. The link is shown only this once. Public links are hidden from search engines. What a public link shows: - **Pictures, videos and sounds** play on a simple page. - **Documents** get a link to open them, as a PDF when Casama made one. - **Other files** download instead of opening in the browser. - **Pages** open as the page. See [Share a page](/guide/pages#share-a-page). **To stop a link**, set it back to **Only me** or **Workspace**. The old link stops working at once. Making it public again creates a new link. A workspace can make up to 20 public links a day from the Library. ### Reports Every public link has a way for viewers to report it. When three different people report the same link, it's hidden until the server's owner looks at it. On a self-hosted server, the owner reviews reports through the API (`GET /v1/admin/reports`, and `POST /v1/admin/creations/{id}/takedown` to take one down). ## Delete something Open the **…** menu and tap **Delete**. It disappears from the Library at once, and **Undo** brings it back. After 30 days it's removed for good, along with its stored files. ::: warning A deleted page's public link Deleting a page from the Library hides it, but its public link keeps working until it's removed for good. To stop the link at once, set the page to **Only me** first, then delete it. ::: **Deleting a chat** keeps what was made in it. Those things stay in the Library, visible to the person they were made for. To delete them with the chat, tick **Also delete the N things made here** when you delete the chat. ## Copies The API can copy anything in the Library (`POST /v1/creations/{id}/duplicate`). The copy is private to you and titled "Copy of …". A page copies with its layout, data and files. The app doesn't have a copy button yet. A copy shares the stored bytes with the original instead of storing them twice, but its size still counts toward storage. Stored bytes are deleted only when nothing in the Library uses them any more. ## Storage On Casama Cloud, each plan includes Library storage for the workspace: | Plan | Storage | | --- | --- | | Free | 1 GB | | Plus | 10 GB | | Pro | 50 GB | | Max | 200 GB | Pages, a site's files, generated pictures, videos and sounds, and kept files all count. When the Library is full, new pages and kept files are refused and the bot tells you so. New pictures, videos and sounds stay on the bot's computer but aren't added to the chat or the Library. Nothing is ever deleted to make room. Delete things you don't need, or move to a bigger plan. See [Usage and budgets](/guide/usage). Self-hosted servers have no storage cap. ## For self-hosters The API and worker store the Library's files, and new generated pictures, videos and sounds, in an object store. Older media is moved out of the database a little at a time, so database backups stop growing with media. By default the store is the `library` Docker volume at `/data/library`, and [backups](/self-hosting/operations#back-up-your-server) include it as `library.tar.gz`. To use S3-compatible storage instead, set these in your `.env`: | Name | Default | What it does | | --- | --- | --- | | `LIBRARY_OBJECT_STORE` | (filesystem) | `s3` to use S3-compatible storage. | | `LIBRARY_OBJECT_DIR` | `/data/library` | Folder for the filesystem store. | | `LIBRARY_S3_BUCKET` | (empty) | Bucket name. | | `LIBRARY_S3_ENDPOINT` | (AWS) | Endpoint, for example `https://.r2.cloudflarestorage.com`. | | `LIBRARY_S3_REGION` | `auto` | Region. | | `LIBRARY_S3_ACCESS_KEY_ID` | (empty) | Access key. | | `LIBRARY_S3_SECRET_ACCESS_KEY` | (empty) | Secret key. | | `LIBRARY_S3_PREFIX` | `library/` | Key prefix inside the bucket. | With S3, `library.tar.gz` isn't made; back up the bucket with your storage provider's tools. Public links and pages are served from the pages address (`PAGES_URL`), never from the app's own address. See [Pages for self-hosters](/guide/pages#for-self-hosters). ## For developers The Library is in the [API](/develop/api) under `/v1/creations`: | Route | What it does | | --- | --- | | `GET /v1/creations` | Lists items. Filters: `kind`, `bot_id`, `conversation_id`, `project_id`, `pinned`, `q`, `sort` (`new` or `opened`) and `deleted=true` for the last 30 days' deletions. | | `GET /v1/creations/{id}` | One item, with what was made alongside it. | | `PATCH /v1/creations/{id}` | Changes `title`, `label`, `pinned`, `visibility` (with optional `expires_in_days` for a public link), or `project_id`. | | `DELETE /v1/creations/{id}` | Deletes it. `POST /v1/creations/{id}/restore` undoes that. | | `GET /v1/creations/{id}/content` | The bytes. | | `GET /v1/creations/{id}/cover` | The cover picture. | | `GET /v1/creations/{id}/preview` | A document's PDF. | | `POST /v1/creations/{id}/duplicate` | A private copy. | The CLI has no Library commands yet. ## Limits - The app can't copy items, set an expiry on a public link, or show older versions. Copies and expiry are available through the API. - The app doesn't preview a document's PDF; **Open** opens the original file. - Pages don't get a picture cover yet. The app draws one from the title and kind. - The Library doesn't update live. It refreshes when you open it or pull down. - Workspaces can't see how much storage they've used in the app yet. ## Related - [Pages](/guide/pages) - [Projects and the ticket board](/guide/projects) - [Chatting with a bot](/guide/chat) - [Computers](/guide/computers) - [Usage and budgets](/guide/usage) - [API](/develop/api) # Connect AI apps to Casama (MCP) Casama is an MCP server, so AI apps such as Claude Code, Cursor and other MCP clients can list your bots, give them tasks and read the results. Use it when you work in another AI app and want a Casama bot, with its own computer, memory and tools, to do part of the job. There are two ways to connect: | | Hosted, by URL | Local, over stdio | | --- | --- | --- | | Address | `https:///mcp` (Streamable HTTP) | The `casama-mcp` command from `@casama/mcp` | | Best for | Apps that only take a URL: web and mobile AI apps, custom connectors | Desktop coding tools | | Sign-in | OAuth, or a workspace API key | Your `casama login` session, or `CASAMA_TOKEN` | | Scope | One workspace | Every workspace you belong to | Both give the same tools, and your bots' approvals, action rules and budgets apply either way. Building something on Casama? The [docs tools](#docs-tools-for-building-on-casama) let a coding agent search these docs and the API reference, with no sign-in. This page is about AI apps using Casama. To let your bots use other MCP servers as tools, see [Connections](/guide/connections). ## Find your address 1. Open **Settings → Workspace settings** and open **Advanced**. 2. Under **Connect AI Apps**, copy the address. It's your API's address followed by `/mcp`, for example `https://api.example.com/mcp`. Self-hosters can set the advertised address with `PUBLIC_API_URL`; otherwise Casama uses the address the request came in on. ## Hosted with OAuth (recommended) 1. In your AI app, add a custom connector or remote MCP server and give it the address: ```text https://api.example.com/mcp ``` 2. The app finds Casama's sign-in on its own, registers itself, and opens Casama in your browser. 3. On the screen that says the app wants to use Casama, pick the **Workspace** and tap **Allow** (or **Refuse**). 4. When you see **Done. You can go back to the AI app.**, return to the app. The app acts as you, in that one workspace only. Its access token lasts an hour. The app renews it with a refresh token that lasts 60 days and is replaced each time it's used. Connections are recorded in the workspace's audit log. ## Hosted with an API key Use a key for apps that don't support OAuth, or for scripts. Owners and admins create keys. 1. Open **Settings → Workspace settings → Advanced → Connect AI Apps**. 2. Tap **New API Key**, enter a **Name** and tap **Create**. 3. Copy the key (it starts with `ksk_`). It isn't shown again. The key acts as the person who created it, in that workspace only. Revoke it there at any time. A key or OAuth connection also stops working if that person leaves the workspace. Cursor (`~/.cursor/mcp.json`): ```json { "mcpServers": { "casama": { "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer ksk_..." } } } } ``` Claude Code: ```sh claude mcp add --transport http casama https://api.example.com/mcp \ --header "Authorization: Bearer ksk_..." ``` Any client that supports Streamable HTTP with custom headers works the same way. ## Local over stdio The local server runs on your machine and uses the same sign-in as the Casama CLI. 1. Sign in with the CLI: ```sh casama login ``` 2. Add the server to your tool. Claude Code: ```sh claude mcp add casama -- npx -y @casama/mcp ``` Any tool that takes a JSON config: ```json { "mcpServers": { "casama": { "command": "npx", "args": ["-y", "@casama/mcp"] } } } ``` | Environment variable | What it does | | --- | --- | | `CASAMA_API_URL` | Your Casama API. Default: the address from `casama config`, else `https://api.casama.ai`. | | `CASAMA_TOKEN` | An access token to use instead of the CLI's saved session | | `CASAMA_CONFIG_DIR` | Where to find the CLI's saved session and config | | `CASAMA_DOCS_URL` | Where the docs tools read the docs. Default: `https://docs.casama.ai` | With the CLI session, the server refreshes your sign-in as needed. See [CLI](/develop/cli). ## Tools | Tool | What it does | | --- | --- | | `list_workspaces` | Workspaces you belong to, with your role | | `list_bots` | Bots in a workspace, with their status. Takes an optional workspace slug, name or id. | | `ask_bot` | Sends a message to a bot (by name or id) and waits for the run to finish, fail or need approval. Returns the reply, the tools used, the cost, and the conversation and run ids. Pass `conversation_id` to continue a thread. | | `get_run` | A run's status and cost, and its recent events: tool calls, outputs and errors | | `list_approvals` | Actions waiting for approval in a workspace | | `decide_approval` | Approves or denies a pending action. The bot continues, or skips the step, right away. | Both servers also have the [docs tools](#docs-tools-for-building-on-casama), and the local one has `check_plugin` and `gallery_search`. `ask_bot` waits up to 10 minutes. If the bot needs approval, the result says `waiting_approval`; approve it in the Casama app, or with `decide_approval` if your workspace allows it. ## Docs tools for building on Casama For people building on Casama, and their coding agents, there's a docs-only server at `https://api.casama.ai/mcp/docs`. It needs no sign-in and can't see any account. A self-hosted server has one too, at `/mcp/docs`, reading the docs shipped with that server. ```sh claude mcp add --transport http casama-docs https://api.casama.ai/mcp/docs ``` | Tool | What it does | | --- | --- | | `search_docs` | Searches these docs by keyword and returns the best-matching sections, with their address | | `read_doc` | One page as markdown, by path (`/develop/plugins`) or address. Pass `section` for one section. | | `list_doc_pages` | Every page, with its title and address | | `get_api_operation` | Looks up the [HTTP API](/develop/api) by operationId (`sendMessage`), `METHOD /path` or keywords, and shows the parameters, request body and responses as types | | `check_plugin` | Local server only: checks a [plugin](/develop/plugins) folder the way Casama does at install | | `gallery_search` | Local server only: searches the [gallery](https://gallery.casama.ai) for ready-made skills, apps, routines, bots, plugins, starter sets and looks, so an agent reuses one before building it | The local server has these tools too. To run only them, with no sign-in: ```sh claude mcp add casama-docs -- npx -y @casama/mcp --docs-only ``` See [Build with AI agents](/develop/agents) for the other ways agents can learn Casama. ## Allow approvals from AI apps By default, connected apps can't approve or deny your bots' actions, so a bot can't get its own risky step approved by the app that asked for it. To change that, an owner or admin opens **Settings → Workspace settings → Advanced → Connect AI Apps** and turns on **Allow Approvals from AI Apps**. | Connection | Can use `decide_approval` | | --- | --- | | OAuth or API key | Only when **Allow Approvals from AI Apps** is on | | Local stdio with your own sign-in | Yes, like the app | Either way, a high-risk step still stops and waits for a decision. See [Autonomy, approvals and action rules](/guide/autonomy). ## Limits - The local server needs Node.js 20 or later. - OAuth connections and API keys don't count as a two-step sign-in. In a workspace that requires two-step sign-in for admins, they get member access only. - The **Connect AI Apps** section is shown to owners and admins only. - OAuth sign-in only accepts apps whose redirect address is `https` or `localhost`. ## Related - [Connections](/guide/connections) - [Autonomy, approvals and action rules](/guide/autonomy) - [CLI](/develop/cli) - [API](/develop/api) - [Build with AI agents](/develop/agents) - [Talk to outside agents (A2A)](/develop/a2a) # Meeting notes Casama doesn't send a bot into your calls. Instead, a bot works from the notes your meeting app already takes, or from your calendar, and turns them into a summary, decisions and action items you can find later. ## Connect a notes app Connect the app that records or transcribes your meetings, then give it to the bot. These come from the [open gallery](https://gallery.casama.ai/#app) and connect with one click: | App | What a bot can read | | --- | --- | | Fireflies | Meeting transcripts and summaries | | Granola | Meeting notes and transcripts | | Circleback | Meeting notes and action items | | Otter | Meeting transcripts and summaries | | Fathom | Recordings, notes and summaries | | tl;dv | Recordings and notes | | MeetGeek | Recordings and summaries | | Krisp | Meeting notes and transcripts | | Plaud | Recordings, transcripts and summaries | 1. Open **Settings** → **Integrations**, pick the **Browse** tab and search for your app. 2. Connect it and choose which bots can use it. See [Apps and connections](/guide/connections). You can also just ask a bot in chat to connect it; it shows a **Connect** button. With no notes app, a bot can still work from your calendar events and from notes you send it. ## File the day's notes every evening The **Meeting notes** routine idea does this for you each weekday at 6 p.m.: - It gathers the day's notes from your connected notes app, or else from today's calendar events and anything you sent the bot. - For each meeting it writes a three-line summary, the decisions, and the action items with owners and dates. - It saves one Markdown file per meeting in the team folder, `shared/meetings/`, and links them in its reply. - It asks you before it sends anything to anyone. To set it up: 1. Open the bot's chat, open the **More** menu and tap **Bot profile**, then **Routines**. 2. Tap **New routine**, then **Meeting notes** under **Ideas**. 3. Change the instructions or time if you like, then tap **Create**. See [Routines](/guide/routines) for editing, pausing and ending routines. ## Right after each meeting A meeting routine can also run a set time after each meeting ends, such as "5 minutes after every standup ends", so the notes are ready while the meeting is fresh. In the app, **Meetings** routines count from the meeting's start (up to **15 min** after). To count from the end, create the routine through the [API](/develop/api) with `anchor: "end"` on its calendar trigger: ```json { "bot_id": "…", "name": "Standup notes", "instructions": "Get this meeting's notes from my notes app and file them in shared/meetings/.", "trigger": "calendar_event", "calendar": { "integration_id": "…", "offset_minutes": 5, "anchor": "end", "title_match": "standup" } } ``` Send it to `POST /v1/routines`. `offset_minutes` counts from the end, so `5` is five minutes after the meeting ends. The other calendar filters work as in the app. See [Meeting triggers](/guide/routines#meeting-triggers). ## Limits - Casama has no meeting bot that joins calls and records them. Use a notes app for that. - Counting from a meeting's end is set through the API only; the app doesn't offer it yet. - The notes-app connections follow each vendor's public docs and haven't all been tried with real accounts. ## Related - [Routines](/guide/routines) - [Apps and connections](/guide/connections) - [Computers](/guide/computers) - [Library](/guide/library) # Memory and knowledge Bots remember what matters about you and your work, so you don't repeat yourself: something you tell a bot in one chat, it can recall in the next. Knowledge is different: it's documents you give a bot, such as files, a website or a GitHub repository, that it searches and cites when they're relevant. | | Memory | Knowledge | | --- | --- | --- | | What it holds | Short notes: facts, preferences, summaries of past work | Your documents, split into passages | | Where it comes from | The bot writes it as you chat | You add sources; Casama reads them | | How the bot uses it | The most relevant notes are in every run | The bot searches it when a question calls for it, and cites the source | | Where to manage it | **Memory** | **Bot profile** → **Knowledge** | ## What bots remember Each bot has its own memory; bots never read each other's. A memory is one of these kinds: | Kind | What it is | | --- | --- | | **Fact** | Something true about you, your work or the people you work with. | | **Preference** | How you like things done, such as a writing style or a format. | | **Episode** | A summary of an earlier part of a long conversation. | | **Summary** | A summary of past work. | Memories are written three ways: - **After every run**, the bot's cheap model reads the latest exchange and saves up to 10 lasting facts and preferences. Small talk and one-off requests are skipped. - **When you ask**, the bot saves a memory itself ("remember that I'm in America/Chicago"). Saving a memory never needs your approval, whatever the bot's autonomy. - **When a chat gets long**, older messages are summarized once the chat's history passes about 16,000 tokens (or 70% of the model's context window, if that's smaller), and the summary is saved as an episode. A new memory that says nearly the same thing as an existing one updates it instead of adding a copy. Without embeddings, only exact duplicates are caught. ### How bots recall At the start of every run, the bot gets the 8 memories most relevant to your message, plus every pinned memory. Casama finds them by meaning and by matching words together. Matching by meaning needs embeddings. They use the workspace's OpenAI API key, or else the server's shared OpenRouter key (as on Casama Cloud). Without either, recall matches words only. ChatGPT plan sign-in doesn't provide embeddings. ## View and edit memory 1. Open a bot's chat, select **More** (the **…** button) → **Bot profile**, then **Memory**. 2. Each memory shows its kind. Type in the search field to filter the list: every word you type must match, in any order. 3. Open a memory's menu for: - **Pin** or **Unpin**: pinned memories are always in the bot's context. - **Edit**: change the text. The bot uses the new version the next time it's relevant. - **Delete**: the memory is gone for good. ### Add a memory yourself 1. On the **Memory** screen, select **Add a Memory** (the **+** button). 2. Choose **Fact** or **Preference** and write it, for example "Our fiscal year starts in April". 3. Select **Save**. It's stored like any memory the bot saved. Only people who manage the bot can add memories here. You can also tell the bot in chat, or import memories (below). From the CLI: ```sh casama memory list Ada casama memory list Ada --search "timezone" ``` ## About you Bot memory belongs to one bot. **About you** belongs to you, and every bot you use reads it, in every workspace. Open it from the card at the top of **Settings**. Your profile photo is set here too: tap it to **Take a Photo**, **Choose a Photo** or **Remove Photo**. If you signed in with Google, your Google photo is copied the first time, and **Use My Google Photo** brings it back. Your photo shows on your avatar and in the workspace's member list. | Field | Where bots use it | | --- | --- | | **What should bots call you?** | Everywhere. Filled in from your sign-in name, and asked once in the welcome chat. | | **Pronouns** (optional) | Everywhere. | | **How I like replies** | Everywhere, for example "short answers, no emoji". | | **About me** | Only where it's shared (see below). | | **What bots learned** | Only where it's shared (see below). | When a bot learns something about you in chat (your job, family, places, tastes), it saves it to About you instead of its own memory, which other people using that bot can see. The chat shows **Saved to your profile** with **Undo**. Facts about the work, like projects, clients and tools, stay in the bot's memory. Bots don't save health, religion, politics, sexuality or money troubles unless you ask them to remember it. To stop bots saving facts about you, turn off **Learn about me from chats**. You can add, edit, pin and delete facts yourself, and **Import from ChatGPT or Claude** fills them from another assistant's memory. **Where it's shared:** About me and learned facts are used only in workspaces where you're the only member. In a team workspace they're off until you turn on **Use what I've shared in …** for that workspace, and they switch off by themselves when someone else joins one of your workspaces. Only you can see About you. It's in your data export and is deleted with your account. While you belong to a workspace with encryption at rest turned on, About you is encrypted with a key of your own. ## Import memories from ChatGPT or Claude If ChatGPT or Claude already knows you, bring that over. 1. Open the bot's **Memory** screen and select the import button (**Import memories from ChatGPT or Claude**). 2. **Copy** the prompt into ChatGPT or Claude, then paste its answer under **Its answer** and select **Next**. 3. Casama turns the answer into facts and preferences. Untick anything that's wrong, then select **Save**. Only people who manage the bot can import memories. See [Templates, sharing and import](/guide/sharing) for importing whole agents. ## Where memory is kept By default, memory lives in your Casama database. Workspace owners and admins can keep it in Honcho or Supermemory instead, with the workspace's own account. The memory screen, data export and account deletion work the same either way. 1. Go to **Settings** → **Workspace settings** → **Where memory is kept**. 2. Pick **Supermemory** or **Honcho** and paste the **API key**. 3. Optional: for Honcho, a **Honcho workspace** (leave empty to use one made for this Casama workspace). For a self-hosted Honcho or Supermemory, its **Server address**. 4. Turn on **Copy current memories over** to bring every bot's memories along, pinned ones included. 5. Select **Save**. Casama checks the connection before saving. To go back, open the same sheet and choose **Use built-in memory again**. Memories saved in the provider stay there, and built-in memories were never removed. ::: warning Honcho deletes Honcho can't delete a single message, so deleting a memory there hides it instead of erasing it. Deleting your account deletes each bot's whole Honcho session. ::: ## Add knowledge Give a bot documents to search and it answers from them and names the source. 1. Open **Bot profile** → **Knowledge**, then **Add knowledge**. 2. Choose what to add: - **Files**: select **Choose files** and pick PDF, Word (`.docx`), Markdown, HTML, CSV or text files, up to 50 at a time. - **Website**: enter the **Website address**. Casama reads up to 50 pages on the same site. - **GitHub**: paste a **GitHub link** to a repository. Casama reads up to 300 of its Markdown, text, HTML and CSV files. 3. Workspace owners and admins can turn on **Share with every bot in the workspace**. 4. Select **Add**. Sources are read within about a minute. Each one shows **Waiting to be read**, **Reading…**, the number of documents and passages, or why it couldn't be read. Use **Sync now** to read a source again, or **Delete** to remove it. PDFs are read page by page, and a PDF's own title is used when it has one. A scanned PDF has no text to read, so it fails with "This PDF has no text to read, probably because it's a scan" instead of being added empty. Upload a version with selectable text. Website crawls follow the site's `robots.txt` and identify as `CasamaBot`. Private repositories use the workspace's `GITHUB_TOKEN` secret (allowed for `api.github.com`). See [Apps and connections](/guide/connections). ### How knowledge stays current - Uploaded files are read once. - Websites, repositories and connection sources refresh every 24 hours. Through the API you can pick any interval from 1 to 168 hours when you add a source (`sync_every_hours`). - A refresh only re-embeds passages that changed, and a source with no changes isn't rewritten at all, so frequent refreshes of a site that rarely changes cost almost nothing. - A source that fails is retried in 6 hours. One unreadable file is reported without stopping the rest. ### How bots use knowledge When a question calls for it, the bot searches its own sources and the workspace's shared ones, using the same meaning-and-words search as memory. Results come back as numbered passages with the document, where in it (a heading, a page, or rows of a CSV) and a link, and the bot is asked to cite them. In the chat, the search step lists the sources it used. Everyone who can chat with a bot shares its knowledge, because sources belong to the bot or the workspace, not to a person. Only the bot's managers can change its sources, and only admins can change shared ones. ## Encryption With encryption at rest turned on, memories and knowledge passages are encrypted before they're stored. Search then matches by meaning, not exact words in encrypted text. See [Privacy and security](/guide/privacy). ## Limits - **Scanned PDFs** can't be read: text recognition (OCR) isn't supported. - **Connection sources** (indexing what a connected app such as Notion or Google Drive returns) work through the API only (`POST /v1/knowledge-sources` with `kind: connection`). Changes in the app are picked up by the next refresh, not right away. - The app can't change how often a source refreshes, and the interval can't be changed after a source is added. - The app can't change a website's page limit. Through the API, `max_pages` goes up to 200. - Honcho and Supermemory catch only exact duplicate memories, not near-duplicates. Memories can't be moved back from a provider to built-in memory. - Search in the chat shows sources on the search step, not as a separate list under the reply. ## Related - [Chatting with a bot](/guide/chat) - [Templates, sharing and import](/guide/sharing) - [Privacy and security](/guide/privacy) - [Bots and models](/guide/bots) # Pages A page is a small web page a bot publishes for you: a report, a dashboard, a tracker, a site or a game. Ask for one when an answer is better as something to look at, keep, play or share than as a chat message: a weekly sales summary, a project tracker, a trip itinerary, a sign-up form, a small browser game. Pages open in your browser, stay private until you share them, and are kept in the [Library](/guide/library). ## Ask a bot for a page Ask in chat, for example: "Make a page that tracks our open bugs by severity, and refresh it every morning." The bot writes the page and publishes it. The reply shows a page card (**Page · Tap to open**). Tap it to open the page. Under the bot's publishing step, **Show in Library** opens the Library on that bot's sites and games. A new page is private unless the bot was asked to share it with the workspace. A page can refresh itself on a schedule. The bot links a routine that updates the page's data while the layout stays the same. To change a page, ask the bot, or open it in the Library and tap **Change It**. The bot can replace the layout, update only the data, or change who can see it. Bots can only change their own pages. ## Sites and games For a site or game with its own pictures, sounds, scripts and styles, the bot builds a folder on its computer with an `index.html` and publishes the whole folder. Ask for "a small game I can play in the browser" or "a one-page site for my business". - A site or game can have up to 300 files and 25 MB in all. - Its files load only from Casama's page address. Nothing from other sites can load. - In the Library, a game's main button is **Play**; other pages show **Open**. - Publishing the page again as one HTML file drops its files. Code and other working files stay on the bot's computer. To keep a copy that outlives the computer, ask the bot to keep the folder in your Library. See [Projects](/guide/projects#files-and-code). ## Pages that take input A page can collect answers, such as a sign-up sheet, an RSVP, a feedback form or a quiz. Ask for it, and say what should happen with each answer: "Make an RSVP page for Saturday's dinner, and tell me each time someone answers." - Answers go only to the page's own address, never to another site. - Each answer can be up to 64 KB. On a public page, each visitor can send up to 20 answers an hour. - The bot reads the answers when you ask ("who has signed up so far?"). If you told it what to do with each answer, a routine starts a run for every new one. See [Routines](/guide/routines). - Answers can be read by the person the page was made for and the people who manage the bot, through the bot. In a workspace that encrypts its content, they are encrypted like other content. See [Privacy](/guide/privacy#encrypt-workspace-content). Bots are told never to ask for passwords, card numbers or other secrets on a page. Treat answers from a public page as coming from strangers. A page only takes input when the bot publishes it that way. Other pages can't send anything. ## Find and open pages - **All pages:** open **Library** and pick **Sites & games**. - **One bot's pages:** open its **Bot profile** → **Library**. - **From a chat:** tap the page card, or long-press (or right-click) it and choose **Show in Library**. Pages open in the browser, never inside the app's own screens: | Platform | Where a page opens | | --- | --- | | iOS | Safari View Controller, inside the app | | Android | Chrome Custom Tabs, inside the app | | macOS, Windows, Linux | Your default browser | | Web | A new tab | For private and workspace pages, the app gets a single-use link that works for 60 seconds and only for you. Your browser then keeps access to that one page for 30 minutes. Access is checked again on every load, so removing someone's access works at once. ## Share a page Each page has one of three visibility levels: | Visibility | Who can open it | | --- | --- | | **Only me** | The person the page was made for, plus the people who manage the bot. | | **Workspace** | Everyone who can see the bot. | | **Anyone with the link** | Anyone with the public link, signed in or not. | To make a page public: 1. Open the page in the **Library**, then open the **…** menu → **Who Can See It** → **Anyone with the link**. 2. Confirm **Make Public**. The **Public Link** appears and is copied for you. Public links are hidden from search engines, and every public page has a way for viewers to report it. To take a link back, set the page to **Only me** or **Workspace**; the old link stops working. Making it public again creates a new link. A bot can share a page too. Making a page public is a high-risk action and sharing it with the workspace is medium risk. Both follow the bot's autonomy and any **Sharing and invites** action rule. See [Autonomy and approvals](/guide/autonomy). Anyone who can open a page can export it. Changing its visibility or deleting it is for the person it was made for, the people who manage the bot, and workspace admins. Making a page public, or taking it back, is recorded in the audit log. See [Share something](/guide/library#share-something) for public links and reports. ## Export a PDF Open the page in the **Library**, then open the **…** menu → **Export PDF**. The PDF is the same page, printed by the server, and opens where pages open. ## Delete a page Open the page in the **Library**, then open the **…** menu → **Delete**. It leaves the Library at once, and **Undo** brings it back. After 30 days it's removed for good. Until then, a public link to it keeps working and its refresh routine keeps running. To stop them at once, set the page to **Only me** and turn the routine off in **Routines** before you delete it. ## What a page can and can't do A page is an HTML document with a block of JSON data, plus its own files for a site or game. The same page serves the app, public links and PDF export. - **No outside requests.** Pages can't load scripts, styles, images or data from other sites. A one-file page must build in its images and fonts; a site or game loads them from its own files. Only [pages that take input](#pages-that-take-input) can send anything, and only to their own address. - **No Casama actions.** Buttons on a page can't call Casama or the bot. To act on what you see, go back to the chat. - **Theme.** Pages don't take on your app theme. Bots are asked to use the light and dark colors Casama provides, so pages follow your system's light or dark mode. - **Size.** The HTML can be up to 2 MB and the data up to 1 MB. A site or game's files can be up to 25 MB more. - **Versions.** Casama keeps the last 20 versions of each page. - **Storage.** Pages count toward the workspace's Library storage on Casama Cloud. See [Storage](/guide/library#storage). ## For self-hosters Pages are served from their own address, separate from the app, so a page can never touch your Casama session. Set `PAGES_URL` to its public address and `PAGES_PORT` to serve it from the API process. A site or game's files are kept in the Library's object store; see [The Library for self-hosters](/guide/library#for-self-hosters). PDF export runs in a separate container: turn on the `pdf` Compose profile and set `PDF_RENDERER_URL=http://pdf:3000`. See [Page PDFs](/self-hosting/configuration#page-pdfs). ## Limits - On a self-hosted server, **Export PDF** fails until the server admin turns on the `pdf` profile. - The app doesn't set an expiry on public links, restore old versions or list a page's answers. Expiry and old versions are available through the API (`PATCH /v1/pages/{id}` with `expires_in_days`, and `POST /v1/pages/{id}/revert`); ask the bot for the answers. - Sites can't run code on a server or use your own domain. - When a site is published again, its older versions' files stay stored until the page is deleted. ## Related - [The Library](/guide/library) - [Chatting with a bot](/guide/chat) - [Routines](/guide/routines) - [Autonomy and approvals](/guide/autonomy) - [API](/develop/api) # Payments with approval A bot can pay a merchant for you, such as checking out an order on a website, with a single-use virtual card that you approve each time. Cards come from your workspace's own Stripe Issuing account, and the bot never sees the card number. ## Set up payments Workspace owners connect payments once. 1. In Stripe, make sure your account has Issuing. 2. In Casama, open **Settings** → **Workspace settings** → **Payments**. 3. Enter your **Stripe secret key (with Issuing)**. 4. In Stripe, add a webhook pointing at the address shown under **Point a Stripe webhook here**, for the `issuing_authorization.request` and `issuing_authorization.created` events. Paste its **Webhook signing secret** into Casama. 5. Fill in the cardholder details: **Name on cards**, email, address and country. 6. Set the limits (see below), then tap **Save**. Casama checks the key before saving, stores the key and signing secret encrypted, and creates the cardholder in your Stripe account. ## Spending limits | Limit | Default | What it caps | | ------------------------------------- | ------- | --------------------------------------------- | | **Workspace limit per month (USD)** | $500 | Approved amounts across all bots this month | | **Per-bot limit per month (USD)** | $200 | Approved amounts for each bot this month | Limits count the amounts of issued and used cards in the current calendar month. A request that would go over a limit is refused before any card exists. The **Payments** row shows how much has been spent this month. ## How a payment works 1. The bot asks to pay, with the merchant, amount, currency and reason. 2. You get an approval card showing the amount and merchant, such as "for $89.50". Approve or deny it. 3. When you approve, Casama issues a virtual card for that one purchase. 4. The bot fills in the checkout form. It gets placeholders, not card details, and Casama fills the real number, expiry date and security code into the page. 5. When the merchant charges the card, Stripe asks Casama to approve it in real time. Casama approves only the right charge, then cancels the card. ::: warning Payments always ask Every payment asks you first, whatever the bot's autonomy level, "always allow" grants or action rules. Choosing "always allow" on a payment approval has no effect. ::: ## Card rules Each card is: - **Single use.** After the first approved charge, the card is cancelled. - **Limited to the amount plus 5%**, to cover tax or small differences. - **Limited to one hour.** Unused cards are cancelled automatically. - **Tied to the merchant.** A charge is approved only if a distinctive word from the approved merchant's name appears in the charge's merchant name, the currency matches, the amount is within the 5%, and the card is still valid. Some purchases are never allowed, and no rule can relax this. Casama refuses these before a card exists, based on the merchant and reason: - Securities, stocks and brokerages - Crypto - Gift cards and prepaid cards - Money transfers and wires - Payment apps used to pay individuals As a backstop, every card also blocks these merchant categories: securities brokers, money orders, stored-value and gift card loads, wires, financial institutions, cash disbursements and gambling. ## Keeping card details private The bot only ever handles placeholders. Casama fills them in only: - in tools that accept secrets, such as filling a web form or making an HTTP request, - for the card issued to that same run, while it's still valid. Filled values are scrubbed from tool output, so card details never reach the model, the timeline or the logs. ## Review payments The **Payments** section in workspace settings lists the five most recent cards, with the amount, merchant, status and reason. Statuses include issued, used, declined, expired and canceled. ## Limits - Payments work only with your own Stripe Issuing account. Casama-issued cards on Casama Cloud aren't offered. - Only owners can set up payments and change the limits. - The per-bot limit applies to every bot. There's no setting to give one bot a different limit yet. - Monthly limits are set in US dollars and compared with each card's amount as requested, without currency conversion. - The Stripe connection follows Stripe's public API docs and has been tested against a stand-in, not yet against a live Issuing account. ## Related - [Autonomy and approvals](/guide/autonomy) - [Apps and connections](/guide/connections) - [Usage and budgets](/guide/usage) - [Privacy and data](/guide/privacy) # Privacy and security Your chats, memories and files belong to you. This page covers how to export your data, delete your account, control how long run history is kept, encrypt workspace content, and protect your sign-in. It also explains what Casama never sends to a model or anywhere else. ## Report or block If a bot's reply is harmful, long-press it (or right-click on a computer) and choose **Report reply**. You can also report a bot shared with your team from its profile, a gallery item from its page, and a person from **Settings > People**. Reports go to the people who run the server, who review each one and can take content down or suspend a workspace. Tap a person in **Settings > People** to **block** them. Blocked people can't invite you to a workspace, and reporting someone blocks them too. See and undo blocks in **Settings > Privacy > Blocked people**. ## Export your data 1. Open **Settings**, and under **Sign-in & security**, tap **Privacy**. 2. Under **Your Data**, tap **Export My Data**. 3. Save or share the ZIP file. The app shows **Export ready** with its size. From the CLI: ```sh casama account export # writes casama-export-.zip casama account export -o my-data.zip ``` The export is built with your own permissions, so it holds exactly what you can see. It contains `account.json`, `workspaces.json`, and a folder per workspace with JSON files for bots, conversations, messages, attachments, runs and their events, approvals, memories, skills, routines, tickets, computers, checkpoints, connections, usage, billing records, members and the audit log. It never contains secret values, model keys, token hashes, device push tokens, memory vectors or voice audio. Secrets and keys appear by name only. The export doesn't include what bots made in the [Library](/guide/library), such as pages, pictures and kept files. Open or download those from the Library. To keep one chat, export it on its own as Markdown or JSON (`GET /v1/conversations/{id}/export`). ## Delete your account 1. Open **Settings → Privacy**. 2. Under **Danger Zone**, tap **Delete My Account**. 3. Type your email to confirm. You're signed out everywhere at once, your devices stop receiving push notifications, and the app shows the date your data will be erased. From the CLI: ```sh casama account delete --confirm ana@example.com ``` ### What gets deleted | What | When | | --- | --- | | Your sessions, push devices and shared device data | Right away | | Workspaces where you're the only owner, with their bots, chats and computers (including computer snapshots) | After the grace period | | Your account | After the grace period | | Your membership in workspaces that have another owner | After the grace period; the workspace and its data stay | The grace period is set by the server with `ACCOUNT_DELETION_GRACE_DAYS` (0 to 30 days, default 7). The confirmation screen shows the exact date. ::: warning A workspace where you're the only owner is deleted with your account, even if other people use it. There's no screen for making someone else an owner yet, so ask for help first if the workspace should stay. ::: ## Run history retention Every run keeps a timeline of events: tool calls, outputs and errors. Workspace owners and admins choose how long to keep it. 1. Open **Settings → Privacy**. 2. Under **Workspace**, set **Keep Run History For**: 30, 90, 180, 365 or 730 days. The default is 180 days. Older run events are deleted automatically every day. Through the API you can set any value from 7 to 3650 days (`run_event_retention_days`). ## Encrypt workspace content Workspace owners can encrypt content before it's stored in the database, using a key that belongs to the workspace. 1. Open **Settings → Workspace settings**. 2. Under **Encrypt Content**, tap **Turn On** and confirm. The status shows **Turning on: encrypting what's already stored** while existing content is encrypted in the background, then **On, with the server's key** or **On, with AWS KMS**. Turning it off decrypts everything the same way, then deletes the key once nothing uses it any more. What's encrypted: messages, run event details, memories, conversation summaries, tickets and their comments, pages (with their versions) and knowledge text. What changes when it's on: - Exact-word search no longer matches text inside encrypted content. Titles and names still match, and memory and knowledge search still work by meaning. - If the workspace is deleted, its key is destroyed and the content can't be recovered. - You don't keep or copy any key. Casama creates the workspace's key and wraps it with the server's key. To rotate, tap **Rotate Key**. This rewraps the workspace key with the server's current key; content stays readable and nothing is re-encrypted. If you think a copy of the database has leaked, rotating isn't enough: whoever has the copy and the old server key could still open it. An owner can instead replace the workspace's key through the API (`POST /v1/orgs/{id}/encryption/replace-key`). New content uses the new key at once, and existing content moves onto it in the background; everything stays readable meanwhile. This also replaces the About you keys of the workspace's members. On a self-hosted server, the instance owner can replace every key on the server at once. There's no button for this in the app yet. ::: tip Self-hosting Encryption needs `CONTENT_ENCRYPTION_KEY` (32 bytes, base64) or an AWS KMS key on the server. `install.sh` generates the key for new installs and fills it in on older ones the next time it runs. Without one, the setting reads **Not available: this server has no encryption key set up**. See [Configuration](/self-hosting/configuration). ::: ## Two-step sign-in Two-step sign-in asks for a 6-digit code from an authenticator app every time you sign in. 1. Open **Settings → Two-step sign-in**. 2. Tap **Set Up an Authenticator App**. 3. Scan the QR code with an authenticator app (such as 1Password, Google Authenticator or Authy), or type in the **Setup key**. 4. Enter the **6-digit code** and tap **Verify**. You can add more than one authenticator with **Add Another Authenticator**, and rename or remove each one. Removing your only authenticator turns two-step sign-in off. After you enter your password, the app asks **Enter your code** before anything else. The CLI asks for the code too, or takes it from `casama login --code` or the `CASAMA_2FA_CODE` environment variable. Workspaces can require two-step sign-in for owners and admins. See [Workspaces and teams](/guide/workspaces#require-two-step-sign-in-for-admins). ## Passkeys A passkey signs you in with Face ID, a fingerprint or your screen lock, with no password or email. 1. Open **Settings**, and under **Sign-in & security**, tap **Passkeys**. 2. Tap **Add a Passkey** and follow your device's prompt. Each phone, computer or password manager keeps its own passkey. Add more with **Add Another Passkey**, and rename or remove each one. ## Public links Anything you share with a public link can be opened by anyone who has the link, without signing in. That covers Library items, pages and read-only chat links. A public chat link shows the chat as its starter saw it, and lists attachments by name without serving them. A chat that holds your personal device data can't be made public. For Library items and chats, making something public again gives a new link, and the old one stops working. Public pages and Library items let anyone report them. After reports from three different people, the item is hidden until the server's instance owner looks at it. See [Sharing](/guide/sharing) and the [Library](/guide/library). ## What models never see - **Secrets.** Bots refer to secrets with placeholders such as `{{secret:NAME}}`. Casama fills in the real value only when a request goes to a host the secret allows, after the model has written the call. Two-step seeds only ever produce codes. Known secret values are replaced with `[secret:NAME]` before anything reaches the model, the run timeline or logs. - **Model keys and connection tokens.** These stay in the server's vault and are used by the server, not the bot. See [Autonomy, approvals and action rules](/guide/autonomy#untrusted-content) for how Casama handles untrusted content. ## Run tracing Each run gets a trace id, shown on the run timeline with **Copy**. If the server runs an OpenTelemetry collector, each run, model step and tool call becomes a span with the model, token counts, cost, tool name, risk and outcome. Spans never carry prompts, messages, arguments or results. A self-hosted server can also send model calls to Langfuse for debugging. Those include model input and output, with secrets and model keys removed. Workspaces can opt out with the `llm_tracing` workspace setting through the [API](/develop/api). ## Telemetry and usage analytics - **Usage ping:** off by default. A self-hosted server sends nothing unless its owner sets `TELEMETRY=on`. Then, once a week, it sends a random instance id, the Casama version, and the number of bots and users active in the last 7 days. Nothing else. The admin console shows whether it's on. - **Product analytics:** On Casama Cloud, the official app and server capture usage metrics (screen views, milestone completions, daily activity rollups) to PostHog to improve the app. You can opt out at any time in **Settings → Privacy → Share Usage Data**. On self-hosted servers, product analytics is completely disabled unless the server owner explicitly sets `PRODUCT_ANALYTICS=on` and supplies a `POSTHOG_API_KEY`. - **Who is counted:** a person is identified only by their account id, only on Casama Cloud, and only while their switch is on. Workspace admins can also turn usage data off for a whole workspace in **Settings → Privacy → Usage Data for This Workspace**. Automated work (routines, watchers, chat apps) is counted per workspace, never as a person being active. Deleting your account also deletes your analytics. - **On someone else's server:** the official app connected to a self-hosted server sends crash reports and one anonymous "the app was used today" ping a day. No screens, no events, no account id. - **Error reports:** Sent to Sentry/PostHog when configured. When on, reports never carry message text, prompts, secrets, personal device data, or email addresses. ## Limits - The app has no screen to change member roles, so making someone else an owner before deleting your account isn't possible in the app yet. - A deletion can't be undone from the app once requested. - The `llm_tracing` opt-out has no switch in the app. ## Questions about your data Email [privacy@casama.ai](mailto:privacy@casama.ai) for privacy questions or requests about data held by Casama Cloud. On a self-hosted server, ask whoever runs it. ## Related - [Workspaces and teams](/guide/workspaces) - [Autonomy, approvals and action rules](/guide/autonomy) - [Memory](/guide/memory) - [Self-hosting configuration](/self-hosting/configuration) - [Operations](/self-hosting/operations) # Projects and the ticket board **Tasks** is a shared ticket board for people and bots. Assign a ticket to a bot and it starts working, reports back in comments and moves the ticket along. A **project** keeps one larger piece of work together: its chat, its plan and to-dos, its files, and everything a bot made for it. Use tickets for single pieces of work. Use a project for work that takes several files or several sittings, such as a game, a site or a set of reports. ## The ticket board Open **Tasks** in the main navigation. On tablets and computers it has one column per status; on phones, tickets are a list grouped by status: | Column | Meaning | | --- | --- | | **To do** | Not started. | | **In progress** | Someone, or a bot, is working on it. | | **In review** | A bot finished and a person should check the result. | | **Blocked** | Stuck. A failed bot run lands here with a comment saying why. | | **Done** | Finished. | Filter the board with **All**, **Mine** or **Bots**, by **Priority**, and by project with the project picker (**All projects** or one project). To change a ticket's status, long-press it and drag it to another column; on a phone, long-press it and pick where to move it. ## Create a ticket 1. In **Tasks**, tap **New ticket**. 2. Enter a **Title** and **Details**. 3. Pick a **Priority**: **Urgent**, **High**, **Medium**, **Low** or **No priority**. 4. Under **Assigned to**, pick a bot, or leave it **Unassigned**. 5. Turn on **Needs review** if a person should check the bot's work before it counts as done. 6. Tap **New ticket**. Bots can create, update, comment on and list tickets too, so you can also ask a bot to "plan this work on the board". ## When a bot works a ticket Assigning a bot, when you create a ticket, reassign it, or when another bot assigns it, starts a run in the ticket's own thread with the bot: 1. The ticket moves to **In progress**. 2. The bot works on it and reports in the ticket's comments. 3. When the run ends, a ticket that's still open moves to **In review** if it needs review, otherwise to **Done**. The bot's reply is added as a comment. 4. If the run fails, the ticket moves to **Blocked**, the bot comments why, and the ticket's owner gets a notification. Commenting on a bot's ticket wakes the bot, so you can answer its questions or ask for changes right there. Moving tickets between columns by hand never wakes a bot. ## The ticket sheet Tap a ticket to open it. From the sheet you can: - change its **Status**, **Priority** and **Assigned to** bot, - assign it to yourself with **Me**, - turn **Needs review** on or off, - read and add **Comments**, - **Open the bot's thread** to see the full conversation, - **Delete ticket**. ## Projects A project needs only a name and a bot. It holds: | Part | Where you see it | | --- | --- | | **Project chat** | A topic with the bot. What the bot makes there belongs to the project. | | **Made in this project** | The sites, games, pictures, videos, documents and files the bot made for it. They are also in the [Library](/guide/library). | | **Plan** | The bot's notes on what is done and what is next. | | **To-dos** | Tickets on the board that belong to the project. | | **Files** | One folder on the bot's computer for working files such as code. | You can work on a project in two ways: - **Together, in its chat.** This is how every new project starts. Nothing happens unless you ask. - **By itself.** The bot drafts a plan for you to approve, then works in sessions until the goal is met. See [Let the bot work on it by itself](#let-the-bot-work-on-it-by-itself). ### Start a project There are three ways: - **From a topic.** In a topic, open the chat's **…** menu and tap **Make This a Project**. The topic becomes the project's chat, and what the bot already made there is filed under the project. General can't become a project. - **From the list.** In **Tasks**, open the project picker and tap **Manage projects**, then **New project**. Enter a **Name**, pick the **Lead bot** and tap **Create Project**. The project gets a new topic as its chat. - **By asking the bot.** Ask for one ("start a project for this"), or let the bot start one when the work clearly takes several files. In a topic, the topic becomes the project's chat. In General, only what the bot makes in that reply is filed under the project. ### Find a project - **Library** has a **Projects** row at the top, one card per project. Tap a card to open the project, or **See All** for the list. - A topic that is a project's chat shows a **Project** chip at the top, and **Open Project** in its **…** menu. - Something in the Library shows the project it belongs to. Tap it to open the project. A project isn't a folder: what belongs to it still shows in the Library's main grid. To see only one project's things, open the project and tap **See All** next to **Made in this project**. ### Move something into or out of a project Things file themselves: whatever a bot makes in a project's chat, or while working on a project, belongs to it. To change that by hand, open the thing in the **Library**, open its **…** menu and tap **Move to Project**. Pick a project, or **No Project** to take it out. ### Files and code The bot keeps a project's working files in one folder on its computer. **Files** on the project screen opens that folder. It is empty until the bot saves something there. Code and other working files stay on the computer. They reach the Library when the bot links one in a reply, or keeps the folder as one zip labelled **Source** (ask it to if it hasn't). Keeping it again makes a new version of the same item. The Library is kept by the server, so that copy survives a reset of the computer. See [Files from the bot's computer](/guide/library#files-from-the-bot-s-computer). ### Finish a project On a project you work on together, tap **Mark as Done**. Tap **Reopen** to pick it up again. ### Let the bot work on it by itself Turn on the switch **Let Ada work on it by itself** (it names your bot) on the project screen, or in the **New project** sheet. It asks for: 1. the **Goal**, 2. **Done when**: how you'll know the project is finished (optional), 3. a **Budget** in dollars (optional). Tap **Start Planning**. The bot drafts a plan in the project chat: milestones with tickets, who should do each one, which milestones need your sign-off, and a written plan. You get a notification when it's ready. Until you approve it, asking the bot to plan again replaces the proposed tickets. Nothing starts before you approve. Turn the switch off to go back to working on it together. Nothing more starts by itself; a session already running finishes. Turning it on again later carries on with the plan you approved. ### Approve and follow along The project screen shows: - the status (**Planning**, **Active**, **Paused**, **Blocked**, **Done** or **Cancelled**) and, when there is one, the reason, - **Approve the Plan**, while a plan is waiting for you, - **Pause** or **Resume**, - **Made in this project**, - the **Goal**, and spend against the **Budget**, - **Milestones**, with tickets done out of the total and **Sign Off** where one waits for you, - the **Plan**, the **Tickets** and a **Timeline** of every run, - **Files**, - **Project chat**, which opens the conversation with the lead bot. Tap **Approve the Plan** to make the project active. ### How a project runs by itself Once the plan is approved, Casama checks every active project that works by itself each minute. When nothing is already running for it, it does the next thing: 1. **Pause** if the project has reached its budget or passed its deadline. You get a note in the project chat and a notification. 2. **Close finished milestones.** A milestone that needs sign-off waits for you to tap **Sign Off**. 3. **Start a session** for up to 10 ready tickets in the current milestone, highest priority first. In a session, the lead bot works on tickets or hands them out to other bots, keeps statuses current and updates the plan. 4. **Wrap up.** When every ticket is done, one last session checks the done criteria and marks the project **Done**. If the criteria aren't met, the project goes **Blocked** for you to decide. The lead bot can also pause the project and ask you a question; you get a notification and the project shows **Blocked** until you answer in the project chat and tap **Resume**. Sessions are normal runs, so the usual step and time limits apply. Every run for the project counts toward its spend: sessions, ticket runs, work a bot delegates, and your own messages in the project chat. Progress is kept in the database, so a project picks up where it left off after a server restart. ## Who can do what - A project made from the list is seen by everyone in the workspace. - A project that grew out of your own chat (made from a topic, or started by a bot there) is seen by you and by people who can open that chat. - Tickets are on the shared board, so everyone in the workspace sees a project's to-dos. - The project's owner, workspace admins and people who manage the lead bot can approve the plan, sign off milestones, pause, resume, finish it and switch working by itself on or off. ## Limits - The app doesn't set a project's deadline, rename it or cancel it yet. All three are available through the [API](/develop/api) (`PATCH /v1/projects/{id}`), which also changes the budget and the plan. - A project has one lead bot, and its chat is with that bot. - Ticket labels and due dates exist in the API but aren't shown on the board. ## Related - [The Library](/guide/library) - [Routines](/guide/routines) - [Bots working together](/guide/bots-together) - [Usage and budgets](/guide/usage) - [Group chats](/guide/group-chats) - [API](/develop/api) # Routines A routine is work a bot does later on its own: once at a time you pick, on a repeating schedule, or when something happens, such as a webhook, a meeting, a message or an event on your phone. Use routines for reminders, daily reports, follow-ups and anything you'd otherwise have to ask for again and again. This page also covers watchers ("tell me when...") and check-ins (a morning brief and suggestions), which are built on the same machinery. ## Create a routine The quickest way is to ask the bot in chat: "Remind me in 20 minutes to call Ana" or "Every weekday at 9:00, summarize my inbox". The bot creates the routine itself, and creating or changing its own routines doesn't need your approval, unless the run has just read untrusted content such as a web page or an email. What the routine later does still goes through your usual [approvals](/guide/autonomy). To create one yourself: 1. Open the bot's chat, open the **More** menu and tap **Bot profile**, then **Routines**. 2. Tap **New routine**. 3. Enter a **Name** and **Instructions**: what the bot should do each time. Or tap one of the **Ideas** at the top (a weekly review, a morning plan, bill reminders…) to fill in the name, instructions and schedule, then change anything. Ideas come from the [open gallery](https://gallery.casama.ai/#routine). 4. Pick a trigger: **Once**, **Repeats**, **Meetings** or **Messages**, and fill in its options (below). **GitHub** and **Webhook** are under **Advanced**, with the cron expression and timezone. 5. Tap **Create**. ## Manage routines Each routine in the list shows its trigger, when it runs **Next** and when it ran **Last**. - Use the switch to turn a routine on or off. An off routine shows **Off**. - Open its **More** menu and tap **Run Now** to start it immediately. **View run** opens the run. - **Edit** in the same menu changes its name and instructions, its schedule and timezone (or, for a one-time routine, when it runs), and lists its recent runs with what each cost. - **When It Ends** sets or removes its end (below). - **Delete** stops it for good. Results it already posted stay in their conversation. You can also ask the bot to list, change or delete its routines. It can rename one, change its instructions, schedule, timezone or device event, pause or resume it, set or remove its end, and turn a one-time routine into a repeating one or back ("make that reminder daily", "stop the standup after Friday"). ## Ending a routine A repeating or event routine can end on its own. In **New routine** (or **When It Ends** on an existing one), set **Ends**: - **Never**: it keeps going until you turn it off. - **On a date**: pick the **Last day** and time. It doesn't run after that. - **After some runs**: it stops after that many runs. On an existing routine the count starts over from now. The card shows **Ends** with the date, or how many runs are left. Once it ends it switches itself off and shows **Off**. To start it again, give it a later end or remove the end. **Run Now** doesn't count as one of its runs. One-time routines don't need an end: they already stop after their run. ## One-time routines Choose **Once**, then tap **In 15 min**, **In 1 hour** or **Tomorrow 9:00**, or pick a date and time. The routine runs a single time and then switches itself off. When you ask a bot for a reminder in chat, it creates a one-time routine, not a repeating one. ## Repeating schedules Choose **Repeats**, then pick **Every day**, **Weekdays**, **Every week** or **Every hour**. For the daily, weekday and weekly choices, set the **Time** (and the **Day** for **Every week**). For anything else, open **Advanced** and write your own **Cron expression**. Cron uses five fields: minute, hour, day of month, month and weekday. For example, `30 17 * * 5` runs at 17:30 every Friday. A schedule the choices can't show reads as **Custom** with the schedule in words. The **Timezone** field, also under **Advanced**, takes an IANA name such as `America/Chicago`. The schedule follows that zone, including daylight saving changes, and the sheet shows **Times are in** with the zone. Check it before you tap **Create**: the app fills it in from your device when it can, and otherwise uses `America/Chicago`. ## Webhooks A webhook routine runs whenever another service posts to its URL. The run gets the request body, and the event name when the sender includes one. 1. Open **Advanced** and choose **Webhook** for any service, or **GitHub** for a GitHub repository webhook. 2. Tap **Create**. 3. Copy the **URL** and the **Signing secret**. The secret is shown only once. 4. Add the URL as a webhook in the other service, signed with the secret. Every request must be signed with HMAC-SHA256 of the raw body: GitHub sends `X-Hub-Signature-256`, and other services send `X-Casama-Signature: sha256=`. Unsigned or wrongly signed requests are ignored. Casama answers `202 Accepted` either way, so nobody can probe which routines exist. See [Webhooks](/develop/webhooks) for signing examples. ## Meeting triggers A meeting routine runs around events on a connected calendar, for example a prep note 15 minutes before every meeting with a customer. 1. Connect Google Calendar or Outlook first. See [Connections](/guide/connections). 2. In **New routine**, choose **Meetings** and pick the **Calendar**. 3. Pick when to run: **30 min**, **15 min** or **5 min** before, **At start**, or **15 min** after. 4. Optionally narrow it down: - **Only meetings with people outside my company**: at least one guest's email domain differs from yours. - **Only meetings with a video link**: a Meet, Zoom, Teams, Webex or Whereby link anywhere in the event. - **Only titles containing (optional)**. 5. Tap **Create**. Casama checks the calendar every 5 minutes, looking 36 hours ahead, and skips cancelled events. Each matching event starts one run, within a minute of its time. If the event moves before then, the run moves with it. The run gets the event's title, times, guests, link, location and description. ## Message triggers A message routine runs when an email or chat message to the bot matches your filters. Without a **From** filter it only hears people the bot already chats with. Set **From** (an address, a number, `*@company.com`, or `*` for anyone) to hear from someone else. For example, a vendor's invoice email can start a routine that files it. 1. Connect the app first under **Bot profile → Advanced → Chat apps**. See [Chat apps](/guide/chat-apps). 2. In **New routine**, choose **Messages**. 3. Set at least one filter: - **App**: one chat app, or **Any app**. - **From (address, number, or \*@company.com)**. - **Subject contains**. - **Message contains**. 4. Tap **Create**. A message that starts a routine isn't also answered as a normal chat message. The run treats the message as untrusted content, so instructions inside it can't take over the bot. ## Device triggers A device routine runs when something happens on your own phone or computer. Ask the bot to set one up, for example "When I leave work, text me the grocery list" or "When a PDF lands in Downloads, file it". Device routines only ever fire for the person who created them; a teammate's routine never sees your events. | Event | Fires when | Needs | | --- | --- | --- | | Wake | You wake up, from last night's sleep in your health data. Once a day. | Health data on your phone | | Arrive, leave | You arrive at or leave a named place, such as Home or Work. | Places on iOS or Android | | Leave now | It's time to leave for your next calendar event that has a location, based on live travel time plus a buffer (5 minutes by default). | Places, a connected calendar, and a Google Maps or Mapbox key | | Workout ended | A workout ended in the last 6 hours. | Health data on your phone | | Notification | A notification arrives from an app you picked. One-time codes are masked. | Android's notification access | | File added | A new file appears in a watched folder, optionally matching a pattern such as `*.pdf`. | Watched folders in the desktop app | Set up places, watched apps and watched folders in **Settings → Advanced → Device connections**. Casama keeps only place names and times, never a location trail. See [Devices](/guide/devices) for setup and privacy details. The routine starts as soon as the event reaches the server. A retried upload never starts it twice. ## Where results go A routine posts its results in a chat with you, so they read like the rest of your conversation: - A routine the bot created in chat posts back into that chat. - A routine made in **Routines** posts into your **General** chat with that bot (see [Chat](/guide/chat)). - Morning briefs always go to **General**. The start of each run shows as "Routine “Daily summary” ran" rather than as a message from you, and the open chat updates when the result arrives. You also get a notification with the result, linked to the chat. Casama's [attention rules](/guide/attention) decide when it reaches you, and the notification says which routine sent it. Routine runs are normal runs, with the usual step, time and budget limits. See [Usage and budgets](/guide/usage). ## Watchers A watcher keeps an eye on something and wakes the bot only when it changes. Ask the bot "tell me when..." and it creates one. | Kind | Watches | | --- | --- | | Page | The visible text of a web page, optionally from a given heading or phrase on. It can read signed-in pages in the bot's browser when the computer is awake. | | Reply | A new comment from a person on a [ticket](/guide/projects). | | Result | The result of a read-only tool from one of the bot's [connections](/guide/connections). | | Time | A moment in time. It fires once and finishes. | How watchers work: - Checks run every 15 minutes by default, and as often as every minute. - The first check only records the starting point. - Checks don't use the model, so an unchanged check costs nothing. When something changes, the bot gets a run with what changed, your condition and what to do, and decides whether it counts. - A watcher can expire after a set number of days. To manage them, open **Bot profile → Watchers**. Each shows **Watching**, **Paused**, **Done** or **Expired** and how many times it fired. Use **Pause**, **Resume** or **Delete**, or open it to see its conversation. Watchers fetch outside pages, so creating one follows the bot's normal approval rules. ## Check-ins Check-ins are how a bot reaches out first: a morning brief, and a look every few hours for things that need you, like a trip to plan or an email to answer. The personal bot Casama makes for you when you first sign in starts with them on. Other bots start with them off. 1. Open **Bot profile → Check-Ins**. 2. Turn them on and set **Morning brief at** (8:00 by default), **Look every** (1, 2, 3, 4, 6 or 12 hours; 3 by default) and **Daily limit** (default $1). 3. Tap **Save**. Briefs and suggestions go to the person who turned check-ins on, in their timezone. They're posted in your **General** chat with the bot. A brief covers today and what's ahead, and its first sentence is the notification you get. On a day with nothing to tell, it says so in the chat without a push. A bot has one morning brief: to change what it covers, ask the bot, and to change its time, use **Check-Ins**. Suggestions the brief makes are cards under it rather than pushes of their own. A suggestion is a card there: **Do it** opens a topic where the bot does it and reports back in General, **Not now** puts it away. Several at once come as one card with a **Do it** on each; tap a row to read it in full. Answered rows say what happened (*Started 12:50*, *Put away* or *Expired*), and a started one opens its topic. If the bot can't start yet, for example because the workspace reached its daily limit, the app says why and the suggestion stays, so you can try again later. The bot asks one thing at a time: while a card in General is still unanswered, new suggestions wait under **Needs you** instead of piling up in the chat. Suggestions are also collected under **Needs you** at the top of **Chats**: - **Suggestions**: things the bot thinks you should act on, each with the bot's own one-line take. Tap **Do it** to open a topic where the bot does it (its actions still go through approvals), or **Dismiss** and choose **Just this once** or **Don't suggest it again**. A suggestion also arrives as a push from the bot, in its own words, following your [attention rules](/guide/attention): low-urgency ones wait for your brief, and a suggestion tied to a time (leaving for the airport, booking a ride before a show) can wait until then. On iPhone and Android the push has **Do it** and **Not now** buttons. **Do it** opens the chat with the bot working on it in a topic; **Not now** clears the push and leaves the suggestion under **Needs you**. The bot also takes an extra look when there's something new to look at: - **After you connect an app**, a few minutes later. Several connections close together share one look. - **When something happens**: new mail from a person or a calendar change in the next 48 hours in Gmail, Google Calendar or Outlook connected through Composio (when the server has Composio's events set up), or a new event in the next 48 hours on a calendar your phone shares. These looks are at least 2 hours apart, at most 6 a day for each bot, wait for your quiet hours to end, and aren't on the Free plan. To save money, scheduled looks skip your [quiet hours](/guide/attention) (on from 22:00 to 07:00 unless you change them; the brief covers the night). If you haven't opened Casama for a week, the bot looks at most once a day, and after a month it stops until you're back. Check-ins use the bot's cheap model when it has one, and stop for the day once they reach the daily limit. Their cost comes out of your usage like any other run. A look that finds nothing writes nothing and sends nothing. If your phone shares health data, the brief can also run when you wake up, and the scheduled time becomes the fallback. On Casama Cloud, plans limit how many bots can check in and how often they look: | Plan | Bots with check-ins | Look at most every | Looks when something happens | | --- | --- | --- | --- | | **Free** | 1 | 12 hours | No | | **Plus** | 2 | 3 hours | Yes | | **Pro** | 5 | 1 hour | Yes | | **Max** | 20 | 1 hour | Yes | Going past a limit opens the paywall. After a downgrade, the oldest bots keep their check-ins. Self-hosted servers have no such limits. ## Limits - Device routines can only be created by asking a bot; **New routine** doesn't offer them. - Focus and Do Not Disturb events, and Android's first unlock as a wake-up signal, aren't collected yet. - Android hears notifications only while the Casama app's process is running. - Calendar changes are picked up by the 5-minute check; Casama doesn't receive change notifications from calendar providers yet. - Watchers can't watch email or chat replies yet; replies on tickets work. - In the app, **Edit** changes a routine's name, instructions and timing but not its trigger. To use a different trigger, make a new routine. ## Related - [Webhooks](/develop/webhooks) - [Chat apps](/guide/chat-apps) - [Devices](/guide/devices) - [Attention and notifications](/guide/attention) - [Projects and the ticket board](/guide/projects) # Templates, sharing and import You can pass a bot along in two ways: share a copy as a template that anyone can import into their own workspace, or give people in your workspace access to the bot itself. You can also bring a bot over from another agent app. | You want to | Use | | --- | --- | | Give someone a copy of a bot to set up as their own | [Share as template](#share-a-bot-as-a-template) | | Let teammates chat with, edit or manage one of your bots | [Sharing](#share-a-bot-with-people) | | Move an agent from OpenClaw or Hermes Agent | [Import an agent](#import-an-agent) | | Bring what ChatGPT or Claude knows about you | [Import memories](#import-memories-from-chatgpt-or-claude) | | Share a page, picture, document or file a bot made | [Share what bots make](#share-what-bots-make) | | Share a chat | [Share or export a chat](#share-or-export-a-chat) | ## Share a bot as a template A template is a copy of a bot's setup: its instructions, skills, routines and the services it uses. It never holds keys, secrets or sign-ins. 1. Open the bot's **Bot profile** → **Advanced** → **Share as Template**. 2. Optional: tick **Include Memories**. Leave it off unless you trust who you share with, since it carries what the bot has learned about you and your work. 3. Choose how to share it: - **Save as File** saves a `.casama-bot.json` file. - **Copy link** creates a link and copies it. Links work for 30 days. Anyone who can see the bot can save it as a file. Creating a link, and including memories, is for people who manage the bot. Every share is recorded in the audit log. What a template carries: | Included | Never included | | --- | --- | | Name, description and instructions | Model keys and the model choice | | Autonomy level | Secrets and passwords | | Its built-in mascot | Sign-ins to apps (OAuth tokens) | | The bot's own skills, with their files | Workspace skills | | Its repeating routines | One-time routines | | The apps and services it uses, by name only | | | Memories, only if you ticked **Include Memories** | | Templates use the open `casama.bot` format, which is also what the community template repository accepts. See [Bot templates](/develop/bot-templates) for the file format. ## Import a bot 1. Open the template: - **A file:** select **Add** (the **+** button) → **Import a bot**, then pick the file. - **A link:** open it. It works for anyone signed in to Casama, in any workspace. 2. Review **What Comes with It**: the instructions, skills, routines, the apps to **Connect after importing**, and how many memories it has. 3. Choose whether to **Schedule Its Routines** and **Keep its memories**. 4. On a self-hosted server, under **Model**, pick a **Model key** from your workspace and a **Model**. The key's default model is filled in. Casama Cloud picks the model for you and skips this step. 5. Select **Import a bot**. The new bot belongs to you, and its routines run in your timezone. Casama can't sign in to apps for you, so if the template uses any, you see which ones to connect in Integrations. Importing counts toward your workspace's bot limit. ## Share a bot with people By default, everyone in the workspace can chat with a bot. Make it private to choose exactly who can see it, or add people who should be able to change it. 1. Open the bot's **Bot profile** → **Sharing**. 2. Turn on **Private** to hide the bot from everyone except you and the people you list. 3. Under **People**, add workspace members. Each starts with **Can chat**. 4. Change each person's access, or remove them with **×**. 5. Select **Save**. | Access | What they can do | | --- | --- | | **Can chat** | See the bot and chat with it. | | **Can edit** | Also change its settings, memory, knowledge and other things a bot's managers can change. | | **Can manage** | Also change who has access. | The bot's creator and workspace admins can always change sharing. Only workspace members can be listed, and every change is recorded in the audit log. Access can also be given to a whole role (for example everyone who is an admin or higher) through the API; such entries show as **Everyone Who Is …**. From the CLI, `casama bot create --private` creates a bot that only you can see. ### A bot working for someone uses only their things When several people use one bot, it acts for whoever started the work, and uses only what that person may use: - Local tools (MCP servers) on someone's own computer are offered only in their runs. - A bot whose computer is someone's personal computer won't use it in other people's runs. - Personal password managers and ChatGPT plans work the same way. Knowledge belongs to the bot or the workspace, so everyone who can chat with the bot shares it. ## Import an agent Bring an agent over from OpenClaw or Hermes Agent: its persona, skills, schedules and memories. You review everything before the bot is created, and keys and settings files are never read. 1. Select **Add** (the **+** button) → **Import an Agent**. 2. In the desktop app, choose **Pick Its Folder**. Anywhere, you can choose **Upload a ZIP of its folder** (a ZIP of the whole home folder or of only its workspace folder both work). 3. Review what was found. Edit the **Name**, read the persona, and untick any skill, routine or memory you don't want. Files that weren't imported are listed with the reason. 4. On a self-hosted server, pick a **Model key** and **Model**. Then select **Import an Agent**. What becomes what: | From | OpenClaw | Hermes Agent | | --- | --- | --- | | Persona | `SOUL.md` and `AGENTS.md`; `IDENTITY.md` gives the name | `SOUL.md`, plus `AGENTS.md` or `.hermes.md` | | Facts | `MEMORY.md` | `memories/MEMORY.md` | | Preferences | `USER.md` | `memories/USER.md` | | Episodes | The newest 60 daily notes in `memory/` | | | Skills | `skills//SKILL.md` | `skills///SKILL.md` | | Routines | Scheduled jobs in `cron/jobs.json` | Scheduled jobs in `cron/jobs.json` | Along the way: - **Never read:** `.env`, `auth.json`, `credentials/`, `openclaw.json`, `config.yaml`, databases, sessions, logs and run history. - **Not made into routines, with a note:** paused, one-off, finished and unreadable jobs. Jobs run in your timezone. - **Fixed up:** invalid skill names are renamed, so `Weekly Report` becomes `weekly-report`. - **Other files** (such as `HEARTBEAT.md` or notes) can be copied to `~/imported/openclaw/` or `~/imported/hermes/` on the new bot's computer. Tick **Copy … other files** to do that. The import goes through the same review and limits as a template, so there's one way to create a bot from outside Casama. ## Import memories from ChatGPT or Claude 1. Open the bot's **Memory** screen and select the import button. 2. **Copy** the prompt into ChatGPT or Claude, then paste its answer under **Its answer** and select **Next**. 3. Untick anything that's wrong, then select **Save**. See [Memory and knowledge](/guide/memory). ## Share what bots make Pages, pictures, videos, sounds, documents and files a bot makes are kept in the [Library](/guide/library), and each one can be shared on its own. 1. Open the item in the Library. 2. Under **Who Can See It**, choose **Only me**, **Workspace** or **Anyone with the link**. **Anyone with the link** gives a public link that anyone can open without signing in. Making it public again gives a new link, and the old one stops working. A workspace can make at most 20 new public links a day, and every public item has a link for viewers to report it. See [Library](/guide/library) for details. ## Share or export a chat Through the [HTTP API](/develop/api), you can: - **Export a chat** as Markdown or JSON (`GET /v1/conversations/{id}/export`). The export has only what you can see in it. - **Share a read-only link** to a chat (`POST /v1/conversations/{id}/share` with `public: true`). The link shows the chat as its starter saw it, with attachments listed by name only. Sharing again gives a new link; `public: false` turns it off. Only the person who started the chat or the bot's managers can share it, and a chat that holds personal data from a device can't be made public. The app doesn't have buttons for these yet. ## Limits - A template holds at most 30 skills, 20 routines, 200 memories and 20,000 characters of instructions. Agent imports over these limits are trimmed, with a note. - Agent uploads can be up to 50 MB and 3,000 files. - Template share links can't be revoked from the app; they expire after 30 days. - The app shares a bot with individual members only. Role-wide access needs the API (`PUT /v1/bots/{id}/access`). - Newer OpenClaw versions keep scheduled jobs in a database, which isn't read, so those jobs don't come over. - Other files are kept for one day after an agent import. If the new bot has no computer yet, they can't be copied; give it a computer and import again. ## Related - [Bot templates](/develop/bot-templates) - [Bots and models](/guide/bots) - [Memory and knowledge](/guide/memory) - [Workspaces and teams](/guide/workspaces) # Skills A skill is a set of instructions a bot loads when a task calls for it, like your house style for reports or the steps for cleaning up a spreadsheet. Skills keep a bot's standing instructions short: the bot always knows which skills it has, and reads the full text only when it needs one. ## How skills work Every run, a bot sees the name and one-line description of each enabled skill it can use. When a task matches a description, the bot loads that skill's full instructions. The chat shows this as **Loaded skill …**. Any files that come with the skill are copied to `~/skills//` on the bot's computer, so its scripts can run there. A skill belongs either to the whole workspace, so every bot can use it, or to one bot. You can also make sure a bot uses a skill: type `/` in the message field and pick it. See [Chatting with a bot](/guide/chat). ## The skill format Casama uses the open Agent Skills layout, so skills written for other apps that read it work here too. A skill is a folder with a `SKILL.md` file and, optionally, other files: ```text weekly-report/ ├── SKILL.md ├── template.md └── scripts/ └── build.py ``` `SKILL.md` starts with front matter, then the instructions in Markdown: ```markdown --- name: weekly-report description: Turn the week's notes into a one-page report for the team. --- # Steps 1. Read the notes in ~/workspace/notes from the last 7 days. 2. Fill in template.md: wins, problems, next week. 3. Keep it under one page. ``` | Field or rule | Requirement | | --- | --- | | `name` | Lowercase letters, digits, `-` and `_`, starting with a letter or digit, up to 63 characters. | | `description` | One line. Bots read it to decide when the skill applies, so say when to use it. | | Extra files | Up to 60 files, 1 MB each and 5 MB in total. | | Scripts | Run only on a bot's computer, never on the server. | ## Create a skill 1. Go to **Settings** → **Skills** and select **New skill**. 2. Fill in **Name (lowercase, dashes)**, **One-line description** and **Instructions (Markdown)**. 3. Select **Save**. Skills made here belong to the whole workspace. Use the switch next to a skill to turn it off for every bot without deleting it. To change or remove a skill, select it, then **Save** or **Delete skill**. You can also teach a bot a skill by doing the task once while it watches. See [Teach by showing](/guide/teach). ## Install from the catalog Casama ships a catalog of ready-made skills in seven categories: Work (meeting notes, meeting prep, weekly report, email drafts, inbox triage, decision memos, a daily digest, feature specs, PDF, Word and PowerPoint), Writing (proofreading, tone rewrites, social posts, article outlines), Research (research briefs, comparisons, fact checks, document summaries, a second pass over claims, competitive briefs), Data (CSV cleanup with a cleaning script, spreadsheet formulas, charts, Excel, an HTML dashboard), Money (budget reviews, invoice checks), Build (code review, bug reports, SQL, web app checks, systematic debugging) and Life (trips, meals, gifts, workouts, teaching a topic). The catalog comes from the [open gallery](https://gallery.casama.ai/#skill), so new and improved skills arrive without an app update, and anyone can propose one by pull request. When the gallery can't be reached, the copy that ships with Casama is shown. 1. Go to **Settings** → **Skills** and select **Skill catalog**. The catalog opens as its own page. 2. Search, or filter by category. Select a skill to read its full instructions. 3. Select **Install**, then choose **The whole workspace** or one bot. With no bots yet, it installs for the whole workspace straight away. Installed skills show a check. Workspace owners and admins can install for the whole workspace. People who manage a bot can install for that bot. ## Import from GitHub 1. Go to **Settings** → **Skills** and select **Import from GitHub**. 2. Paste a link to a folder that contains a `SKILL.md`, then select **Preview**. 3. Review `SKILL.md` and every file in the folder. Binary files are marked as such. 4. Under **Install for**, choose **The whole workspace** or one bot, then select **Install**. Casama installs exactly the commit you previewed, so a change pushed after your review never sneaks in. The skill is labeled with its repository. Private repositories need a workspace secret named `GITHUB_TOKEN` that is allowed for `api.github.com`. See [Apps and connections](/guide/connections). ### Update a GitHub skill 1. In **Settings** → **Skills**, select **Check for updates** on the skill. 2. If there's a newer commit, review the line-by-line changes to `SKILL.md` and the files **Added**, **Changed** and **Removed**. 3. Select **Update**. Otherwise you see **Already up to date.** ## Skills bots write A bot can save a skill for itself, for example after you walk it through a task, and improve the skills it saved. Skills a bot saves belong to that bot and show **Saved by a bot**. - A bot can change only its own skills. Workspace skills are for admins to change. - Saving or changing a skill is a medium-risk action. When it needs your approval (see [Autonomy and approvals](/guide/autonomy)), the approval card shows the whole `SKILL.md` for a new skill, or a line-by-line diff for a change. ## Skill ideas from a bot's own work Bots also learn from how their runs go and suggest skills for you to approve. - **A new skill.** When a bot succeeds at a task using at least two tools and no skill, and it has done similar tasks successfully at least twice before, it writes up a skill from up to four of those runs: a name, a description, the steps and the tools it used. It suggests each idea once. - **A better skill.** When a run that used a skill fails, or you correct the bot in your next message ("no…", "actually…", "that's wrong"), the bot rewrites the skill and says what changed. To review ideas: 1. You get a notification. Tap **Needs you** at the top of **Chats**. Ideas show as cards, for example "Ada suggests a skill: weekly-report" or "Ada suggests improving weekly-report". 2. Read the steps, the tools it **Uses**, or the line-by-line change. 3. Select **Save skill** or **Apply change**, or **Dismiss**. Ideas wait for the bot's owner. To apply them without asking, add an action rule that allows the bot's `skills.create` or `skills.update`. See [Autonomy and approvals](/guide/autonomy). Plugin skills are never changed this way. ## See how a skill is doing In **Settings** → **Skills**, select **How it's doing** on a skill to see how many times it was used, how often it went well, failures, corrections, the last problem, and **Earlier versions**. Every change to a skill, by a person or a bot, keeps the old text. ## Skills as files Every skill (and routine) can be exported as Markdown files, edited anywhere and imported back, or kept in sync with a GitHub repository. See [Workspace files](/develop/workspace-files). ## Limits - Skill ideas appear under **Needs you** and as a notification, not as a card in the chat. - Learning counts only runs since the feature arrived on your server; older history doesn't count. - Runs in group chats don't lead to skill ideas. - Without embeddings (an OpenAI API key, or the server's shared OpenRouter key), similar runs are matched by shared words only. - Skills from plugins are managed with the plugin. See [Plugins](/develop/plugins). ## Related - [Chatting with a bot](/guide/chat) - [Teach by showing](/guide/teach) - [Workspace files](/develop/workspace-files) - [Plugins](/develop/plugins) - [Autonomy and approvals](/guide/autonomy) # Teach by showing Instead of writing instructions, you can show a bot how to do a task. Do it yourself once on the bot's desktop computer while Casama records each step, and the bot turns the recording into a [skill](/guide/skills) it can reuse. You can also save the steps as a replay that runs without the model, which is faster and cheaper for tasks that don't change. ## Before you start - The bot needs a desktop [computer](/guide/computers). On a headless computer, use **Switch to Desktop** first. - Teaching happens in the live view, and only while you're in control. ## Teach a task 1. Open the bot's computer and tap **Open Live View**. 2. Tap **Take Control**. 3. Open **More** (**⋯**) and tap **Teach a task**. On a team computer, pick **Which bot should learn this?** 4. A red **Recording** banner appears. Do the task as you normally would. The banner shows the last step it saved. 5. If you type something sensitive that isn't in a password field, tap **Mark as Secret** right after typing it, give it a **Name** such as `EMPLOYEE_ID`, and tap **Save**. 6. Tap **Stop** when you're done. The bot then writes a draft skill from your recording in a new chat called "Teach: draft a skill", and the app opens the **New skill** screen while it works ("Writing a skill from your recording…"). ## Review and save the skill The **New skill** screen shows the bot's draft: - **Name (lowercase, dashes)** and **One-line description**, - **Instructions**, including an Inputs section and a Success checks section, - **What you showed**: the recorded steps, with secrets shown by name only. Check the steps, inputs and success checks, then choose: | Button | What it does | | --- | --- | | **Save** | Adds the skill to the bot. | | **Save and Try** | Adds the skill and opens a chat asking the bot to use it now. | | **Also Save as a Replay** | Saves the recording as a replay too (see below). | | **Discard** | Deletes the recording: every step, snapshot and screenshot it captured. | If the bot couldn't write a draft, the screen says so. You can still write the skill yourself from the recorded steps, or discard it. ## What gets recorded | You do | Recorded as | | --- | --- | | Click | One step, at that position. | | Type | One step, until you click, press a special key or pause for 1.5 seconds. | | Scroll | Grouped into one step, the same way as typing. | | Special keys and shortcuts | Their own step, such as `Tab` or `Ctrl+c`. | After each step, Casama captures what the screen looks like: the accessibility snapshot of the desktop (or the bot's browser), the browser's address and a screenshot. Anything it can't capture is skipped. ## Privacy and secrets Live view normally keeps everything you do away from the bot. Teaching is the one exception, and Casama makes it obvious: - Recording runs only while you hold control, and each step checks that again. If you lose control, recording stops. - The red **Recording** banner with **Stop** stays on screen the whole time. - Text typed into a password field is never stored. The step becomes a named placeholder such as `{{secret:PASSWORD}}`, and the bot asks for the value when it uses the skill. - **Mark as Secret** deletes the text you last typed from the recording and turns it into a named secret input. You can only mark secrets before **Stop**, because **Stop** sends the recording to the model. - Only you can see your recordings. Starting a recording is written to the workspace's audit log. - One recording at a time per computer. The bot gets the recording as text: steps grouped by page address, each with the start of the screen snapshot after it. Screenshots are kept for you but aren't sent to the model. ## Replays A replay is a recorded set of browser or desktop steps that the bot runs as is, without calling the model. It's faster and cheaper than having the bot work the task out each time. If a step doesn't work any more, the bot takes over from that step and can update the replay. Each step can carry: - **Parameters** for values that change between runs, with defaults. - **Secrets** as `{{secret:NAME}}` placeholders, each limited to the site it belongs to. - **Targets** found by an element's role and label rather than by position, so the step still works when the page reloads. - **Checks**, such as "the address contains..." or "the screen shows...". ### Save a replay - **From a teach recording:** tap **Also Save as a Replay** on the **New skill** screen. Clicks become clicks at the recorded position, typed text becomes a parameter with what you typed as its default (secrets stay placeholders), and each page address becomes a check. - **From a chat:** after the bot does a browser or desktop task, ask it to save the steps it took as a replay. It saves the steps with targets, checks and parameters, and refuses to store plain text typed into password fields. ### Run a replay 1. Open the bot's **Bot profile → Advanced → Replays**. 2. Tap **Run** on the replay. 3. Check the values it fills in, then run it. The run's chat opens. The bot can also run a replay itself during a chat. Each replay shows how many steps it has, how many times it's run and how many runs needed help. ### When a step fails A missing element, a failed check or a tool error stops the replay at that step. The bot gets where and why it stopped, plus what was already done, and carries on from there with the model. It can then offer to update the replay. A replay run still passes through your approval rules as usual. To delete a replay, use **Delete** in **Bot profile → Advanced → Replays**. ## Limits - Teaching needs a desktop computer and the live view. - Clicks recorded from a teach recording are screen positions, not elements, so they're usually the first thing to need the bot's help when a screen changes. Replays the bot saves from a chat use elements instead. - Screenshots from a recording aren't sent to the model yet. - Password manager items in replays aren't supported yet. ## Related - [Skills](/guide/skills) - [Computers](/guide/computers) - [Autonomy and approvals](/guide/autonomy) - [Routines](/guide/routines) # Usage, budgets and plans Casama tracks what every bot spends on models, cloud computers and other metered services. Use this page to see where the money goes, cap what a bot can spend, and understand Casama Cloud plans and credits. If you self-host, there are no plans or paywalls: you pay your providers directly and set your own limits. ## See usage and cost 1. Open **Settings**. The **Usage** row shows this month's model spend. 2. Tap **Usage**. 3. Pick a period: **Today**, **This week**, **This month** or **This year**. On Casama Cloud, a credits meter sits at the top (see [Credits](#credits)). The screen shows: | Section | What it shows | | --- | --- | | **Spend**, **Runs** | Totals for the period, in dollars | | **Spend by Day** | Spend per day (per month when you pick **This year**) | | **By Bot** | Spend per bot. **Not tied to a bot** covers usage without one. | | **By Model** | Spend per model. **Computers and other** covers non-model usage. | | **Everything Metered** | Each metered kind, such as **AI models** (input and output together), **Cloud computer time**, **Live view** and **Read aloud** | To keep a copy, tap **Export CSV**. Token counts and **Export JSON** are under **Advanced**. ::: tip Costs are estimates from token counts and published prices. Your model provider's bill is the final word. ::: From the CLI: ```sh casama usage --period day # or month (the default) ``` It prints the total and each bot's cost and tokens. For machine-readable output, put `--json` before the command: `casama --json usage`. ## See what each reply cost To see what each answer costs while you chat, turn on **Settings > Show usage on replies**. It's off by default and saved on each device. With it on, a small line sits under the last message of every reply, for example `$0.0420 · 18.2K tokens · 32s`. While the bot is working, the line counts up. It includes any helper runs the bot started for that reply. Tap the line to see: - what came out of your credits, and what your own keys or ChatGPT plan spent; - tokens, how long the reply took, and how many steps the bot took; - each metered item, such as model input and output for each model, cloud computer time and web searches. **Open the run** from that sheet shows the reply's full timeline. Anyone who can see the chat can see its costs. The same numbers come from `GET /v1/runs/{id}/usage`. ## Ask a bot about your usage 1. On the **Usage** screen, tap **Ask a Bot About This**. 2. Under **Which bot should look at this?**, pick a bot. Casama starts a new chat with that bot and sends a summary of the period. The bot can also check live numbers itself: every bot has a read-only usage tool that reports the workspace's spend for a day, week, month or year, by bot, model, day and metered kind. You can ask any bot "what did we spend this week?" at any time. ## Bot budgets Every bot has two spending limits: | Limit | Default | What happens when it's reached | | --- | --- | --- | | Per run | $1 | The run stops with "This run reached its budget" | | Per day | $10 | The bot's runs stop, and new ones are refused until the next day (midnight UTC) | Set them when you create a bot with the CLI: ```sh casama bot create "Ada" --credential --run-budget 2 --daily-budget 20 ``` Or pass `budget` (`per_run_usd`, `daily_usd`) when creating a bot through the [API](/develop/api). A bot that manages other bots can set budgets for the bots it creates or edits, but never higher than its own. When a bot hands work to a subagent, the subagent gets 20% of what the parent run has left (at least one cent). ### Other limits on every run | Limit | Value | | --- | --- | | Steps per run | 40 | | Time per run | 30 minutes | | Repeated actions | See [the loop guard](/guide/autonomy#the-loop-guard) | Projects have their own budget and deadline. See [Projects](/guide/projects). ## Workspace quotas On a self-hosted server, the instance owner can cap each workspace in the admin console: 1. Open **Settings → Admin console → Workspaces**. 2. Find the workspace and tap **Edit quotas**. 3. Set **Max bots** and **Monthly spend limit (USD)**. Leave a field empty for no limit. 4. Tap **Save**. The monthly limit counts the workspace's spend since the start of the calendar month (UTC). See [Workspaces and teams](/guide/workspaces#the-admin-console). ## When a run hits a limit Limits are checked when a run starts and before every model step. A run that hits one ends as failed with a clear message and a stable code: | Code | Meaning | | --- | --- | | `budget_exceeded` | The run reached its per-run budget | | `daily_budget_exceeded` | The bot reached its daily budget | | `quota_exceeded` | The workspace reached its monthly spend limit | | `out_of_credits` | A Casama Cloud workspace has no credits left | | `cloud_daily_cap` | A Casama Cloud workspace reached its plan's [daily limit](#daily-limit). It resets at midnight UTC. | | `computer_hours_exceeded` | A Casama Cloud workspace used its computer hours for the month | | `plan_limit` | A Casama Cloud workspace is over a plan limit, such as how many bots or computers can run | | `max_steps_exceeded` | The run used all its steps | | `wall_time_exceeded` | The run ran out of time | | `stuck_looping` | The bot kept failing the same way and stopped | | `no_model_configured` | The bot has no model. Add a model key and pick a model in **Bot profile**. | ## Casama Cloud plans and credits On Casama Cloud, each workspace has a plan. Open **Settings → Billing** to see it. - **Your plan** shows the plan, how it's billed (**Billed on the web**, **Billed through the App Store** or **Billed through Google Play**), when it renews or ends, your **Credits** balance and the credits meter. - **Plans** lists what each plan includes: a number of bots, computer hours a month and credits a month. - **Credits** (paid plans only) lists the credit packs you can buy. - **Extra People** (Pro and Max, web subscriptions) sets how many people you pay for on top of the plan's own. - The usage row shows what bots used this month and what it cost. Each charge, with the server it came from, is under **Advanced**. Owners and admins can change plans and buy credits. Members see the plan and usage. ### Plans | Plan | Price | Credits a month | Bots | Computers (running at once) | Computer hours a month | People | Library storage | | --- | --- | --- | --- | --- | --- | --- | --- | | **Free** | $0 | $1 | 3 | 1 (1) | 5 | 1 | 1 GB | | **Plus** | $15 a month or $150 a year | $5 | 10 | 2 (1) | 30 | 1 | 10 GB | | **Pro** | $49 a month or $490 a year | $15 | Unlimited | 5 (2) | 100 | 3 | 50 GB | | **Max** | $99 a month or $899 a year | $30 | Unlimited | 10 (2) | 300 | 10 | 200 GB | Each plan also caps what its bots can spend on Casama's own model key in one day ($0.25 on Free, $5 on Plus, $10 on Pro and $25 on Max). Bigger plans also get bigger computers: 1 vCPU and 1 GB of memory on Free and Plus, 2 on Pro and 4 on Max. Plans can change, so **Billing** always shows the current ones. Library storage counts what bots keep in the [Library](/guide/library). With [Casama Link](/guide/casama-link), Free and Plus connect one self-hosted server, Pro three and Max ten, and live view away from home comes with Plus and up. **Running at once:** starting another computer puts one nobody has used for 2 minutes to sleep. If they're all in use, the start is refused until one is free. **Pro trial:** Pro is free for 7 days, once per person, if you've never had a subscription. During the trial the workspace gets $2 of credits and 10 computer hours; the first payment tops the month up to $15. A person is a member of the workspace. Free and Plus have one, the owner, so inviting someone needs Pro or Max. On the web, Pro and Max can add more people at $12 a month each ($120 a year). One person can own up to five workspaces on Casama Cloud. ### Credits Credits are dollars: 1 credit = $1. The credits meter at the top of **Usage** and on the **Billing** plan card shows your balance (for example **Credits: $7.80**), a bar of how much of this month's credits you've used, and roughly how many more runs that buys at your usual cost. The bar turns amber at 80% and red when nothing is left. Credits pay for everything Casama Cloud runs for you: AI models on Casama's key, cloud computer time, live view, live calls, images and video, read-aloud and dictation, and apps connected through Casama's own connector account. Usage is deducted from the balance every minute. Every run on Casama Cloud needs credits, because even a short run can use some of these. Credits belong to the workspace, not to a person, and they don't last forever: | Credits | Last until | | --- | --- | | A month's included credits | The end of the following month | | Credit packs and rewards | 12 months | Credits that run out soonest are spent first. Only your oldest Free workspace gets Free's monthly credits. A run that fails because of Casama or a model provider doesn't cost model credits: its model usage is waived, or refunded if it was already taken. Computer time is still charged, since the computer ran. Runs that stop at a limit, loop, or that you stop yourself are charged as usual. When a workspace's balance drops under $1 after recent use, its owners get a notification, at most once a week. ### Daily limit Each plan also has a daily limit on what Casama Cloud spends for you in a day: models on Casama's key, live calls, images, read-aloud and apps. Computer time doesn't count here; it has its own monthly hours. | Plan | Daily limit | | --- | --- | | Free | $0.25 | | Plus | $5 | | Pro | $10 | | Max | $25 | The limit stops runs on its own, even with credits left. Under the credits meter, **Today's limit** shows what's been spent today against it (for example **$0.10 of $0.25**) and when it resets. It turns red when the limit is reached. The day resets at midnight UTC. To go past it, upgrade, or add your own model key in **Settings → Model keys**. ### Paywalls When a workspace runs out of something its plan includes, the paywall opens on top of whatever you were doing, with the reason (for example "Your plan allows 3 bots. Upgrade to add more.") and the paid plans side by side. Close it to go back to where you were, such as a half-filled **New bot** sheet. Members are asked to get an owner or admin to upgrade. This happens when: - The credit balance is at or below zero. New runs are refused until you add credits or change plans. - The workspace used its computer hours for the month. - Creating another bot or computer, or adding another member, would go over the plan's limit. - A bot's work hits another plan limit, such as the daily limit on Casama's models. A paying workspace that runs out of credits gets a sheet of credit packs instead, with **See Plans** under it. On the Free plan, **Billing** also shows an **Upgrade to Pro** banner that opens the paywall. ### Where you can buy | Where you use the app | Subscriptions | Credit packs | | --- | --- | --- | | iPhone, iPad and the Mac App Store app | In-app purchase. In the US, a web checkout link too. | In-app purchase | | Android | Google Play | Google Play | | Web, Windows, Linux and the Mac app from the web | Web checkout | Web checkout | Credit packs come in $10 and $25 of credits, for workspaces on a paid plan. On the web they cost their face value. In the App Store and Google Play they cost a little more, because the stores keep a share. To manage or cancel a subscription, tap **Manage Subscription**. If you bought on a phone and reinstalled, tap **Restore Purchases**. Cancelling a store subscription keeps access until the end of the paid period; a refund ends it. ### Invite friends On Casama Cloud, everyone has a personal invite code and link under **Settings → Invite Friends**. When a friend signs up with your code and finishes their first chat, you each get $2 of free usage as credits. You can earn rewards for up to 20 friends. A friend who signed up without your link can still enter your code under **Got a Friend's Code?**, within a week of signing up. Self-hosted servers don't show invites. ## Self-hosting: no paywall Billing is off on a self-hosted server unless you turn it on. **Settings → Billing** is hidden, and the workspace has no plan limits. If you open the billing screen anyway, it says **Billing is off on this server. Self-hosted Casama has no limits.** Bot budgets and any quotas the instance owner sets still apply. ## Limits - The app doesn't edit bot budgets yet. Set them at creation with the CLI or API, or ask a bot that manages bots to lower them. Changing an existing bot's budget isn't available in the app or the CLI. - Owners and admins can get each member's share of the cost (`by_person`) from `GET /v1/usage`, but the app doesn't show it yet. - `casama usage` supports `day` and `month` only. Use the app for weeks and years. - Usage costs are estimates, not invoices. - Prices are in US dollars only. ## Related - [Casama Link](/guide/casama-link) - [Autonomy, approvals and action rules](/guide/autonomy) - [Projects](/guide/projects) - [Workspaces and teams](/guide/workspaces) - [Self-hosting configuration](/self-hosting/configuration) # Voice and calls Talk to your bots instead of typing. Dictate messages, have replies read aloud, call a bot live, and let a bot ring your phone when something needs you. Bots can also make spoken audio for you, such as a voiceover. On Casama Cloud, voice runs on Casama's own keys and is paid from your [credits](/guide/usage#credits), so there are no keys to add and no voice providers to pick. If you're out of credits, dictation uses your device's own speech recognition instead. The rest of this section is for self-hosted servers, where voice runs on your workspace's own provider keys (or keys the server's admin set up for everyone). ## Which keys you need Add keys in **Settings** → **Model keys** → **Add Key**. | Feature | Needs | | ---------------------------- | --------------------------------------------------------------------------------- | | Dictation | An OpenRouter key, or the server's shared one | | Read aloud | An OpenRouter key, or the server's shared one | | Spoken audio a bot makes | An OpenRouter key, or the server's shared one | | Live calls | A Google AI (Gemini) key, used only for calls. Included on Casama Cloud, and on servers whose admin set a server-wide key | | Bot rings your phone | A Google AI key for the call, plus push set up on the server for iOS and Android | | Wake word | No key: it runs on your device | Every minute, second or character of voice is recorded in [Usage](/guide/usage). On your own keys, the provider bills your own account. ## Dictate a message 1. In a chat, tap **Dictate** in the message box. Allow microphone access the first time. 2. Speak, then tap **Stop and transcribe**. 3. The text lands in the message box. Edit it if you like, then send. Dictation uses Whisper Large V3 Turbo on OpenRouter: the workspace's OpenRouter key, or the server's shared one when the workspace has none. If the dictation service fails or isn't available, the app falls back to your device's own speech recognition, where the device has one. ## Have a reply read aloud Open a bot message's actions and choose **Read aloud**. It uses Gemini 3.8 Flash-Lite TTS on OpenRouter, on the workspace's OpenRouter key or the server's shared one. Audio is saved per message and voice, so replaying it doesn't call the provider again. ## Choose a bot's voice Read aloud and calls always use Gemini voices, and dictation always uses Whisper, so there's no service to pick. 1. Open **Bot profile** → **Voice**. 2. Optionally enter a **Voice id**: one of Gemini's built-in voices, such as Kore or Puck. Leave it empty for Kore. 3. Tap **Save**. ## Bots that make spoken audio Ask a bot for a narration, a voiceover, a podcast intro or a message read in a voice, and it can make the audio itself. - It turns up to 4,000 characters into speech per clip, in a Gemini voice such as Kore, Puck or Charon. For longer pieces it makes several clips and joins them on its computer. - The audio plays under the bot's reply. It's saved on the bot's computer when it has one, and kept in the [Library](/guide/library). - Under the default autonomy, the bot asks you before it makes audio. - It uses the same speech service as read aloud (Gemini 3.8 Flash-Lite TTS on OpenRouter) and is counted the same way in [Usage](/guide/usage). On Casama Cloud it's paid from credits. Music and sound effects aren't supported. ## Call a bot live Live calls and phone calls use **Gemini Live**, on the workspace's Google AI key, or the server's own Google key when the workspace has none. The bot's voice is one of Gemini's built-in voices (Kore by default). 1. In a chat, tap **Start a voice call** (the phone icon in the header). 2. The bot picks up and speaks first, like someone answering the phone: it says hi, by your name when it knows it, and asks what it can do. Then talk. Use **Mute** and **Hang up** as on a phone call. On Casama Cloud, calls are included and paid from credits; a workspace with no credits left sees the paywall instead. On a self-hosted server with no live-call key, the call screen says so, with **Get a free key from Google** (Google AI Studio) and **Add a Google AI key** (opens **Model keys** with Google picked). Only owners and admins can add keys. ### The call screen The bot appears as its Casama cloud mascot, animated for the call. Bots without a mascot icon appear as the lavender Casama cloud. - While you talk, it listens: a soft smile, blinks, glances and a nod. - While it talks, its mouth moves, it bounces a little and its orb pulses. It grows slightly with its voice. - It fades when you mute, and turns grey if the call drops. - On phones, calls play through the speaker. Tap the audio button (**Speaker**) to switch to the earpiece (**Phone**). With Bluetooth or wired headphones connected, it lists them to pick from. - **Captions** shows the last few lines of the conversation under the orb. Turn them off for just the orb; the choice is remembered on the device. - With reduced motion turned on in your system settings, the mascot holds still. What to know: - Before it uses a tool, the bot says so ("Let me check that"), so the call doesn't go quiet. A tool that takes more than about 12 seconds hands its result to the chat, and the bot tells you. - Each tool shows as a card above the captions, in plain words with what it's about ("Searching the web", "best time to repot a fern"). It spins while it runs, shows a check when it's done and then folds away. Cards that take a while count the seconds. - When an action needs your OK, its card asks right there: tap **Allow** or **Not now** without leaving the call. The bot hears your answer and carries on. - The bot keeps its persona and a small set of tools suited to talking: memory, knowledge, web search, notes to you, routines, watchers, tickets, usage and your device data. Each tool call runs with the bot's normal approvals. If an action needs your approval, the bot tells you, and you approve it in the app. - For bigger jobs, anything that needs its computer, files, the browser or connected apps, the bot starts the task in the chat and tells you. It runs in the background with all the bot's tools, and the result appears in the conversation. - To let the bot use specific connected-app tools live, such as creating a GitHub issue while you talk, open the bot's settings → **Voice** → **Tools on calls** and tick them. Each tool you add goes with every call, so it adds a little to each call's cost; pick only the ones you'll use by voice. - A call with no speech from either side for 2 minutes ends by itself, so a forgotten call doesn't keep running. - On Gemini Live, **Usage** records what the call actually cost, from the token counts Gemini reports; other calls are estimated by the minute. - You can interrupt. When you start speaking, the bot stops talking and listens. - The call's transcript is saved to the conversation. - Screen tools, such as clicking around the bot's desktop, aren't offered during a call. ## Start a call with a wake word On desktop and Android, say a phrase to start a live call with a chosen bot. 1. Open **Settings** → **Wake word**. 2. Turn on **Listen for the wake word**. 3. Set the **Phrase**: two or three words, such as "hey casama". 4. Choose **Call this bot**. The first time, the app downloads an open-source on-device model, about 18 MB. Listening happens only on your device while Casama is open. Nothing is sent anywhere until the call starts. ## When a bot calls you A bot can ring you when something is worth interrupting you for and talking beats a message. Your device rings like a normal call, with the bot's name and the reason. | Device | How it rings | | ----------------- | ----------------------------------------------------------------- | | iPhone | The system call screen (CallKit), even when the app is closed | | Android | A full-screen calling screen, even when the app is closed | | Desktop and web | A ringing banner over every screen, with **Answer** and **Decline** | When you answer, the live call opens in the same conversation and the bot speaks first. The rules: - It rings for 45 seconds. If you don't answer, you get a notification with the reason. - Your quiet hours apply. During quiet hours nothing rings, and you get a notification with the reason when they end. See [Attention and notifications](/guide/attention). - Only one call rings for you at a time. - The bot can only call the person it's working for. ### Server setup for ringing phones If you self-host, phones need push credentials on the server: | Platform | Settings | | -------- | ------------------------------------------------------------------------------------------------ | | iOS | `APNS_KEY_P8` (the `.p8` key, inline or a file path), `APNS_KEY_ID`, `APNS_TEAM_ID`, `APNS_VOIP_TOPIC` | | Android | `FCM_SERVICE_ACCOUNT` (a Firebase service account, JSON text or a file path) | `APNS_VOIP_TOPIC` defaults to `ai.casama.app.voip`. Without these, desktop and web still ring through the banner while the app is open. See [Configuration](/self-hosting/configuration). ## Limits - Live calls run on Gemini Live only; other realtime voice providers aren't supported. - On Gemini Live, use headphones on desktop computers if the bot seems to hear itself: echo cancellation depends on the device. - The wake word isn't available on iOS or on the web, and on Android it listens only while the app is open. - Bots can't phone other numbers, such as a business, yet. - Provider connections follow each provider's public docs and have been tested against stand-ins, not yet against every live provider. ## Related - [Chat](/guide/chat) - [Attention and notifications](/guide/attention) - [Autonomy and approvals](/guide/autonomy) - [Usage and budgets](/guide/usage) - [Chat apps](/guide/chat-apps) # Workspaces and teams A workspace holds your bots, their computers, memory, connections, secrets, billing and the people you work with. Use separate workspaces to keep things apart, such as work and home, or one per team. Nothing is shared between workspaces. ## Create and switch workspaces Your first workspace is made for you the first time you sign in, named after you (for example "Ana's space"). If you later change your name under **Settings → About you**, a workspace that still has the name Casama gave it is renamed to match. A name you chose yourself is never changed. The workspace switcher sits at the top of the sidebar on large screens, the rail on medium ones, and the header on phones. A dot on it means another workspace has pending approvals or unread notifications. To create one: 1. Open the workspace switcher. 2. Tap **New workspace**. 3. Enter a **Workspace name**, pick an **Icon** and a **Color**, and confirm. You become the workspace's owner. To switch, open the switcher and pick a workspace. The app remembers your choice on each device. From the CLI: ```sh casama org create "Ada's team" casama org list casama org use # the default workspace for other commands ``` To rename a workspace or change its look, an owner or admin opens **Settings → Workspace settings**. ## Roles Every member has one role: **Owner**, **Admin** or **Member**. Each role can do everything the role below it can. | Role | What it can do | | --- | --- | | **Member** | Create bots and manage the ones they created; use team bots; answer approvals for bots they can use; see usage and the plan; manage their own quiet hours, two-step sign-in and data | | **Admin** | Invite people (by link, code or email) as members or admins; approve requests to join; open the workspace to their email domain; rename the workspace and change its look; manage every team bot; add workspace action rules; set run history retention; require two-step sign-in; manage workspace settings such as bots talking to each other, phone calls, where secrets and memory are kept, AI app connections and workspace files; buy plans and credits and create Casama Link keys on Casama Cloud | | **Owner** | Everything above, plus turn on encryption and set up payments | A workspace always has at least one owner. Only an owner can make someone else an owner, and there's no screen for that yet (see [Limits](#limits)). Private bots are visible only to the person who created them and the people they share them with. See [Sharing](/guide/sharing). ## Invite people Owners and admins invite people from **Settings → People**. The workspace switcher has a shortcut, **Invite people**. Members can open **People** too, to see who's in the workspace. ### The invite link Every workspace has one standing invite link. Anyone who opens it can join as a member. 1. Open **Settings → People**. 2. Under **Invite link**, tap **Copy link** or **Share**. To invite someone in the room, or to move from your computer to your phone, tap **QR code** and let them scan it. The link stays the same, so you can copy it again whenever you need it. To stop it working, tap **Reset link**. The old link stops at once and you get a new one; people already in stay in. Turn on **Ask me before people join** to make the link safe to post somewhere semi-public. People who use it then ask to join, and their request waits under **Waiting to join**, where an owner or admin taps **Approve** or **Decline**. Admins get a notification for each request. ### An invite code For reading out on a call or typing on another device, tap **Get a code**. You get a short code such as `7F3Q-9XWD`. It works for 48 hours and isn't fussy about how it's typed: lower case, spaces, or the letter O for a zero all work. Codes leave out letters that look alike. ### By email 1. Under **Invite by email**, paste one or more addresses, separated by commas or new lines. 2. Turn on **Invite as admins** if they should be admins. 3. Tap **Send invite** (or **Send 3 invites**). What happens next depends on whether the server can send email: - **With email set up**, each person gets an email with a link. It works for 7 days, only for the address it was sent to. - **Without email**, the app lists each person with their link. Copy it and send it to them yourself. Invites that haven't been accepted are listed under **Invites not accepted yet**. Open the menu next to one to **Send again** (a new link, valid 7 more days) or **Cancel invite**. From the CLI: ```sh casama org invite ada@example.com --role admin # the default workspace, or --org ``` ### Join by email domain If you signed in with a verified work email, turn on **Anyone with a verified @example.com email can join** under **Join by email domain**. People with a verified address at that domain then see the workspace without an invite: new people are offered it before their first workspace is made, and everyone else finds it under **Workspaces you can join** in the workspace switcher. Admins get a notification when someone joins this way. You can only open a workspace to your own domain, and never to shared ones such as gmail.com or outlook.com. ### Custom links Under **Custom links**, make a link with its own **Role** (**Member** or **Admin**), **Expires** (1, 7 or 30 days, or **Never**) and **Uses** (1, 5, 25 or **Unlimited**). Copy or share it right away: for security, a custom link isn't shown again. The list shows each link and code with its role, uses and whether it's **Revoked**; tap **Revoke** to stop one. ### Joining Open the link. Casama shows the workspace first: its name, who invited you, how many members it has and the role you'd get. Tap **Join** (or **Ask to join** when an admin approves new people). After joining, you land on a welcome page with the workspace's bots. - **Not signed in yet:** tap **Sign in to join**. Casama remembers the invite and shows it again after you sign in, even if the app restarted. - **Got a code or a link in a message:** open the workspace switcher, tap **Join with a link or code** and paste or type it. On phones you can also scan the QR code. On Android and desktop, a link you copied fills in by itself. - **The link is for another server:** the app offers to switch to it. The person who made the invite gets a notification when you join. **Opening links in the app.** When the app is installed, an invite link opens it directly once the server publishes the app's link files (see [Configuration](/self-hosting/configuration)). Otherwise the link opens a page in the browser with **Open in Casama**. On a self-hosted server without the web app, that page comes from the API. ## Require two-step sign-in for admins Owners and admins can require two-step sign-in for everyone with admin powers in the workspace. 1. Set up two-step sign-in for yourself first. See [Privacy and security](/guide/privacy#two-step-sign-in). 2. Open **Settings → Two-step sign-in**. 3. Under **Workspace**, turn on **Require two-step sign-in for owners and admins**. You can only turn it on from a session where you signed in with your code, so you can't lock yourself out. Once it's on: - Owners and admins who didn't sign in with a code keep member access only. Settings tells them to set up two-step sign-in or sign in again with their code. - Members aren't affected. ## Enterprise single sign-on (SAML) SAML single sign-on is an enterprise feature. It needs a Casama Enterprise license key (`CASAMA_LICENSE_KEY`) and, when self-hosting, `SUPABASE_SERVICE_ROLE_KEY` with SAML enabled in the auth service. Without a valid key, the enterprise endpoints answer `402 license_required`; the rest of Casama works as usual. Owners and admins set it up through the API: 1. Get a verification record for each email domain: `GET /v1/orgs/{id}/sso/verification?domain=example.com`. 2. Add the returned TXT record (`casama-verification=...`) to that domain's DNS. 3. Register your identity provider with its metadata URL (or XML) and your domains: ```http POST /v1/orgs/{id}/sso Content-Type: application/json { "metadata_url": "https://idp.example.com/metadata", "domains": ["example.com"] } ``` 4. People sign in by tapping **Continue with SSO** on the sign-in screen and entering their work email. Casama sends them to your identity provider. `GET /v1/orgs/{id}/sso` shows the setup and `DELETE` removes it. A domain can belong to only one workspace's SSO. With the same license, owners and admins can also download the workspace's audit log as CSV or JSON (`GET /v1/orgs/{id}/audit-log/export`, with optional `from`, `to` and `format=json`; the last 90 days by default). ## The admin console On a self-hosted server, the instance owner has an admin console for the whole server. The instance owner is anyone listed in `INSTANCE_ADMIN_EMAILS`, or the first person to sign up when it's unset. Open **Settings → Admin console**. It has these tabs: | Tab | What you can do | | --- | --- | | **Overview** | Totals such as bots, **Computers running** and **Personal computers online**; the Casama version and update notices | | **Users** | Every user, their workspaces and when they last signed in | | **Workspaces** | Each workspace's members and bots; **Edit quotas** (**Max bots**, **Monthly spend limit (USD)**); **Suspend** a workspace (its computers and bots stop, nothing is deleted) and **Lift suspension** | | **Services** | Which optional services are configured, and whether each is **OK**, **Down** or **Off**. **App settings** sets minimum app versions, a maintenance notice, announcements and feature switches for every app connected to this server, without an app release. | | **Pricing** | With billing on: each plan's name, price label, limits and store products, and the credit packs. Saving a plan applies to every workspace on it straight away. | | **Abuse** | Suspicious activity on the server | Update notices appear only when the server sets `UPDATE_CHECK_URL`; otherwise the server never checks for updates. ## Limit who can sign up On a self-hosted server you can close sign-ups or allow only certain people: - `DISABLE_SIGNUP=true` makes the server invite-only once the first accounts exist. - `SIGNUP_ALLOWED_EMAILS` allows only listed emails or domains (for example `ana@example.com,@example.com`). It applies to every sign-in method, including Google. It needs the sign-up hook to be set up; without it, sign-ups are refused rather than open to everyone. See [Configuration](/self-hosting/configuration). ## Limits - **People** lists members, but changing someone's role, removing a member or leaving a workspace isn't available in the app or the CLI yet. - Joining by email domain needs a verified email address, and accepts members only. - Wrong invites are limited to 10 tries in 10 minutes per person (or address, when signed out). - On Casama Cloud, the plan's seats cap how many people a workspace can have. Free and Plus have one seat, the owner; Pro and Max can buy more. See [Usage, budgets and plans](/guide/usage#plans). - On Casama Cloud, one person can own up to five workspaces. - Signing in with SSO doesn't add anyone to a workspace. Invite people as usual. - SSO setup and audit log export have no screens in the app; use the API. ## Related - [Privacy and security](/guide/privacy) - [Sharing](/guide/sharing) - [Usage, budgets and plans](/guide/usage) - [Self-hosting configuration](/self-hosting/configuration) - [API](/develop/api) --- layout: home title: Casama titleTemplate: AI teammates with their own computers hero: name: Casama text: AI teammates with their own computers tagline: Bots that remember, work on real computers, ask before risky steps, and run on your own server with any model. actions: - theme: brand text: Quick start link: /quick-start - theme: alt text: What is Casama? link: /introduction - theme: alt text: Self-host link: /self-hosting/ features: - title: Bots that reach out first details: Each bot has instructions, memory, skills and a budget. It sends a morning brief, spots things it could do for you, and keeps working on schedules and triggers while you're away. link: /guide/bots linkText: Bots and models - title: A real computer each details: A sandboxed Linux computer with a shell, files and a browser. Watch it live, take control at any time, or lend a bot your own machine. link: /guide/computers linkText: Computers - title: Everything it makes, kept details: Sites, games, reports, documents, pictures, videos and sounds land in the Library, grouped by project and shareable with a link. link: /guide/library linkText: The Library - title: You stay in charge details: Autonomy levels, approvals for risky actions, action rules, checkpoints before destructive commands and a full timeline of every run. link: /guide/autonomy linkText: Autonomy and approvals - title: Where you already work details: Apps for every platform, Slack, Microsoft Teams, Discord, Telegram, WhatsApp, email and more, Linear and Jira issues, voice calls, and your AI coding tools. link: /guide/chat-apps linkText: Chat apps - title: Works with your tools details: One-click app connections, MCP servers, plugins and password managers, with secrets kept out of the model's sight. Plus an API, CLI and SDK to build on. link: /guide/connections linkText: Apps and connections - title: Any model details: Bring your own key for OpenAI, Anthropic, Google, xAI, OpenRouter or any OpenAI-compatible endpoint, run local models for free, or sign in with a ChatGPT plan on your own server. link: /guide/bots linkText: Choose a model - title: Yours to run details: Apache-2.0, one install script, and no paywall when you self-host. Casama Link puts a server on your own computer on your phone, with no domain and no open ports. link: /self-hosting/ linkText: Self-hosting - title: Or let us run it details: Casama Cloud is the hosted service, with a free plan and paid plans from $15 a month. Casama picks the models, so there are no keys to add, and models, computers and voice are paid from credits. link: /guide/usage linkText: Plans and usage --- # What is Casama Casama gives you AI teammates, called bots, that keep working after you close the chat. Each bot has its own instructions, memory, skills and a sandboxed Linux computer. It can research, write, code, browse and run tasks on a schedule, and it asks before doing anything risky. You run Casama on your own server with your own model keys, and reach your bots from apps on every platform, the terminal, chat apps or your AI coding tools. This page explains the main ideas. To try it, go to the [Quick start](/quick-start). ## The main ideas ### Workspaces A **workspace** holds your bots, chats, connections and model keys. You can belong to several, such as a personal one and one for your team. Everyone in a workspace has a role (owner, admin or member) that decides what they can change. See [Workspaces and teams](/guide/workspaces). ### Bots A **bot** is a teammate with: - **Instructions**: who it is and how it works, written by you, started from a persona, or proposed by the bot itself in a short setup interview. - **A model**: any model you have a key for (including a local model or a ChatGPT plan), with fallbacks if one is unavailable. On Casama Cloud, Casama picks the model. - **Memory**: facts and preferences it saves as it works and recalls in later chats. - **Skills**: reusable instructions for tasks it does often, loaded when they're relevant. - **A computer**: its own sandboxed machine for files, code and the web. - **Limits**: an autonomy level, budgets and the tools it may use. See [Bots and models](/guide/bots). ### Chats and runs You talk to a bot in a **chat**. Each bot has one main conversation with you, called **General**, where quick questions, morning briefs, routine results and its suggestions land. Bigger pieces of work get their own **topics**, which post a one-line result back to General when they finish. See [Chatting with a bot](/guide/chat). Each time a bot works on something, from a message, a schedule or a webhook, it starts a **run**. A run is a sequence of steps: the model thinks, calls tools, reads the results and replies. Every step is recorded in the run's timeline, so you can see what the bot did, what it cost and why. Runs survive restarts: if the server stops mid-run, the run continues from its last finished step. ### Tools and risk Bots act through **tools**: shell commands, files, the browser, memory, app connections, MCP servers and more. Every tool has a risk level (low, medium or high). The bot's **autonomy** setting decides which actions it does on its own and which wait for your **approval**. Approvals reach you in the app, with a push notification, and in Slack as buttons in the thread. See [Autonomy and approvals](/guide/autonomy). ### Computers Each bot works on a **computer**: an isolated Linux machine with a shell, files and a browser, and optionally a full desktop. Computers sleep when idle and wake with everything intact. You can watch one live, take control, and restore a checkpoint taken before a destructive command. You can also lend your own machine through the desktop app. See [Computers](/guide/computers). ### Routines and check-ins A **routine** starts a run without you: on a schedule, when a webhook arrives, before or after a meeting, when a message comes in, or when your phone says you've arrived somewhere. A routine can stop on a date or after a number of runs. **Check-ins** let a bot reach out first. It sends a morning brief, looks through your connected mail and calendar during the day, and offers what it could do as suggestions with **Do It** and **Not Now** buttons. Your first bot has them on, and non-urgent notifications wait out quiet hours (22:00 to 07:00 by default). See [Routines and triggers](/guide/routines) and [Notifications and attention](/guide/attention). ### The Library and projects Everything a bot hands you, such as sites and games, reports, documents, pictures, videos and sounds, is kept in the **Library**, with versions, search and share links. A **project** keeps one piece of work together: its chat, plan, to-dos and what was made for it. See [The Library](/guide/library) and [Projects and tickets](/guide/projects). ### Connections **Connections** let a bot use your other tools: built-in apps such as GitHub, Notion, Slack and Google, meeting notes apps, any MCP server, plugins, chat apps, password managers and your devices. Secrets are stored in a vault and are never shown to the model. See [Apps and connections](/guide/connections). ## Ways to run Casama | Option | What it is | | --- | --- | | **Self-hosted** | The whole stack on your own server with one install script. No paywall and no limits. See [Self-hosting](/self-hosting/). | | **Casama Cloud** | The hosted service at [casama.ai](https://casama.ai). A free plan, then Plus ($15 a month), Pro ($49) and Max ($99), paid from credits. Optional. See [Usage, budgets and plans](/guide/usage). | | **Casama Link** | Links a self-hosted server to a Casama Cloud account. Free: an address like `https://k7qm2xfd9abc.casama.link` that your phone can reach with no domain or open ports, sign-in by scanning a QR code, and notifications in the store apps. Billed: Casama Cloud's computers and model credits for your server. See [Use your server on your phone](/self-hosting/remote-access) and [Casama Link](/guide/casama-link). | ## Where you use it - **Apps** for iOS, Android, macOS, Windows, Linux and the web. - The **`casama` CLI** for the terminal and scripts. See [CLI](/develop/cli). - **Chat apps**: Slack, Microsoft Teams, Discord, Telegram, WhatsApp, Messenger, Feishu, iMessage, email and SMS. Assign a bot a Linear or Jira issue and it works on it. See [Chat apps](/guide/chat-apps). - **Voice**: live calls in the app, and phone calls. See [Voice and calls](/guide/voice). - **AI apps and coding tools** over MCP. See [Connect AI apps](/guide/mcp). - The **HTTP API** and the **Dart SDK** for your own software. See [HTTP API](/develop/api). ## How it fits together ```text Apps, CLI, chat apps, MCP clients │ ▼ API server ──── enqueues runs ────▶ Worker (runs the agent loop) │ │ ▼ ▼ Postgres (row-level security on Sandbox supervisor ──▶ Bot computers every table) + Auth + Realtime (via egress proxy) ``` - The **API** handles requests, checks who you are, and queues work. - The **worker** runs bots: it calls models, runs tools and records every step. Runs are durable, so a crash resumes at the last finished step. - **Postgres** stores everything, with row-level security on every table, so one workspace can never read another's data. Live updates reach the apps through Realtime. - The **sandbox supervisor** starts and stops computers. It's the only part with access to Docker (or another computer provider). Computers reach the internet only through an egress proxy that blocks private and cloud-metadata addresses. For the full picture, see [How Casama is built](/develop/architecture). ## Open source Casama is licensed under Apache-2.0, except the `ee/` folder (enterprise features such as SAML single sign-on and audit-log export), which is source-available under the Casama Enterprise License and needs a license key in production. A self-hosted server sends no telemetry unless you turn it on. The code is on [GitHub](https://github.com/stackwares/casama), and contributions are welcome. ## Related - [Quick start](/quick-start) - [Self-hosting](/self-hosting/) - [Contribute to Casama](/develop/contributing) - [FAQ](/faq) # Quick start Get a Casama server running, sign in, and give your first bot a task. With Docker already installed, this takes about 15 minutes, most of it building images. Don't want to run a server? Sign up for [Casama Cloud](https://casama.ai) in the app or at [app.casama.ai](https://app.casama.ai), and skip to [step 5](#_5-meet-your-first-bot). ## 1. Start a server You need a machine with Docker. For a trial on your own computer: ```sh git clone https://github.com/stackwares/casama && cd casama ./install.sh --local ``` For a server other people reach over the internet, point a domain at the machine first, then: ```sh ./install.sh --domain casama.example.com ``` The installer checks Docker, generates every secret, builds and starts the stack, and waits until it's healthy. It prints the address when it's done. Add `--pull` to download the published images instead of building them. See [Self-hosting](/self-hosting/) for requirements, every option and production advice. ::: tip Prefer not to use a terminal? The desktop app on macOS and Linux can run a server on the computer it's installed on: start Docker Desktop, then on the sign-in screen choose **More Options** → **Run Casama on This Computer**. It needs about 10 GB of free disk. ::: ::: tip Want to use it from your phone? A server installed with `--local` answers only on that computer. [Casama Link](/self-hosting/remote-access) gives it an address your phone can reach from anywhere, with no domain and no open ports, for free. Set it up after step 3. ::: ## 2. Install a client - **Apps**: iOS, Android, macOS, Windows, Linux and the web. - **CLI**: `brew install stackwares/tap/casama`, or download a binary from the [releases page](https://github.com/stackwares/casama/releases). See [CLI](/develop/cli). ## 3. Sign in to your server **In the app:** 1. Tap **Let's Go**. 2. Tap **More Options**, then the button that shows the current server (**Server:** followed by an address). Enter your server's address (for example `https://casama.example.com`, or the address `--local` printed) and tap **Connect**. 3. Tap **Continue with Email** → **Use a Password Instead** → **New here? Create an account**, and enter an email and password. The first account on a server becomes its owner. ::: info Email links, Google and Apple Signing in with an emailed link needs the server to send email, and Google and Apple sign-in need them set up on the server. A new server has neither, so start with a password. See [Configuration](/self-hosting/configuration). ::: **With the CLI:** ```sh casama config --api-url https://casama.example.com casama signup --email you@example.com ``` ## 4. Add a model Bots need a model. On Casama Cloud they already have one. On your own server, open **Settings** → **Model keys** and pick one of these: - **Continue with ChatGPT** to use a ChatGPT plan you already pay for. This needs the desktop app, or `casama credential chatgpt` in the CLI. - **Add Key** for OpenRouter, OpenAI, Anthropic, Google or xAI. - **Add Key** → **OpenAI-compatible server** for a local model served by Ollama, LM Studio or vLLM. Use an address the server can reach: on a self-hosted server, that's the model machine's network address rather than `localhost`, allowed with `OUTBOUND_ALLOW_CIDRS` (see [Configuration](/self-hosting/configuration)). Calls to a local model cost nothing. With the CLI: ```sh casama credential add --provider openrouter # prompts for the key casama credential chatgpt # or sign in with a ChatGPT plan casama credential add --provider openai_compatible --base-url http://192.168.1.20:11434/v1 ``` ## 5. Meet your first bot The first time you sign in, the app asks **What should bots call you?**, then makes a workspace named after you and a personal bot called Casama, and opens its chat. This is the bot's **General** conversation, where quick questions, briefs and its suggestions land. The chat starts empty, with tiles to **Connect your apps** and a few starter requests you can tap. Prefer to set things up yourself? Choose **Set Up Manually** while the workspace is being made. Your first bot has check-ins on: each morning it sends a brief, and during the day it looks for things it could help with and offers them as suggestions you accept or dismiss. See [Routines and triggers](/guide/routines#check-ins). With the CLI: ```sh casama org create "My team" && casama org use my-team casama credential list # find your key's id casama bot create Ada --credential casama chat Ada "Research the top three open-source vector databases and write a comparison to report.md" ``` ## 6. Give it real work Try a task that needs its computer: > Find the five most-starred Rust web frameworks on GitHub, compare their latest releases, and save > a table to `frameworks.md`. Open the bot's computer to watch it work. When it wants to do something risky, an approval appears in the chat and as a notification. What it makes, such as the table above, reports, pictures and sites, is kept in the [Library](/guide/library). ## Next steps - Connect your tools: [Apps and connections](/guide/connections) - Put it on a schedule: [Routines and triggers](/guide/routines) - Decide what it may do on its own: [Autonomy and approvals](/guide/autonomy) - Invite your team: [Workspaces and teams](/guide/workspaces) - Reach it from Slack, Teams, Telegram and more: [Chat apps](/guide/chat-apps) - Use it from your coding tool: [Connect AI apps](/guide/mcp) # Cloud computers and credits (Casama Link) Run your own Casama server, but let Casama Cloud host the bots' computers or pay for the model calls. A Casama Link key from a Casama Cloud workspace gives your server both, billed to that workspace's credits. This is the paid half of Casama Link. The free half, an address your phone can reach plus notifications, is on [Use your server on your phone](/self-hosting/remote-access). See the [Casama Link overview](/guide/casama-link) for how the two fit together. ## How it works - A workspace owner or admin creates a Casama Link key in Casama Cloud, named after your server. - Your server uses that key to create computers on Casama Cloud and to call models through it. - Computer time and model calls show on the cloud workspace's bill under your server's name, and are paid from its credits. Everything else (your bots, chats, memory, files and data) stays on your server. ## 1. Create a key in Casama Cloud You need to be an owner or admin of the cloud workspace. 1. In the Casama Cloud app, open **Settings → Billing**. 2. Open **Charges by server, Casama Link servers and keys**. 3. Under **Casama Link**, choose **New Casama Link Key**. 4. Enter a **Server name**, such as `home-server`, and choose **Create**. 5. Copy the key. It starts with `kcc_` and is shown only once. A key from the app can use both computers and models. Through the API you can pick what a key may do with `scopes` on `POST /v1/orgs/{id}/link/keys`: | Scope | Lets the server | Spends credits | | --------------- | ------------------------------------------------ | -------------- | | `computers` | Create and use computers on Casama Cloud | Yes | | `models` | Call models through Casama Cloud | Yes | | `remote_access` | Hold a `casama.link` address | No | | `push` | Send notifications to the store apps | No | A key made by linking (`casama selfhost remote on`, or **Use on Your Phone** in the app) has only `remote_access` and `push`. ## 2. Configure your server Add both values to `infra/compose/.env`: ```sh CASAMA_CLOUD_URL=https://api.casama.ai CASAMA_CLOUD_KEY=kcc_... ``` Then run `casama selfhost up`. The API and worker now offer a computer provider named `casama-cloud`. ::: tip One key per server A server holds one `CASAMA_CLOUD_KEY`. To use cloud computers or credits and remote access together, create the key through the API with all four scopes, set it in `.env`, then run `casama selfhost remote on`, which keeps a key that can already hold an address. Linking again replaces the key with one that can't spend credits. ::: ## 3. Use cloud computers Create a computer with the provider `casama-cloud` through the API: ```http POST /v1/computers Content-Type: application/json { "org_id": "", "name": "Cloud computer", "kind": "team", "provider": "casama-cloud" } ``` The computer runs on Casama Cloud, and bots use it like any other computer: shell, files, browser, sleep and wake. If the server has no `CASAMA_CLOUD_KEY`, the request fails with `link_cloud_off`. If the key lacks the `computers` scope, Casama Cloud refuses with `computers_unavailable`. See [API](/develop/api) and [Computers](/guide/computers). ## 4. Use model credits Add an OpenRouter model key that points at Casama Cloud, with the Casama Link key as the API key: ```sh casama credential add --provider openrouter --label "Casama Cloud" \ --base-url https://api.casama.ai/link/v1/models \ --key kcc_... ``` Then pick that key and a model in a bot's settings. Casama Cloud passes the calls to its own model provider (OpenRouter by default) and bills the cost that provider reports. ## Billing | What | How it's billed | | ------------------- | ------------------------------------------------------------ | | Cloud computer time | Per hour, from create or wake until sleep or delete | | Model calls | The provider's reported cost, with Casama Cloud's markup | Usage appears on the cloud workspace's **Billing** screen with your server's name, and is deducted from its credits. When the credits run out, new computers, wake-ups, commands and model calls are refused with `out_of_credits` until credits are added. Model calls also stop for the day when the workspace reaches its daily limit for model credits. See [Usage, budgets and plans](/guide/usage). ## Revoke a key 1. In Casama Cloud, open **Settings → Billing**, then **Charges by server, Casama Link servers and keys**. 2. Under **Casama Link**, choose the delete icon next to the server. 3. Confirm **Revoke**. That server stops using cloud computers and credits right away. If the key also held an address, the address is removed too. ## Limits - Live view and terminals for cloud computers aren't available through Casama Link. Bots can still use the computer. - The app has no option to pick the `casama-cloud` provider when creating a computer. Use the API. - The app's model key form shows **Base URL** only for an OpenAI-compatible server, so add the OpenRouter key with the CLI or the API. - A cloud computer belongs to the cloud workspace that first created it. Other cloud workspaces can't use it. ## Related - [Casama Link overview](/guide/casama-link) - [Use your server on your phone](/self-hosting/remote-access) - [Computer providers](/self-hosting/computers#casama-link-computers) - [Configuration](/self-hosting/configuration#casama-link) - [Usage, budgets and plans](/guide/usage) - [CLI](/develop/cli) # Computer providers Every bot can have its own Linux computer: a shell, files, a browser and, with the desktop image, a screen you can watch live. The sandbox supervisor creates these computers through a **provider**. The default provider runs them as Docker containers on your server. You can also run them on E2B, Daytona, Novita, Kubernetes, Incus, Boat or Railway, on Casama Cloud through Casama Link, or on people's own machines through the desktop companion. This page covers each provider's setup and settings, the computer images, the egress proxy, the TURN relay for live view, and resource limits. For what computers do for bots, see [Computers](/guide/computers). ## How providers fit together The API and worker talk to one supervisor (`SUPERVISOR_URL`, `SUPERVISOR_TOKEN`). The supervisor holds the object store and the secret that derives each computer's tokens, so every provider runs inside it: - **Docker** runs on the supervisor's own Docker host. It's set up when it's the default provider. - **Hosted providers** (E2B, Daytona, Novita, Kubernetes, Incus, Boat, Railway) are turned on by their settings on the supervisor. Each starts Casama's own computer image with `computerd` inside, so files, commands, checkpoints, sleep and wake, and live view work the same everywhere. - **Casama Cloud** (`casama-cloud`) is set up on the API and worker, not the supervisor. See [Casama Link computers](#casama-link-computers). - **People's own machines** (`local`) connect through the desktop companion. It's on by default (`LOCAL_COMPUTERS`). See [Companion](/guide/companion). Each computer records its provider when it's created. `DEFAULT_PROVIDER` on the supervisor decides where computers go that ask for the default (`docker`), which is what the apps do. A computer created through the API can name another provider in its `provider` field, as long as that provider is configured on the supervisor. ::: warning Settings go on the supervisor The bundled compose file passes only the Docker settings to the `supervisor` service. To use a hosted provider, add its settings to `services.supervisor.environment` in `infra/compose/docker-compose.yml` (see [Advanced settings](/self-hosting/configuration#advanced-settings)), then run `casama selfhost up`. ::: To send every new computer to a hosted provider, set its settings and `DEFAULT_PROVIDER`, for example: ```yaml # infra/compose/docker-compose.yml, under services.supervisor.environment DEFAULT_PROVIDER: e2b E2B_API_KEY: ${E2B_API_KEY:-} ``` With a hosted default, the supervisor doesn't set up Docker at all, so it needs no Docker socket. The supervisor refuses to start if `DEFAULT_PROVIDER` names a provider that isn't configured. ## Docker The default. Each computer is a container named `casama-c-` with its own volume for `/home/casama` and its own internal Docker network. The supervisor joins that network to reach `computerd`, the egress proxy joins it to give the computer internet access, and the TURN relay joins desktop computers' networks for live view. Every container runs with: - user `1000:1000`, a read-only root filesystem, and `/tmp` as a 1 GB in-memory filesystem; - all Linux capabilities dropped and `no-new-privileges`; - CPU, memory (swap capped at the same amount) and a 512-process limit; - `HTTP_PROXY` and `HTTPS_PROXY` pointing at the egress proxy with per-computer credentials. ### gVisor on Linux With gVisor (`runsc`), each computer gets a user-space kernel between it and the host. The installer sets `SANDBOX_RUNTIME=runsc` on the first run when `docker info` lists `runsc`. To add it later, install gVisor, register it with Docker, set `SANDBOX_RUNTIME=runsc` in `infra/compose/.env` and run `casama selfhost up`. Computers pick it up the next time they start. ### Docker settings | Name | Compose default | What it does | | ------------------------- | --------------------------------------- | ---------------------------------------------------------------------------- | | `SANDBOX_RUNTIME` | Set by the installer | Docker runtime for computers (`runsc` for gVisor). Empty: Docker's default. | | `COMPUTER_IMAGE_HEADLESS` | `/computer-headless:` | Image for headless computers. `casama/computer-headless:local` unless you installed with `--pull`. | | `COMPUTER_IMAGE_DESKTOP` | `/computer-desktop:` | Image for desktop computers. | | `COMPUTER_MEMORY_MB` | `2048` | Memory for each new computer. | | `COMPUTER_CPUS` | `1` (not passed by Compose) | CPUs for each new computer. | | `WARM_POOL_SIZE` | `0` | Started headless computers kept waiting. See [Scaling](/self-hosting/operations#scaling). | | `DOCKER_SOCKET` | `/var/run/docker.sock` | The Docker socket the supervisor uses. | | `EGRESS_CONTAINER` | `casama-egress` | Container name of the egress proxy. | | `EGRESS_CONTROL_URL` | `http://casama-egress:3129` | The egress proxy's control API. | | `EGRESS_CONTROL_TOKEN` | Generated | Token for the control API. | | `TURN_CONTAINER` | `casama-turn` | Container name of the TURN relay. | | `SUPERVISOR_CONTAINER` | `casama-supervisor` | The supervisor's own container name, so it can join computer networks. | | `COMPUTER_TOKEN_SECRET` | Generated | Derives each computer's tokens. Don't change it on a running server. | Compose names the egress proxy, TURN relay and supervisor containers with a prefix, `CASAMA_CONTAINER_PREFIX` (default `casama`), and bot computers' containers, networks and volumes use it too (`NAME_PREFIX` on the supervisor). To run two Casama stacks on one Docker host, give the second one its own prefix and its own ports in its `.env`. ## E2B Runs computers as E2B sandboxes from templates built from Casama's images. 1. Build E2B templates from the headless image (and the desktop image for live view), with `computerd` as the start command. Name them `casama-computer-headless` and `casama-computer-desktop`, or set the names below. 2. Add the settings to the supervisor and run `casama selfhost up`. | Name | Default | What it does | | ----------------------- | --------------------------- | ------------------------------- | | `E2B_API_KEY` | (empty) | Turns the provider on. | | `E2B_API_URL` | `https://api.e2b.app` | E2B API address. | | `E2B_TEMPLATE_HEADLESS` | `casama-computer-headless` | Template for headless computers. | | `E2B_TEMPLATE_DESKTOP` | `casama-computer-desktop` | Template for desktop computers. | ## Daytona Runs computers from Daytona snapshots built from Casama's images. | Name | Default | What it does | | ---------------------------- | ------------------------------- | -------------------------------- | | `DAYTONA_API_KEY` | (empty) | Turns the provider on. | | `DAYTONA_API_URL` | `https://app.daytona.io/api` | Daytona API address. | | `DAYTONA_ORGANIZATION_ID` | (empty) | Your Daytona organization. | | `DAYTONA_SNAPSHOT_HEADLESS` | `casama-computer-headless` | Snapshot for headless computers. | | `DAYTONA_SNAPSHOT_DESKTOP` | `casama-computer-desktop` | Snapshot for desktop computers. | ## Novita Novita Agent Sandbox is E2B-compatible: build templates from the images as for E2B. | Name | Default | What it does | | -------------------------- | ---------------------------------- | -------------------------------- | | `NOVITA_API_KEY` | (empty) | Turns the provider on. | | `NOVITA_API_URL` | `https://api.sandbox.novita.ai` | Novita API address. | | `NOVITA_TEMPLATE_HEADLESS` | `casama-computer-headless` | Template for headless computers. | | `NOVITA_TEMPLATE_DESKTOP` | `casama-computer-desktop` | Template for desktop computers. | ## Image-based providers Kubernetes, Incus, Boat and Railway run the computer images directly from a registry. They share two settings: | Name | Default | What it does | | ----------------------- | ------------------------------------------------ | ------------------------------- | | `HOSTED_IMAGE_HEADLESS` | `ghcr.io/stackwares/casama/computer-headless:latest` | Image for headless computers. | | `HOSTED_IMAGE_DESKTOP` | `ghcr.io/stackwares/casama/computer-desktop:latest` | Image for desktop computers. | If you build your own images, push them to a registry these providers can pull from and set both. ### Kubernetes One pod per computer, created in a namespace through the Kubernetes API. Inside the cluster, the supervisor uses its service account and reaches pods by IP; outside, it uses the API server's pod proxy. The [Helm chart](/self-hosting/operations#kubernetes-with-helm) sets this up for you. | Name | Default | What it does | | ------------------------ | ------------------------------- | -------------------------------------------------------------------- | | `K8S_NAMESPACE` | (empty) | Turns the provider on: the namespace for computer pods. | | `K8S_API_URL` | The in-cluster API server | API server address, when the supervisor runs outside the cluster. | | `K8S_TOKEN` | The pod's service account token | Bearer token for the API server. | | `K8S_CA_FILE` | The pod's service account CA | CA certificate file for the API server. | | `K8S_IMAGE_PULL_SECRET` | (empty) | Image pull secret for computer pods. | | `K8S_RUNTIME_CLASS` | (empty) | Runtime class for computer pods, for example gVisor or Kata. | The supervisor needs `create`, `get`, `list` and `delete` on pods, and access to `pods/proxy`, in that namespace. ### Incus A container per computer, pulled from an OCI registry and reached on the instance's IPv4 address. | Name | Default | What it does | | ------------------------- | ------------------- | -------------------------------------------------------------------- | | `INCUS_URL` | (empty) | Turns the provider on: the Incus API address, for example `https://incus.example.com:8443`. | | `INCUS_TOKEN` | (empty) | Bearer token. Or use a client certificate: | | `INCUS_CLIENT_CERT_FILE` | (empty) | Client certificate file. | | `INCUS_CLIENT_KEY_FILE` | (empty) | Client key file. | | `INCUS_CA_FILE` | (empty) | CA certificate for the Incus server. | | `INCUS_REGISTRY` | `https://ghcr.io` | Registry the images come from. The `ghcr.io/` part of the image names is dropped. | | `INCUS_PROJECT` | (empty) | Incus project. | ### Boat A VM per computer. Boat doesn't run OCI images, so the VM runs the computer image with Docker. | Name | Default | What it does | | -------------------- | --------------------------- | ------------------------- | | `BOAT_API_KEY` | (empty) | Turns the provider on. | | `BOAT_API_URL` | `https://boat.dev/api/v1` | Boat API address. | | `BOAT_SANDBOX_TYPE` | (empty) | Boat sandbox type. | ### Railway A Railway service per computer, in one project and environment, with a Railway domain per port. | Name | Default | What it does | | ------------------------- | --------- | --------------------------------------------------------------- | | `RAILWAY_TOKEN` | (empty) | Railway API token. With the next two, turns the provider on. | | `RAILWAY_PROJECT_ID` | (empty) | Project for computer services. | | `RAILWAY_ENVIRONMENT_ID` | (empty) | Environment for computer services. | | `RAILWAY_TOKEN_KIND` | (account) | `project` when `RAILWAY_TOKEN` is a project token. | ### What changes on hosted providers - **Internet access.** Hosted computers use the provider's own network, so the egress proxy's private-range blocking doesn't apply. - **Live view** needs the TURN relay to be reachable from the internet. The supervisor gives hosted computers `TURN_PUBLIC_HOST` and `TURN_PORT`. - **Resource limits.** `COMPUTER_MEMORY_MB` and `COMPUTER_CPUS` apply to Docker only. Hosted providers set CPU and memory only for a computer with its own size; otherwise the provider's defaults apply. - **The warm pool** is Docker only. - Archives on sleep still go to the supervisor's object store. ## Casama Link computers With `CASAMA_CLOUD_URL` and `CASAMA_CLOUD_KEY` set on the API and worker, computers created with the `casama-cloud` provider run on Casama Cloud, and their time is billed to the Casama Cloud workspace that made the key. The key needs the `computers` scope; a key made by linking for remote access doesn't have it. Live view and terminals aren't available for these computers. See [Cloud computers and credits](/self-hosting/casama-link-cloud) and [Configuration](/self-hosting/configuration#casama-link). ## Images Casama has two computer images, both built from `infra/images/computer/`: | Image | Contents | | --------------------------- | ------------------------------------------------------------------------------------------ | | `computer-headless` | Ubuntu 24.04, `computerd`, shell tools, git, Node.js 24, Python 3, Chromium, agent-browser, LibreOffice, pandoc, Poppler, qpdf and Tesseract | | `computer-desktop` | The headless image plus an X server, a window manager, accessibility tools, a text editor and the Neko WebRTC streamer for live view | The installer always builds the headless image, or pulls it with `--pull`. Get the desktop image with `./install.sh --with-desktop`, or build it on its own: ```sh COMPOSE_PROFILES=images docker compose -f infra/compose/docker-compose.yml --env-file infra/compose/.env build computer-desktop ``` Compose tags them `${CASAMA_REGISTRY}/computer-headless:${CASAMA_VERSION}` and `${CASAMA_REGISTRY}/computer-desktop:${CASAMA_VERSION}` (by default `casama/...:local`; with `--pull`, `ghcr.io/stackwares/casama/...` at the pulled tag). To build them outside Compose: ```sh docker build -f infra/images/computer/Dockerfile.headless -t casama/computer-headless:dev . docker build -f infra/images/computer/Dockerfile.desktop \ --build-arg BASE=casama/computer-headless:dev -t casama/computer-desktop:dev . ``` Both build on x86-64 and ARM64. `computerd` listens on port 7070; the headless image starts it with `CMD ["computerd"]`, and the desktop image with `desktop-start`. Rebuild or pull the images after each upgrade (the installer does this for the headless image, and for the desktop image with `--with-desktop`). A computer picks up a new image the next time it sleeps and wakes. For hosted providers, rebuild your templates, snapshots or registry images too. ## The egress proxy The `egress` service is the only route from Docker computers to the internet. It's an HTTP forward proxy (plain requests and `CONNECT`): - Each computer authenticates with its own credentials, so the proxy knows which computer made each connection. - It resolves host names itself and refuses if any address is private, loopback, link-local (cloud metadata), CGNAT, multicast or reserved, including IPv4-mapped IPv6. It then connects to the address it checked, which defeats DNS rebinding. - Non-HTTP traffic, such as SSH, has no route out. - `EGRESS_BLOCKED_CIDRS` on the `egress` service adds more ranges to block. - `EGRESS_ABUSE=on` also refuses outbound mail ports and crypto-mining traffic and reports it. It's off on self-hosted servers by default. Computers can't reach your LAN through the proxy. `OUTBOUND_ALLOW_CIDRS` lets the API and worker reach LAN services, not computers. ## TURN for live view Live view streams a desktop computer's screen over WebRTC through the `turn` service (coturn). Viewers always use the relay; media flows viewer ↔ relay ↔ computer, so the computer is never reachable from outside. The relay refuses every peer address except its own, so it can't be used to reach other hosts. 1. Build the desktop image (`./install.sh --with-desktop`). 2. Open port 3478, UDP and TCP, on the server. Compose publishes both. 3. Make sure `TURN_PUBLIC_HOST` is a name viewers can resolve to the server. The installer sets it to your domain, or `localhost` for `--local`. The streamer starts with the first viewer and stops 60 seconds after the last one leaves (`STREAM_IDLE_STOP_MS` on the supervisor). Credentials are short-lived and derived from `TURN_SECRET`. The bundled relay doesn't serve TLS (`turns:` on 5349), so viewers on networks that block UDP and port 3478 can't connect. With Casama Link remote access on, viewers who aren't on the server's own computer can't reach this relay. They get credentials for Casama Cloud's relay instead, and the `turn` container forwards one extra port (3479, not published) to it, so bots' computers can reach it without any other way out. See [Live view away from the computer](/self-hosting/remote-access#live-view-away-from-the-computer). ## Resource limits | Limit | Docker default | Set with | | ------------------ | --------------------------------- | -------------------------------------------- | | Memory | 2048 MB (swap capped the same) | `COMPUTER_MEMORY_MB` | | CPUs | 1 | `COMPUTER_CPUS` (add it to Compose) | | Processes | 512 | Fixed | | `/tmp` | 1 GB in memory | Fixed | | Shared memory | 512 MB | Fixed | | Idle before sleep | 5 minutes | Fixed | Home folders live on a Docker volume per computer, with no size limit of their own; watch disk use on the host. Team computers have one screen, so a workspace admin sets how many bots can use desktop tools at once from the team computer's menu (**Desktop users at once**). ## Related - [Computers](/guide/computers) - [Cloud computers and credits](/self-hosting/casama-link-cloud) - [Companion](/guide/companion) - [Configuration](/self-hosting/configuration) - [Operations](/self-hosting/operations) - [Troubleshooting](/self-hosting/troubleshooting) # Configuration Every setting for a Compose install lives in one file: `infra/compose/.env`. The installer writes it on the first run with generated secrets and a few defaults. This page lists every setting you can put there, grouped by topic, with its default and what it does. If you run Casama with Helm or on a platform like Render or Railway, the same names apply as environment variables on the API, worker and supervisor. See [Database and auth](#database-and-auth) for the ones Compose sets for you. ## Change a setting 1. Edit `infra/compose/.env`. Use one `NAME=value` per line. An empty value counts as unset. 2. Apply it: ```sh casama selfhost up ``` Or, without the CLI: ```sh docker compose -f infra/compose/docker-compose.yml --env-file infra/compose/.env up -d ``` Compose recreates every service whose settings changed. All Casama services read their settings only at start, so every change needs this step. `docker compose restart` is not enough: it restarts containers with their old settings. ::: tip Optional profiles `casama selfhost up` names no Compose profile except `link`, which it adds while remote access is on. If you changed a setting for the web app, monitoring, search, page PDFs or backups, add the profile: `docker compose ... --profile monitoring up -d`. Docker Compose also reads `COMPOSE_PROFILES` from the env file, so `COMPOSE_PROFILES=monitoring,web` in `.env` keeps them on for every command. Re-running `./install.sh` adds the `backup` profile by itself once you installed with `--backups`. ::: Some settings are read by the server but not passed through by the bundled compose file. They're listed under [Advanced settings](#advanced-settings), with how to add them. ## Core and URLs | Name | Default | What it does | | ------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `CASAMA_SITE` | Set by the installer | What Caddy serves: a domain (`casama.example.com`, automatic HTTPS) or `:80` (plain HTTP, for `--local` or behind another proxy). | | `CASAMA_PUBLIC_URL` | Set by the installer | The public address, for example `https://casama.example.com`. Used as the API, app and Supabase address and for Auth redirects. | | `HTTP_PORT` | `80` | Host port Caddy listens on for HTTP. | | `HTTPS_PORT` | `443` | Host port Caddy listens on for HTTPS. | | `CASAMA_PAGES_SITE` | `:8790` | What Caddy serves Pages on: a domain of its own (`pages.example.com`, automatic HTTPS) or a port. | | `CASAMA_PAGES_URL` | `http://localhost:8790` | The public address of Pages, used in links to bots' pages. Set it to match `CASAMA_PAGES_SITE`. | | `PAGES_PORT` | `8790` | Host port Caddy publishes for Pages. | | `CORS_ORIGINS` | (empty) | Extra comma-separated web origins allowed to call the API from a browser. The public address is always allowed. | | `RATE_LIMIT_PER_MINUTE` | `120` | Requests per minute on the API and webhooks, per signed-in user or else per IP address. Casama Link endpoints get ten times as much. | | `UPDATE_CHECK_URL` | (empty: no update checks) | Where the admin console checks for new releases, in the shape of GitHub's latest-release API. | | `CASAMA_REGISTRY` | `casama` (build locally) | Where the Casama images come from. `./install.sh --pull` sets `ghcr.io/stackwares/casama`, and re-runs then pull instead of build. | | `CASAMA_VERSION` | `local` | The tag of the Casama images Compose builds or pulls. `--pull [tag]` sets it (default `latest`). | | `CASAMA_SERVER_IMAGE` | (empty: registry and tag above) | Runs the API and worker on one exact image, such as your own build of `apps/server/Dockerfile`. Upgrades leave it alone; empty it to go back. | | `HTTP_BIND` | `0.0.0.0` | The address Caddy's HTTP, HTTPS and Pages ports listen on. `--behind-proxy` and `--local` set `127.0.0.1`. | | `TRUSTED_CLIENT_IP_HEADER` | (empty: `X-Forwarded-For`) | A header your edge sets with the caller's address, for rate limits on signed-out requests. Behind Cloudflare, `cf-connecting-ip`. | | `AUTH_RATE_LIMIT_HEADER` | (empty: Auth's default) | The same for Supabase Auth's per-caller sign-in limits. Behind Cloudflare, `cf-connecting-ip`. | | `CASAMA_CONTAINER_PREFIX` | `casama` | Prefix of the fixed container names and of bot computers' containers, networks and volumes. Change it to run two stacks on one machine. | | `PAIR_LINK_URL` | `https://casama.ai/pair` | The page a sign-in QR code opens, which hands the code to the app. The code rides after `#`, so the page never receives it. | **Pages on their own domain.** Bots' web pages are served from a separate origin so a page's scripts never share an origin with Casama. On a public server, give them their own name: ```sh CASAMA_PAGES_SITE=pages.casama.example.com CASAMA_PAGES_URL=https://pages.casama.example.com ``` Point the name's DNS at the server; Caddy gets its certificate automatically. **Change the address after installing.** Re-running the installer doesn't change the address. Edit these together, then run `casama selfhost up`: ```sh CASAMA_SITE=casama.example.com CASAMA_PUBLIC_URL=https://casama.example.com TURN_PUBLIC_HOST=casama.example.com SIGNUP_HOOK_URI=https://casama.example.com/hooks/auth/before-user-created ``` ### Behind another proxy If a load balancer or another reverse proxy terminates TLS: 1. Set `CASAMA_SITE=:80` so Caddy serves plain HTTP. `./install.sh --behind-proxy --domain ` does this. 2. Keep `CASAMA_PUBLIC_URL` on the public `https://` address. 3. Route your proxy to Caddy's HTTP port (`HTTP_PORT`), including WebSocket upgrades. 4. Set `HTTP_BIND=127.0.0.1` (the installer does this with `--behind-proxy`). Docker-published ports skip the host firewall, so `0.0.0.0` would serve plain HTTP to anyone who can reach the server's IP. 5. Keep port 3478 (UDP and TCP) reachable directly for live view, and set `TURN_PUBLIC_HOST` (`--turn-host`) to a name that points at the server with DNS only, not through the HTTP proxy. Media stays inside coturn, so the relay range 49160–49260 does not need to be open. 6. If the proxy is a tunnel on the same machine (Cloudflare Tunnel, for example), every request reaches Caddy from the tunnel's own address. Set `TRUSTED_CLIENT_IP_HEADER` to the header that carries the real address (`cf-connecting-ip` for Cloudflare), or all signed-out callers share one rate limit. ## Generated secrets The installer generates these on the first run. Don't edit them on a running server unless the table says it's safe: several are baked into the database or into each other. | Name | What it is | Safe to change? | | ------------------------ | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | | `POSTGRES_PASSWORD` | Password for Postgres and the Supabase service roles | No. Postgres keeps the password it was first started with. | | `WORKER_DB_PASSWORD` | Password for `casama_worker`, the worker's least-privilege database role | Yes. The `migrate` service sets it again at every start. | | `AUTH_HOOK_SECRET` | Shared secret for the sign-up hook (`v1,whsec_…`), on Auth and the API | Yes, if you change it in both places and restart Auth and the API. | | `JWT_SECRET` | Signs Supabase tokens | No. `ANON_KEY` and `SERVICE_ROLE_KEY` are signed with it. | | `ANON_KEY` | Supabase anon key (a JWT) | No | | `SERVICE_ROLE_KEY` | Supabase service role key (a JWT) | No | | `SECRET_KEY_BASE` | Supabase Realtime's secret | No | | `REALTIME_ENC_KEY` | Supabase Realtime's encryption key | No | | `SAML_PRIVATE_KEY` | Supabase Auth's SAML signing key (RSA, PKCS#1, base64 DER) | No | | `SUPERVISOR_TOKEN` | The API and worker's token for the supervisor (16+ characters) | Yes, with a full `casama selfhost up` | | `COMPUTER_TOKEN_SECRET` | Derives each computer's own tokens | No. Existing computers would stop answering. | | `EGRESS_CONTROL_TOKEN` | The supervisor's token for the egress proxy's control API | Yes, with a full `casama selfhost up` | | `INTERNAL_TOKEN` | Shared secret for the API's internal endpoints (32+ characters) | Yes, with a full `casama selfhost up` | | `TURN_SECRET` | coturn's shared secret for short-lived live view credentials (16+ characters) | Yes, with a full `casama selfhost up` | | `SEARXNG_SECRET` | SearXNG's own secret (search profile) | Yes, with a full `casama selfhost up` | | `METRICS_TOKEN` | Bearer token for `/metrics` (16+ characters) | Yes. Prometheus picks it up when it restarts. | | `GRAFANA_ADMIN_PASSWORD` | Grafana's `admin` password (monitoring profile) | Only before Grafana's first start; afterwards change it in Grafana. | The installer also generates `CONTENT_ENCRYPTION_KEY` unless you use AWS KMS. See [Encryption keys](#encryption-keys): it can't be changed like the others. ## Database and auth Compose wires these for the API and worker from the generated secrets. Set them yourself only on Helm, a platform like Render, or a custom setup. | Name | Default | What it does | | --------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------- | | `MODE` | `api` | `api` or `worker`. The API and worker are the same image. | | `PORT` | `8787` | The API's HTTP port. | | `NODE_ENV` | `development` | Set `production` in production (Compose does). | | `DATABASE_URL` | Required | Postgres URL with full access, for the API. | | `WORKER_DATABASE_URL` | Falls back to `DATABASE_URL` | The worker's least-privilege URL (`casama_worker`). Compose builds it from `WORKER_DB_PASSWORD`. | | `SUPABASE_URL` | Required | Supabase's public address. Compose uses `CASAMA_PUBLIC_URL`, since Caddy routes `/auth/v1` and friends. | | `SUPABASE_ANON_KEY` | Required | Supabase anon key. The apps get it from the server. | | `SUPABASE_JWT_SECRET` | (empty: verify with JWKS) | Supabase's HS256 secret. When unset, tokens are checked against the project's JWKS. | | `SUPABASE_SERVICE_ROLE_KEY` | (empty) | Needed for SAML SSO administration and for sign-in codes (scan to sign in). | | `SUPABASE_INTERNAL_URL` | `SUPABASE_URL` | How the server reaches Supabase itself. Compose uses `http://kong:8000`, since the public address may not answer from inside the stack. | | `PUBLIC_APP_URL` | `http://localhost:3000` | The app's public address. Always allowed by CORS. | | `PUBLIC_API_URL` | The request's origin | The API's public address, used in OAuth redirects, phone call webhooks and live view. | | `PAGES_URL` | `http://localhost:8790` | Public address of Pages. Compose sets it from `CASAMA_PAGES_URL`. | | `PAGES_PORT` | (unset: Pages not served) | Port the API process serves Pages on. Compose uses `8790` inside the stack. | | `API_INTERNAL_URL` | `http://127.0.0.1:$PORT` | How the worker reaches the API's internal endpoints. | | `INTERNAL_TOKEN` | Derived from `DATABASE_URL` | Shared secret for internal endpoints. Always set a random value; the server warns in production without one. | | `SUPERVISOR_URL` | (unset: no computers) | The sandbox supervisor's address. Compose uses `http://casama-supervisor:8788`. | | `SUPERVISOR_TOKEN` | (unset) | Token for the supervisor. | ## Page PDFs **Export PDF** on a page prints it with headless Chromium. Chromium can't keep its own sandbox inside a normal container, so it runs in a container of its own (Gotenberg, about 500 MB) that holds no secrets and sits on a private network with only the API on it: no internet, no database. Pages are printed from what the API sends; outside URLs and other files are blocked. 1. Add `pdf` to `COMPOSE_PROFILES` in `infra/compose/.env` (or pass `--profile pdf`). 2. Set `PDF_RENDERER_URL=http://pdf:3000` in the same file. 3. Run `docker compose -f infra/compose/docker-compose.yml --env-file infra/compose/.env up -d`. | Name | Default | What it does | | ------------------ | ----------------------- | ----------------------------------------------------- | | `PDF_RENDERER_URL` | (empty: PDF export off) | The PDF sidecar's address. Compose: `http://pdf:3000`. | On Helm, run `gotenberg/gotenberg:8.39.0-chromium` as its own Deployment with a NetworkPolicy that only lets the API in and nothing out, and set `PDF_RENDERER_URL` with `extraEnv`. ## Invite links Invite links are `/join/`. With the web app running, it shows the invite; without it, Caddy sends `/join/*` to a small page from the API with **Open in Casama**. To have links open the installed apps directly, publish the app-link files: | Name | Default | What it does | | --------------------- | ------------------ | ------------------------------------------------------------------------------------------------ | | `APPLE_APP_IDS` | (empty: no file) | iOS app ids (`TEAMID.ai.casama.app`, comma-separated) for `/.well-known/apple-app-site-association`. | | `ANDROID_APP_PACKAGE` | `ai.casama.app` | Android package for `/.well-known/assetlinks.json`. | | `ANDROID_CERT_SHA256` | (empty: no file) | SHA-256 fingerprints of the Android signing certificates, comma-separated. | | `APP_STORE_URL` | (empty) | App Store page linked from the invite page. | | `PLAY_STORE_URL` | (empty) | Google Play page linked from the invite page. | The apps only claim links for a domain built into them, so on your own domain links open the invite page, whose **Open in Casama** button opens the app and points it at your server. ## Email Supabase Auth sends sign-in links, confirmations and password resets through SMTP. Casama sends invites through the same SMTP server, or through Resend when `RESEND_API_KEY` is set. Email is optional: without it, people sign in with a password and invites return a code to share. | Name | Default | What it does | | ------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------- | | `SMTP_HOST` | (empty: Auth sends no email) | Your SMTP server. | | `SMTP_PORT` | `587` | SMTP port. `465` uses TLS from the start; other ports need STARTTLS. | | `SMTP_USER` | (empty) | SMTP user name. | | `SMTP_PASS` | (empty) | SMTP password. | | `SMTP_ADMIN_EMAIL` | (empty) | The address Auth emails come from. | | `EMAIL_AUTOCONFIRM` | `true` | Confirm new accounts without an email. Set `false` once SMTP works. | | `RESEND_API_KEY` | (empty) | Resend key for invite emails, used instead of SMTP. With neither, an invite returns a code to share. | | `EMAIL_FROM` | `Casama ` | Sender for Casama's own emails. | | `AUTH_SITE_URL` | `CASAMA_PUBLIC_URL` | Where Auth's email links land when the app didn't ask for a place. Set it to your web app's address. | | `EMAIL_TEMPLATE_*` | Casama's branded templates | URLs of Auth's email templates (`_MAGIC_LINK`, `_CONFIRMATION`, `_INVITE`, `_RECOVERY`, `_EMAIL_CHANGE`, `_REAUTHENTICATION`). Override one to use your own. | Links in Auth's emails go to `/auth/v1/verify`, which Caddy sends to Auth. To turn on email confirmation and sign-in links: ```sh SMTP_HOST=smtp.example.com SMTP_PORT=587 SMTP_USER=casama@example.com SMTP_PASS=your-smtp-password SMTP_ADMIN_EMAIL=casama@example.com EMAIL_AUTOCONFIRM=false ``` ## Sign-ups and allowlists | Name | Default | What it does | | ------------------------ | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `INSTANCE_ADMIN_EMAILS` | (empty: the first account) | Comma-separated emails of instance owners, who get the admin console. | | `DISABLE_SIGNUP` | `false` | `true` turns off new sign-ups in Supabase Auth. | | `SIGNUP_ALLOWED_EMAILS` | (empty: anyone) | Only these emails or domains can sign up, comma-separated: `ana@example.com,@example.org` (`example.org` also works for a domain). | | `SIGNUP_HOOK_ENABLED` | `false` | `true` makes Supabase Auth call Casama's sign-up hook. Needed for the allowlist. | | `AUTH_HOOK_SECRET` | (empty) | The hook's signing secret, `v1,whsec_`. Shared by Auth and the API. | | `SIGNUP_HOOK_URI` | Set by the installer | Where Auth calls the hook: `https:///hooks/auth/before-user-created`. Empty for `--local`. | | `ADDITIONAL_REDIRECT_URLS` | `casama://app/login-callback,http://127.0.0.1:*/auth/callback` | Redirect URLs Supabase Auth accepts after sign-in, comma-separated. Keep the default for the apps: iPhone, Mac and Android come back on `casama://`, Windows and Linux on a listener on `127.0.0.1`. | | `SAML_ENABLED` | `true` | SAML SSO in Supabase Auth. Workspaces register their identity provider through the API (needs an enterprise license). | | `ABUSE_CONTROLS` | `auto` (off when self-hosted) | `auto`, `on` or `off`. Sign-up proofs, verified email before computers start, and suspension on egress abuse. Meant for Casama Cloud. | | `EGRESS_ABUSE` | `off` | `on` makes the egress proxy refuse mail and crypto-mining traffic from computers and report it. | To limit sign-ups to your team (needs a `--domain` install, because Supabase Auth only calls https hooks): 1. Generate a secret: ```sh echo "v1,whsec_$(openssl rand -base64 32)" ``` 2. Add to `infra/compose/.env`: ```sh SIGNUP_ALLOWED_EMAILS=@example.com,ana@example.org SIGNUP_HOOK_ENABLED=true AUTH_HOOK_SECRET=v1,whsec_... ``` 3. Run `casama selfhost up`. The allowlist applies to every sign-in method, Google and Apple included. Others see "limited to approved email addresses". An allowlist without a hook secret refuses every sign-up rather than allowing everyone. ::: warning `SIGNUP_HOOK_URI` must be empty or an `https://` address. A plain `http://` address stops Supabase Auth from starting, even with the hook turned off. ::: ## Apple and Google sign-in The sign-in screen offers **Continue with Apple** and **Continue with Google**. A new server has both turned off, so people sign in with email until you set these. They are the accounts people use to enter Casama. A Google client for Gmail, Calendar and Drive is a different setup, under [Integrations](#integrations) below. | Name | Default | What it does | | ------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `APPLE_AUTH_ENABLED` | `false` | `true` turns on Continue with Apple. | | `APPLE_AUTH_CLIENT_IDS` | (empty) | Comma-separated. The Services ID first, then the app id `ai.casama.app`. The first is the browser flow. The app id is the system sheet on iPhone and Mac. | | `APPLE_AUTH_SECRET` | (empty) | Apple's client secret, a signed token. It expires within six months. Make a new one from the same key before it does, or browser sign-in starts failing. | | `GOOGLE_AUTH_ENABLED` | `false` | `true` turns on Continue with Google. | | `GOOGLE_AUTH_CLIENT_ID` | (empty) | The web client id from Google Cloud. To let your own build of the app use Google's sign-in sheet on iPhone and Mac, add its iOS client id after a comma. | | `GOOGLE_AUTH_SECRET` | (empty) | That client's secret. | Apple and Google both send people back to `https:///auth/v1/callback`. Register that exact address. On Apple it is the return URL of the Services ID. On Google it is an authorized redirect URI of the web client. If Apple and Google reach Auth under another name than `CASAMA_PUBLIC_URL`, set that full address in `AUTH_CALLBACK_URL`. 1. In the Apple Developer account, turn on Sign in with Apple for the app id `ai.casama.app`. Create a Services ID and a key. Put the Services ID first in `APPLE_AUTH_CLIENT_IDS`, then `ai.casama.app`. 2. In Google Cloud, create a web OAuth client (not an iOS or Android client) and copy its id and secret. 3. Add the values to `infra/compose/.env` and run `casama selfhost up`. ## Passkeys People can sign in with a passkey (Face ID, a fingerprint or a screen lock) once they add one in Settings → Passkeys. On your own server this works in the browser, under your domain. The App Store and Google Play apps are tied to `casama.ai`, so they hide passkeys when connected to another server. | Name | Default | What it does | | -------------------- | --------------------- | --------------------------------------------------------------------------------------- | | `PASSKEYS_ENABLED` | `false` | `true` turns on passkeys. | | `PASSKEY_RP_ID` | (empty) | Your domain without `https://`, for example `casama.example.com`. Required when on. | | `PASSKEY_RP_ORIGINS` | `CASAMA_PUBLIC_URL` | Comma-separated addresses the web app is served from, if more than the public address. | A passkey belongs to its domain. Changing `PASSKEY_RP_ID` later means everyone adds theirs again. iPhone and Mac use Apple's system sheet, so they need `ai.casama.app` in the client id list. Android, Windows, Linux and the web open the browser, which is what the secret is for. Keep `casama://app/login-callback` (Android) and `http://127.0.0.1:*/auth/callback` (Windows and Linux) in `ADDITIONAL_REDIRECT_URLS`. If the web app is served from another address, add that address too. ## Models and AI Gateway People add their own model keys in the app (Settings → Model keys) or with `casama credential add`. Any OpenAI-compatible endpoint works, including a local Ollama. These settings change server-wide defaults. | Name | Default | What it does | | --------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------- | | `DEFAULT_MODEL_OPENROUTER` | `deepseek/deepseek-v4.1-flash-1017` | Default model for new bots on OpenRouter. | | `DEFAULT_MODEL_OPENAI` | `gpt-6-luna` | Default model for new bots on OpenAI. | | `DEFAULT_REASONING_EFFORT` | `medium` | `none`, `low`, `medium`, `high`, `xhigh` or `max`. | | `LAZY_TOOLS_THRESHOLD` | `30` | Bots with more tools than this load the rest on demand. `0` turns it off. | | `CHATGPT_SIGN_IN` | `auto` (on) | `auto`, `on` or `off`. Lets people use their ChatGPT plan instead of an API key. Each plan serves only its owner. `auto` is on unless billing is on. See [Connect a ChatGPT plan](/guide/bots#connect-a-chatgpt-plan). | | `RUN_CONCURRENCY` | `20` | How many runs one worker processes at once. See [Scaling](/self-hosting/operations#scaling). | | `AI_GATEWAY_URL` | (empty) | Send model calls through Cloudflare AI Gateway: `https://gateway.ai.cloudflare.com/v1//`. | | `AI_GATEWAY_TOKEN` | (empty) | Token for an authenticated gateway, sent as `cf-aig-authorization`. | | `GOOGLE_AI_API_KEY` | (empty) | A server-wide Google AI key: live calls in workspaces without a Gemini or OpenAI key of their own use it. You pay Google for those calls. | With `AI_GATEWAY_URL` set, calls for OpenAI, Anthropic, Google, xAI and OpenRouter keys go through the gateway, for caching, logs and rate limits. A credential with its own base URL keeps it. **Local models.** To use Ollama running on the server, allow the server to reach it with [`OUTBOUND_ALLOW_CIDRS`](#network-and-egress), then add it as an OpenAI-compatible credential with the address the worker container can reach. On Docker Desktop that's `host.docker.internal`: ```sh casama credential add --provider openai_compatible --base-url http://host.docker.internal:11434/v1 ``` On Linux, use the host's LAN address instead (for example `http://192.168.1.20:11434/v1`). ## Object storage Computers' home folders are archived to object storage when they sleep, and checkpoints are kept there too. By default the supervisor stores them on the `objects` Docker volume, which needs nothing extra on one host. For S3-compatible storage (SeaweedFS from the `s3` profile, Cloudflare R2, AWS S3 and others), the supervisor reads these settings: | Name | Default | What it does | | ----------------------- | ---------------------- | -------------------------------------------------------------------- | | `OBJECT_STORE` | (filesystem) | `s3` to use S3-compatible storage. | | `OBJECT_STORE_DIR` | `/data/objects` | Folder for the filesystem store. | | `S3_BUCKET` | Required with `s3` | Bucket name. | | `S3_ENDPOINT` | (AWS) | Endpoint, for example `http://casama-s3:8333` or `https://.r2.cloudflarestorage.com`. | | `S3_REGION` | (empty) | Region, for example `auto` for R2. | | `S3_ACCESS_KEY_ID` | (empty) | Access key. The `s3` profile also creates SeaweedFS's user with it. | | `S3_SECRET_ACCESS_KEY` | (empty) | Secret key. | | `S3_PREFIX` | (empty) | Key prefix inside the bucket. | | `S3_CREATE_BUCKET` | (off) | `true` creates the bucket at start. | ::: warning The bundled compose file doesn't pass these to the supervisor Only `S3_ACCESS_KEY_ID` and `S3_SECRET_ACCESS_KEY` reach the `s3` service. To switch the supervisor to S3, add the settings to the `supervisor` service's `environment:` in `infra/compose/docker-compose.yml`, as shown in [Advanced settings](#advanced-settings). Switching stores doesn't move existing archives, so do it before computers have slept, or copy the `objects` volume's contents to the bucket yourself. ::: With SeaweedFS on the same host: ```sh # infra/compose/.env S3_ACCESS_KEY_ID=casama S3_SECRET_ACCESS_KEY=a-long-random-secret ``` ```yaml # infra/compose/docker-compose.yml, under services.supervisor.environment OBJECT_STORE: s3 S3_ENDPOINT: http://casama-s3:8333 S3_BUCKET: casama S3_CREATE_BUCKET: "true" S3_ACCESS_KEY_ID: ${S3_ACCESS_KEY_ID:-} S3_SECRET_ACCESS_KEY: ${S3_SECRET_ACCESS_KEY:-} ``` Then start it with the profile: ```sh docker compose -f infra/compose/docker-compose.yml --env-file infra/compose/.env --profile s3 up -d ``` `casama selfhost backup` archives the `objects` volume only. With S3, back up the bucket with your storage provider's tools. ### The Library's files The API and worker keep a second store: files bots hand over in replies, which the Library keeps with their versions, and the pictures, videos and sounds in chats. By default it's the `library` Docker volume, mounted at `/data/library`. To keep it in S3-compatible storage instead, set these in `infra/compose/.env`; Compose passes them to the API and worker: | Name | Default | What it does | | ------------------------------- | --------------- | -------------------------------------------------- | | `LIBRARY_OBJECT_STORE` | (filesystem) | `s3` to use S3-compatible storage. | | `LIBRARY_OBJECT_DIR` | `/data/library` | Folder for the filesystem store. | | `LIBRARY_S3_BUCKET` | Required with `s3` | Bucket name. | | `LIBRARY_S3_ENDPOINT` | (AWS) | Endpoint, for example an R2 address. | | `LIBRARY_S3_REGION` | `auto` | Region. | | `LIBRARY_S3_ACCESS_KEY_ID` | (empty) | Access key. | | `LIBRARY_S3_SECRET_ACCESS_KEY` | (empty) | Secret key. | | `LIBRARY_S3_PREFIX` | `library/` | Key prefix inside the bucket. | The scheduled `backup` container includes the `library` volume (`library.tar.gz`). `casama selfhost backup` doesn't; see [Back up your server](/self-hosting/operations#back-up-your-server). ## Computers and sandbox These go to the supervisor. Hosted providers and their settings are on [Computer providers](/self-hosting/computers). | Name | Default | What it does | | -------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------- | | `COMPUTER_MEMORY_MB` | `2048` | Memory for each new computer, in MB. Swap is capped at the same amount. The API also counts a computer with no recorded size as this much. | | `COMPUTER_HOST_MEMORY_GB` | Set by the installer | Memory all hosted computers together may use, in GB. A start past it waits with `capacity_full`. The installer sets the machine's memory less 4 GB (at least 2). `0` means no limit. See [Server capacity](/self-hosting/operations#server-capacity). | | `WARM_POOL_SIZE` | `0` (off) | How many started headless computers to keep waiting, so a new computer starts at once. Docker provider only. | | `SANDBOX_RUNTIME` | Set by the installer | The Docker runtime for computers: `runsc` for gVisor, or empty for Docker's default. | ## Network and egress | Name | Default | What it does | | ----------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `OUTBOUND_ALLOW_CIDRS` | (empty) | Private networks the API and worker may call, comma-separated CIDRs, for example `192.168.1.0/24`. Everything private is blocked otherwise. | | `TURN_PUBLIC_HOST` | Set by the installer | The host name viewers use to reach the TURN relay. The domain, or `localhost` for `--local`. | | `TURN_HOST_PORT` | `3478` | Host port the TURN relay is published on, and the port viewers are given. "Run Casama on this computer" moves it when 3478 is taken. | | `TURN_BIND` | `0.0.0.0` | The address the TURN port listens on. `--local` sets `127.0.0.1`. | `OUTBOUND_ALLOW_CIDRS` covers calls the server makes for bots and people: model endpoints such as Ollama, password managers such as Vaultwarden, connections, MCP servers and memory backends. It doesn't change what computers can reach. The egress proxy always blocks private, loopback, link-local (cloud metadata), CGNAT, multicast and reserved addresses for computers. ## Voice and phone calls Bots phoning other numbers through a workspace's own Twilio account is built but turned off for now. To try it, set `PHONE_CALLS=true` on the server (bots get the `voice.call` tool) and build the app with `--dart-define=PHONE_CALLS=true` (admins see **Workspace settings** → **Phone calls**). It needs a public `https://` address, because Twilio calls back to `PUBLIC_API_URL` (Compose sets it to `CASAMA_PUBLIC_URL`). To ring iPhones for calls through PushKit, the worker needs an APNs token key for the app's bundle: | Name | Default | What it does | | --------------- | --------- | -------------------------------------------------- | | `APNS_KEY_P8` | (empty) | The APNs token key: the `.p8` file's contents. | | `APNS_KEY_ID` | (empty) | The key's id. | | `APNS_TEAM_ID` | (empty) | Your Apple team id. | | `APNS_VOIP_TOPIC` | `ai.casama.app.voip` | The app's VoIP push topic. | ## Push notifications | Name | Default | What it does | | ---------------------- | --------- | ----------------------------------------------------------------------------------------------------------------- | | `FCM_SERVICE_ACCOUNT` | (empty) | A Firebase service account JSON, on one line, for the Firebase project the apps are built with. Unset: no push. | Push only reaches apps built with the same Firebase project as the service account. Without push, the in-app inbox still shows every notification. The apps from the App Store and Google Play are built with Casama's Firebase project, so your own key can't reach them. Link the server to Casama Cloud instead and, as long as `FCM_SERVICE_ACCOUNT` is empty, its notifications and call rings go through there, for free: `casama selfhost remote on` for a server on your own computer, or `casama selfhost remote link` for one with its own domain. With **Private Notifications** on, they carry no text. See [Use your server on your phone](/self-hosting/remote-access#notifications). ## Integrations | Name | Default | What it does | | ----------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GOOGLE_OAUTH_CLIENT_ID` | (empty) | Your Google OAuth client, for Gmail, Calendar and Drive connections. | | `GOOGLE_OAUTH_CLIENT_SECRET` | (empty) | Its secret. | | `MCP_OAUTH_CLIENTS` | (empty) | OAuth clients for apps that don't support automatic registration, as JSON by app id: `{"slack":{"client_id":"...","client_secret":"..."}}`. | | `COMPOSIO_API_KEY` | (empty) | A server-wide Composio key. Apps whose own sign-in needs a client the server doesn't have (GitHub, Slack, Asana, Google's apps without a Google client, and others) then offer **Sign in through Composio**. The admin console's Services tab can switch back to people's own accounts. | | `OAUTH_REDIRECT_URL` | `/oauth/callback` | Where vendors send people back after an app sign-in. Change it only if vendors must use another address. | | `SEARXNG_URL` | (empty) | A SearXNG instance for web search in workspaces without a Brave Search or Tavily key. Free: `./install.sh --search` runs one (`http://searxng:8080`). Its settings must allow JSON results. | | `UNSPLASH_ACCESS_KEY` | (empty) | Wallpaper photo search in Appearance. Without it, the app offers its own patterns and photos. | | `GALLERY_URL` | `https://gallery.casama.ai` | The open gallery of themes, color schemes, wallpapers, skills, apps, starter bots, routine ideas and reviewed plugins. Set to `off` to turn it off; a fork can point here instead. When it can't be reached, the built-in looks, skills, apps and bots stay. | Register `https://casama.example.com/oauth/callback` as the redirect URI in each OAuth app. See [Connections](/guide/connections). ### Gallery The gallery's settings beyond `GALLERY_URL`. The defaults suit almost every server. | Name | Default | What it does | | ---------------------- | ------------------------------------------ | ------------ | | `GALLERY_SIGNATURE` | `optional` | Whether the gallery must be signed. `required`: the server only trusts a catalog whose `manifest.sig` checks out against the public key, and shows the gallery as unavailable otherwise. `optional`: it checks the signature when the catalog has one (a signature that doesn't check out still makes it unavailable). `off`: never checked. With no public key, it's off. | | `GALLERY_PUBLIC_KEY` | (empty) | The catalog's Ed25519 public key, base64 of the raw 32 bytes. Empty: Casama's own key for the default `GALLERY_URL`, none for any other address. Set it when you sign your own catalog (`GALLERY_SIGNING_KEY` in its CI). | | `GALLERY_SOURCES` | (empty) | More catalogs next to the main one, comma-separated: `url`, `name=url`, or `name=url#`. Their items show up with ids like `team:weekly-review`. Each folder is laid out like the gallery's and checked with the same `node gallery/check.mjs`. If one can't be reached, only its items are missing. | | `GALLERY_STATS_URL` | `https://api.casama.ai/v1/gallery/stats` | Where the "Used by 120 people" numbers on gallery items come from. They're Casama's public, aggregate counts (nothing under 10 people is shown). `off` hides them. Your server's own installs aren't sent anywhere. | | `GALLERY_SUBMIT_REPO` | `stackwares/casama-gallery` | Where **Submit to the gallery** opens pull requests (`owner/repo`). | | `GALLERY_SUBMIT_TOKEN` | (empty) | A GitHub token that can push branches and open pull requests on that repository. Empty: **Submit to the gallery** is off on this server. | | `GALLERY_REWARDS` | `{"50":10,"250":25,"1000":75}` | Casama Cloud only (billing on): credits for people whose submitted item reaches that many active users, as JSON (active users → credits). Each item earns each one once. `off` turns rewards off. | An offline server can read a local copy: point `GALLERY_URL` at a folder you serve, made with `casama gallery mirror `, which checks the signature as it downloads. ## Billing Billing is for Casama Cloud. The bundled compose file sets `BILLING_ENABLED=false` for the API and worker, so there's no paywall and no usage limit, and none of the payment settings apply. Settings whose `auto` follows billing keep their self-hosted behaviour: `ABUSE_CONTROLS`, `HEALTH_REQUIRES_ENCRYPTION` and `REFERRALS` stay off, and `CHATGPT_SIGN_IN` stays on. Computer time is recorded at what it costs whoever runs it: E2B and Daytona at their published prices, Docker at a share of the server. Change the prices with `COMPUTER_RATES`, as JSON by provider (`docker`, `e2b`, `daytona`, `local`, `casama-cloud`), in USD per vCPU-hour and per GB-hour: `{"docker":{"cpu_hour":0.003,"gb_hour":0.005}}`. ### Settings only Casama Cloud uses The server reads these, and the compose file passes most of them, but they only do something with `BILLING_ENABLED=true`. Leave them empty on your own server. | Names | What they're for | | --- | --- | | `DODO_*`, `REVENUECAT_*` | Payments on the web, and in the App Store and Google Play | | `REFERRALS`, `REFERRAL_REWARD_USD`, `REFERRAL_WELCOME_USD`, `REFERRAL_REWARD_CAP`, `REFERRAL_REDEEM_DAYS`, `REFERRAL_LINK_BASE` | Invite-a-friend credits | | `SIGNUP_PROOFS`, `SIGNUP_POW_DIFFICULTY`, `APP_CHECK_PROJECT_NUMBER` | Sign-up abuse controls | | `CASAMA_LINK_CLOUD` | Serving Casama Link to other servers (on by default when billing is on) | | `CLOUD_MODEL_UPSTREAM_URL`, `CLOUD_MODEL_UPSTREAM_KEY`, `CLOUD_MODEL_MARKUP`, `CLOUD_COMPUTER_USD_PER_HOUR` | What linked servers' model calls and computers go to and cost | | `CASAMA_LINK_ZONE`, `CASAMA_LINK_CF_ACCOUNT_ID`, `CASAMA_LINK_CF_ZONE_ID`, `CASAMA_LINK_CF_API_TOKEN` | The zone and Cloudflare account that hold linked servers' addresses and tunnels | | `CASAMA_LINK_SIGN_IN_URL` | Where a workspace admin approves a link code (default `/link`) | | `CASAMA_LINK_PARKING`, `CASAMA_LINK_PARK_AFTER_DAYS` | Removing tunnels of servers that stopped checking in (`off`, `dry-run` or `on`; after 14 days) | | `CASAMA_LINK_TUNNEL_ALERT`, `CASAMA_LINK_RECORD_LIMIT` | When the instance owners are warned about tunnel and DNS record counts (700 tunnels, 200 records) | | `CASAMA_LINK_TURN_KEY_ID`, `CASAMA_LINK_TURN_API_TOKEN` | The relay for live view away from the computer (Cloudflare's TURN service) | | `TREG_API_KEY`, `TREG_RESALE` | Paid data resale through Treg | | `SUPPORT_INBOX`, `SUPPORT_ASSISTANT`, `SUPPORT_MODEL`, `SUPPORT_DAILY_USD`, `SUPPORT_MESSAGES_PER_DAY`, `DOCS_URL` | Help & support: where messages from the app go (default support@casama.ai, sent with your email settings) and the free support assistant, which runs on `CLOUD_MODEL_UPSTREAM_KEY` (model, daily spending cap $10, 60 messages a person a day, docs it refreshes from) | | `ABUSE_INBOX` | Where reports from inside the app are emailed (default abuse@casama.ai); they also show in Admin console > Reports | | `ACCOUNT_EMAILS`, `EMAIL_POSTAL_ADDRESS` | Emails about plans and purchases (trial ending, payment failed, plan ended, credits low) and a short welcome series. Welcome and tips emails go out only when `EMAIL_POSTAL_ADDRESS` is set, and each has a one-click unsubscribe | ## Casama Link Casama Link connects your server to a Casama Cloud workspace. See the [Casama Link overview](/guide/casama-link). | Name | Default | What it does | | ------------------- | --------- | ---------------------------------------------------------------------------- | | `CASAMA_CLOUD_URL` | (empty) | Casama Cloud's address: `https://api.casama.ai`. | | `CASAMA_CLOUD_KEY` | (empty) | The server's Casama Link key (`kcc_...`). Empty: Casama Link is off. | With both set: - notifications go through Casama Cloud when the key can send them and `FCM_SERVICE_ACCOUNT` is empty; - the `casama-cloud` computer provider is available, if the key has the `computers` scope; - a workspace can add an OpenRouter model key whose base URL is `/link/v1/models` and whose key is the Casama Link key, if the key has the `models` scope. See [Cloud computers and credits](/self-hosting/casama-link-cloud). **Remote access.** `casama selfhost remote on` (or **Use on Your Phone** in the desktop app) writes the settings below along with the two above, and changes the address and sign-up settings. Don't set these by hand; see [What gets set](/self-hosting/remote-access#what-gets-set). | Name | Default | What it does | | ------------------------ | --------- | ----------------------------------------------------------------------- | | `CASAMA_REMOTE_ACCESS` | `off` | `on`: the server keeps a public address through Casama Link, the `connector` container runs (Compose profile `link`) and the `turn` container forwards to Casama Cloud's relay. | | `CASAMA_INSTANCE_ID` | (empty) | This server's id at Casama Cloud. The same id gets the same address. | | `CASAMA_LOCAL_URL` | (empty) | The address on the server's own computer, which its own app keeps using. | | `SIGNUP_INVITED_ONLY` | (empty) | `true`: only an email address with a pending workspace invite can make an account. Needs the sign-up hook. | | `CASAMA_LINK_RELAY_UPSTREAM` | `turn.cloudflare.com:3478` | Where the `turn` container forwards bots' computers for live view away from the computer. It must match Casama Cloud's relay. | Compose also sets `CASAMA_LINK_TOKEN_FILE` (`/link/token`, where the API keeps the connector's secret on the `link` volume) and `CONNECTOR_URL` (`http://connector:2000`, the connector's readiness check) for the API. ## Telemetry and observability | Name | Default | What it does | | ------------------------------ | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `TELEMETRY` | `off` | `on` sends anonymous counts once a week (see below). | | `TELEMETRY_URL` | `https://telemetry.casama.ai/v1/ping` | Where telemetry goes. | | `ERROR_REPORTING` | `auto` | `auto` (Sentry if `SENTRY_DSN` is set, else PostHog if `POSTHOG_API_KEY` is set, else nothing), `sentry`, `posthog` or `none`. | | `SENTRY_DSN` | (empty) | A Sentry-protocol DSN: sentry.io, self-hosted Sentry or GlitchTip. | | `POSTHOG_API_KEY` | (empty) | PostHog project key for error reports (and for product analytics when `PRODUCT_ANALYTICS=on`). | | `PRODUCT_ANALYTICS` | `off` | `on` sends product events and daily summaries to your PostHog project (Casama Cloud turns it on). Needs `POSTHOG_API_KEY`. People and workspaces that opted out are skipped. | | `ANALYTICS_ENVIRONMENT` | (`NODE_ENV`) | The `environment` tag on analytics and error events: `production`, `staging` or `development`. | | `POSTHOG_PERSONAL_API_KEY` | (empty) | Optional. A PostHog personal API key with person write scope: when an account is purged, its PostHog person and events are deleted too. | | `POSTHOG_PROJECT_ID` | (empty) | The PostHog project the key above belongs to. | | `POSTHOG_APP_HOST` | `https://us.posthog.com` | PostHog's app address for person deletion (your region or self-hosted address). | | `POSTHOG_HOST` | `https://us.i.posthog.com` | PostHog's ingest address, for another region or a self-hosted PostHog. | | `LOG_LEVEL` | `info` | The API and worker's log detail: `debug`, `info`, `warn` or `error`. | | `OTEL_EXPORTER_OTLP_ENDPOINT` | (empty) | Send traces to an OpenTelemetry collector. | | `LANGFUSE_BASE_URL` | (empty) | Langfuse address. With all three Langfuse settings, runs send LLM traces (workspaces can opt out). | | `LANGFUSE_PUBLIC_KEY` | (empty) | Langfuse public key. | | `LANGFUSE_SECRET_KEY` | (empty) | Langfuse secret key. | | `METRICS_TOKEN` | Generated | Bearer token for Prometheus metrics at `/metrics`. Without it, `/metrics` is off in production. | **Telemetry** is off unless you turn it on. With `TELEMETRY=on`, the worker sends once a week a random instance id, the Casama version and two numbers: bots and users active in the last 7 days. Nothing else: no names, emails, content, keys or addresses. **Error reports** are scrubbed before they leave: request bodies, headers, cookies and users are dropped, and secret-looking values and emails are redacted. ## Backups and alerts These are read by the optional `backup` and `monitoring` profiles, not by the server. They're explained on Operations. | Name | What it does | | --- | --- | | `CASAMA_BACKUPS` | `on` once you installed with `--backups`, so re-running the installer keeps the `backup` profile. | | `BACKUP_*` | Where and when the `backup` container uploads. See [Off-site backups](/self-hosting/operations#off-site-backups). | | `ALERT_EMAIL` | Where Alertmanager emails alerts, through the SMTP settings above. See [Alerts](/self-hosting/operations#alerts). | | `CASAMA_BACKUP_RECIPIENTS` | Read by `casama selfhost backup` from your shell, not from `.env`: age recipients for `--encrypt`. | ## Secret store Bots' named secrets live in Supabase Vault in your database by default. A workspace admin can keep them in Infisical instead, under workspace settings → **Where secrets are kept**, with a machine identity's client id and secret. There's no server setting for it. Casama's other credentials (model keys, connection tokens) stay in Vault either way. ## Encryption keys Encryption at rest seals message content, run events, memories, summaries, ticket text, pages and knowledge in Postgres. It's off by default and turned on per workspace by its owners, once the server has a key. | Name | Default | What it does | | ---------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------- | | `CONTENT_ENCRYPTION_KEY` | (generated) | The server key that wraps workspace keys: 32 bytes, base64. `install.sh` makes one unless KMS is set; back it up. | | `CONTENT_ENCRYPTION_KEY_PREVIOUS` | (empty) | Older keys during a rotation, comma-separated. | | `CONTENT_KMS_KEY_ID` | (empty) | Use AWS KMS instead: the key's id or ARN. | | `CONTENT_KMS_REGION` | (empty) | The KMS key's region. | | `AWS_ACCESS_KEY_ID` | (empty) | AWS credentials for KMS. | | `AWS_SECRET_ACCESS_KEY` | (empty) | AWS credentials for KMS. | | `AWS_SESSION_TOKEN` | (empty) | Optional session token for temporary credentials. | | `HEALTH_REQUIRES_ENCRYPTION` | `auto` (off) | `on` stores health data only for workspaces with encryption at rest on. | ::: danger Back up the key Without the key, encrypted content can't be read. Keep a copy somewhere other than the server. ::: **Rotate the server key:** 1. Generate a new key with `openssl rand -base64 32`. 2. Move the current value to `CONTENT_ENCRYPTION_KEY_PREVIOUS` and put the new key in `CONTENT_ENCRYPTION_KEY`. 3. Run `casama selfhost up`. 4. Wait at least an hour. The worker's hourly maintenance rewraps every workspace key that still uses the old server key. Owners can also rotate their workspace right away under workspace settings. 5. Remove `CONTENT_ENCRYPTION_KEY_PREVIOUS` and run `casama selfhost up` again. Rotation rewraps workspace keys and people's About you keys; it doesn't rewrite rows. Search can't look inside sealed text: memory and knowledge search use embeddings only, which stay unencrypted. **If the database leaked:** rotating the server key isn't enough, because a copy of the database plus the old server key still opens the old data keys. Replace the data keys as well: 1. Rotate the server key as above. 2. As the instance owner, call `POST /v1/admin/encryption/replace-keys`. It replaces every workspace's data key and every person's About you key. A workspace owner can do the same for one workspace with `POST /v1/orgs/{id}/encryption/replace-key`. 3. The worker re-encrypts every row onto the new keys in the background, 500 rows per column a minute. Rows are decrypted and encrypted again in the server, never in Postgres, and keep reading normally the whole time. The workspace's encryption status shows `rekeying: true` until it's done. 4. An old key is deleted 15 minutes after its last row moves, once nothing anywhere in the database still holds a value encrypted with it. Content in the leaked copy stays readable to whoever has it; replacing keys protects everything from then on. ## Audit forwarding and enterprise features | Name | Default | What it does | | -------------------- | --------- | ------------------------------------------------------------------------------------------------ | | `CASAMA_LICENSE_KEY` | (empty) | A Casama Enterprise license key. Unlocks SAML SSO, audit log export and audit-log forwarding. | Everything outside the `ee/` folder works without a license. See [Audit-log forwarding](/self-hosting/operations#audit-log-forwarding). ## Privacy and retention | Name | Default | What it does | | ------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------ | | `ACCOUNT_DELETION_GRACE_DAYS` | `7` | Days between an account deletion request and the purge (0 to 30). | Deleted accounts are purged with the workspaces they solely own and their computer snapshots. Run events are kept for each workspace's retention setting (default 180 days). See [Privacy](/guide/privacy). ## Advanced settings The server and supervisor read these, but the bundled compose file doesn't pass them through. On Helm, set them with `extraEnv`; on a platform, as environment variables. With Compose, add them to the service's `environment:` in `infra/compose/docker-compose.yml`. The API and worker share the `x-casama` block at the top: ```yaml x-casama: &casama # ... environment: &casama-env # ... EMBEDDINGS: ${EMBEDDINGS:-auto} ``` Then set the value in `.env` and run `casama selfhost up`. Keep your edit when you upgrade: `git pull` refuses to overwrite a changed file, so commit it on a local branch or re-apply it. **API and worker:** | Name | Default | What it does | | -------------------------- | ------------------- | --------------------------------------------------------------------------------------------- | | `LOCAL_COMPUTERS` | `true` | People's own machines as bot computers through the desktop companion. | | `EMBEDDINGS` | `auto` | `auto` embeds memories with the workspace's OpenAI key when it has one; `none` uses full-text search only. | | `AI_GATEWAY_PROVIDERS` | (all) | Limit AI Gateway to some providers, comma-separated: `openai`, `anthropic`, `google`, `xai`, `openrouter`. | | `TRACE_URL_TEMPLATE` | (empty) | A trace viewer link containing `{trace_id}`, shown on run timelines. | | `TURN_TLS_PORT` | (empty) | Also offer a `turns:` address on this port. The bundled relay doesn't serve TLS. | | `CONTENT_KMS_ENDPOINT` | (AWS's) | A custom KMS endpoint, for example a VPC endpoint. | | `MODEL_PRICES_URL` | OpenRouter's model list | Where the worker reads model prices once a day, for the cost shown on runs and budgets. `off` uses only the built-in table. | | `GEMINI_LIVE_MODEL` | `gemini-3.8-live` | The Gemini Live model for live calls (used when a workspace has a Google AI key). | | `PDF_CHROMIUM_PATH` | (empty: PDF export off) | A Chromium binary in the API's own image, used when `PDF_RENDERER_URL` is empty. Chromium can't keep its sandbox in a normal container, so prefer [the sidecar](#page-pdfs). | | `COMPOSIO_WEBHOOK_SECRET` | (empty) | The signing secret of a Composio webhook subscription to `/hooks/composio`. With it, new mail and calendar changes in Composio-connected apps start a bot's check-in scan early; without it, scans keep their schedule. | | `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`, `SLACK_SIGNING_SECRET` | (empty: paste a bot token) | A Slack app of your own for one-click install of bots into Slack workspaces. Without them, people connect Slack with a bot token. See [Chat apps](/guide/chat-apps). | **Supervisor:** | Name | Default | What it does | | ---------------------- | --------------- | ----------------------------------------------------------------------------------------- | | `COMPUTER_CPUS` | `1` | CPUs for each new computer. | | `DEFAULT_PROVIDER` | `docker` | The provider for computers that ask for the default. See [Computer providers](/self-hosting/computers). | | `STREAM_IDLE_STOP_MS` | `60000` | How long the live view streamer keeps running after the last viewer leaves. | | `OBJECT_STORE`, `S3_*` | Filesystem | See [Object storage](#object-storage). | | Provider settings | (none) | See [Computer providers](/self-hosting/computers). | **Egress proxy:** | Name | Default | What it does | | ----------------------- | --------- | -------------------------------------------------------------------------------- | | `EGRESS_BLOCKED_CIDRS` | (empty) | More address ranges to block for computers, on top of the built-in private ranges. | **For tests and development only.** The server also reads names that point it at fakes or record model calls. Never set them on a real server: `APP_CHECK_JWKS_URL`, `APP_CHECK_ISSUER_BASE`, `APNS_URL`, `CASAMA_LICENSE_PUBLIC_KEY`, `CASAMA_LINK_CF_API_URL`, `CASAMA_LINK_TURN_API_URL`, `CASAMA_MAX_OUTPUT_TOKENS`, `CASAMA_MODEL_FIXTURES`, `CASAMA_MODEL_RECORD`, `CHATGPT_API_URL`, `CHATGPT_AUTH_URL`, `COMPOSIO_API_URL`, `DODO_API_URL`, `GITHUB_API_URL`, `REVENUECAT_API_URL`, `SLACK_API_BASE`, `STRIPE_API_URL`, `TREG_API_URL`, `TWILIO_API_URL` and `UNSPLASH_API_URL`. `FFMPEG_PATH`, `SKILLS_CATALOG_DIR` and the supervisor's `EGRESS_PROXY_PORT` and `NAME_PREFIX` are set inside the images or by Compose; leave them alone. ## Related - [Self-hosting](/self-hosting/) - [Operations](/self-hosting/operations) - [Computer providers](/self-hosting/computers) - [Troubleshooting](/self-hosting/troubleshooting) - [Privacy](/guide/privacy) - [Casama Link](/guide/casama-link) - [Use your server on your phone](/self-hosting/remote-access) # Self-hosting Casama runs on your own hardware. One machine with Docker runs the whole stack: Supabase (Postgres, Auth, REST and Realtime), the Casama API and worker, the sandbox supervisor and egress proxy for bot computers, the TURN relay for live view, and Caddy for HTTPS. Self-hosted Casama has no paywall and no usage limits: billing is switched off in the bundled stack. This page covers what you get, what you need, and how to install. When the server is running, see [Configuration](/self-hosting/configuration) for every setting and [Operations](/self-hosting/operations) for upgrades, backups and monitoring. ## What you get `./install.sh` starts these services from `infra/compose/docker-compose.yml` (Compose project `casama`): | Service | What it does | | --------------- | ------------------------------------------------------------------------------------------------------------ | | `caddy` | The one public address. Gets TLS certificates automatically and routes requests to the API, Supabase or the web app. | | `api` | The Casama API (port 8787 inside the stack), plus Pages on port 8790. | | `worker` | Runs bots: chats, routines, memory, connections and scheduled jobs. | | `db` | Supabase Postgres 17. Holds all data, including encrypted secrets in Supabase Vault. | | `auth` | Supabase Auth (accounts, sign-in, two-step sign-in, SAML SSO). | | `rest` | PostgREST, used by the apps for reads. | | `realtime` | Supabase Realtime, which streams chat and run updates to the apps. | | `kong` | The Supabase gateway in front of Auth, REST and Realtime. | | `migrate` | Runs once at each start. Waits for Auth and Realtime, then applies Casama's database migrations. | | `supervisor` | Creates, sleeps and wakes bot computers. The only service with access to the Docker socket. | | `egress` | The only route from computers to the internet. Blocks private, loopback and cloud metadata addresses. | | `turn` | A coturn relay for live view of desktop computers. | Optional Compose profiles add more: | Profile | Services | Turn it on with | | ------------ | ------------------------------------------ | -------------------------------------------------- | | `web` | The web app at the same address | `./install.sh --web` | | `monitoring` | Prometheus, node-exporter and Grafana | `./install.sh --monitoring` | | `search` | SearXNG, free web search for bots | `./install.sh --search` | | `backup` | Daily off-site backups | `./install.sh --backups` | | `link` | `connector`: Casama Link's tunnel, a public address with no domain | `casama selfhost remote on`, see [Use your server on your phone](/self-hosting/remote-access) | | `pdf` | Gotenberg, for **Export PDF** on pages | See [Page PDFs](/self-hosting/configuration#page-pdfs) | | `s3` | SeaweedFS, S3-compatible object storage | See [Object storage](/self-hosting/configuration#object-storage) | | `images` | Build-only services for the computer images | Used by the installer | How a request flows: ```text Apps, CLI, browser | v Caddy :80/:443 --- /v1, /hooks, /link, /oauth, /mcp, /a2a, ----> api :8787 | | /links, /telephony, /healthz, /readyz, /.well-known/... | \---- /auth/v1, /rest/v1, /realtime/v1 --------> kong ---> auth, rest, realtime | \--- everything else ------------------------> web (profile "web") Caddy :8790 ------ Pages (bots' web pages, own origin) ------> api :8790 worker ---> supervisor ---> computer containers (one private network each) |-- internet only through egress \-- live view media only through turn :3478 ``` Bot computers are Docker containers named `casama-c-`. They run as a non-root user with a read-only root filesystem, no Linux capabilities, CPU, memory and process limits, and a private network whose only way out is the egress proxy. See [Computer providers](/self-hosting/computers) for details and for running computers on E2B, Daytona, Kubernetes and others. ## Requirements | What | Minimum | | ----------- | ---------------------------------------------------------------------------------------------------------- | | OS | Linux with Docker Engine. macOS with Docker Desktop works for trials. | | Docker | Docker Engine with Docker Compose v2 (`docker compose`). Your user must be able to run `docker`. | | Tools | `git`, `bash`, `openssl` and `curl` | | CPU and RAM | 4 vCPU and 8 GB RAM for a few computers at once. Plan on about 2 GB RAM per running computer. | | Disk | 40 GB or more. The images take about 10 GB; home folders and snapshots take the rest. | | Domain | For a public server, a DNS name (for example `casama.example.com`) pointing at the machine. | The installer warns when the machine has less than about 8 GB of memory, because computers may not start reliably. ### Ports | Port | Protocol | Used for | | --------------- | --------- | --------------------------------------------------------------------- | | 80 | TCP | HTTP, and Let's Encrypt certificate checks | | 443 | TCP | HTTPS: the API, Supabase and the web app | | 3478 | UDP, TCP | TURN relay for live view | | 8790 | TCP | Pages, when you serve them on a port instead of their own domain | | 127.0.0.1:3001 | TCP | Grafana (monitoring profile), on the loopback interface only | For a public server, open 80, 443 and 3478 (UDP and TCP) in your firewall. With `--local`, nothing needs to be reachable from other machines. To use a `--local` server from your phone without a domain or open ports, see [Use your server on your phone](/self-hosting/remote-access). ### Domain and TLS With `--domain`, Caddy requests a certificate for that name the first time it starts. Before you install, make sure: - the domain's A (or AAAA) record points at the server, and - ports 80 and 443 are reachable from the internet. If another proxy already terminates TLS in front of the machine, see [Behind another proxy](/self-hosting/configuration#behind-another-proxy). ## Install 1. Clone the repository on the server: ```sh git clone https://github.com/stackwares/casama && cd casama ``` 2. Run the installer with your domain: ```sh ./install.sh --domain casama.example.com ``` For a trial on your own computer, use `./install.sh --local` instead. 3. Wait for the installer to finish. It prints the address when the API is ready: ```text Casama is running at https://casama.example.com ``` 4. Back up `infra/compose/.env` somewhere safe. It holds every key for this installation. The installer: 1. Checks that Docker, Docker Compose v2 and OpenSSL are available and that Docker is running. 2. On Linux, uses gVisor (`runsc`) for computers if Docker lists it as a runtime. 3. Generates every secret with OpenSSL and writes `infra/compose/.env` (mode 600). This includes the database passwords, the Supabase JWT secret and keys, a SAML signing key, the tokens the services use to talk to each other, and the server key for encryption at rest (`CONTENT_ENCRYPTION_KEY`, unless AWS KMS is set). Back that key up: encrypted data can't be read without it. 4. Pulls the Supabase, Caddy and other images (two at a time, with up to five retries, because public registries rate-limit anonymous pulls). 5. Builds the Casama images: `api` (shared by the worker), `supervisor`, `egress`, `turn` and the headless computer image. With `--pull`, it downloads the published images from `ghcr.io/stackwares/casama` instead. 6. Starts the stack and waits up to three minutes for `/readyz` to answer. A fresh install that builds every image from scratch takes a few minutes, plus the time to download about 3 GB of third-party images. Re-running it with images in place takes about a minute. ### Installer options | Option | What it does | | ------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `--domain ` | Public server at `https://` with automatic HTTPS. Sets `CASAMA_SITE` to the domain and the TURN host to the domain. | | `--local` | This machine only, over plain HTTP. The address is `http://localhost` (or `http://localhost:`). | | `--http-port ` | The host port for HTTP (default `80`). Mostly useful with `--local`, for example `--local --http-port 8080`. | | `--with-desktop` | Also builds the desktop computer image, needed for live view and desktop apps. Slower. | | `--monitoring` | Adds the `monitoring` profile: Prometheus, node-exporter and Grafana. | | `--web` | Adds the `web` profile: the Flutter web app at the same address. The build runs Flutter in Docker and takes a while. | | `--search` | Adds SearXNG and points the worker at it, so bots can search the web without a Brave or Tavily key. | | `--pull [tag]` | Pulls published images from `ghcr.io/stackwares/casama` instead of building them. The tag defaults to `latest`. | | `--behind-proxy` | TLS ends at a tunnel or another proxy. Needs `--domain`. Caddy listens on loopback only (`HTTP_BIND=127.0.0.1`). | | `--turn-host ` | The name or IP clients use for live view, when it differs from `--domain`. Needs UDP and TCP 3478 open to that host. | | `--admin-email ` | Comma-separated instance admin emails (`INSTANCE_ADMIN_EMAILS`). | | `--settings ` | Merges `KEY=VALUE` lines from a file into `.env`. Comments and blank lines are skipped. | | `--backups` | Adds the `backup` profile: a daily encrypted upload. See [Operations](/self-hosting/operations#off-site-backups). | | `--no-start` | Writes `.env` and builds or pulls the images, but doesn't start the stack. | | `-h`, `--help` | Prints the usage. | With neither `--domain` nor `--local`, the installer asks for a domain. An empty answer (or no terminal) means a local install. To force clean image builds, set `CASAMA_BUILD_FLAGS`, which is passed to `docker compose build`: ```sh CASAMA_BUILD_FLAGS=--no-cache ./install.sh ``` ::: warning Re-running keeps your settings When `infra/compose/.env` exists, the installer keeps it as is and only adds settings that newer releases introduced. `--domain`, `--local` and `--http-port` have no effect on a re-run. To change the address later, edit the settings in [Core and URLs](/self-hosting/configuration#core-and-urls). `--pull`, `--behind-proxy`, `--turn-host`, `--admin-email`, `--settings` and `--backups` do apply on a re-run. ::: ### `--local` versus `--domain` | | `--local` | `--domain casama.example.com` | | ------------------- | --------------------------------------- | --------------------------------------------- | | Address | `http://localhost[:port]` | `https://casama.example.com` | | TLS | None | Automatic (Let's Encrypt through Caddy) | | Who can reach it | This machine | Anyone who can reach the domain | | Sign-up allowlist | Not available (needs an https hook URL) | Available | | Live view TURN host | `localhost` | The domain | ### The same steps from the CLI The [Casama CLI](/develop/cli) wraps the installer: ```sh casama selfhost init --dir ~/casama --domain casama.example.com ``` `init` takes `--domain`, `--local`, `--http-port`, `--with-desktop` and `--monitoring`. For `--web` or `--no-start`, run `./install.sh` directly. Every `casama selfhost` command finds the checkout through `--dir`, then the `CASAMA_SELFHOST_DIR` environment variable, then the current directory. ## First sign-in and the instance owner The first account created on a new server becomes the **instance owner**. Owners get the admin console under Settings, where they can see the health of each service, manage workspaces and check for updates. 1. Open the Casama app and point it at your server (see the next section). 2. Create an account with email and password. 3. Add a model key (or a local model endpoint) and create your first bot. A new server doesn't send email, so start with a password: emailed sign-in links need [SMTP](/self-hosting/configuration#email). New accounts are confirmed automatically until you turn email confirmation on. To name the owners explicitly instead, set `INSTANCE_ADMIN_EMAILS` to a comma-separated list of emails in `infra/compose/.env`, then run `casama selfhost up`. ## Connect the apps and the CLI **In the app** (iOS, Android, macOS, Windows, Linux): 1. On the sign-in screen, tap **More options**. 2. Tap the **Server** chip, which shows the current server. 3. Enter your server's address, for example `https://casama.example.com`, and tap **Connect**. The app remembers the address. If it can't reach a server, the error screen also offers **Use a different server**. The web app (`--web`) always uses the address it's served from. **With the CLI:** ```sh casama config --api-url https://casama.example.com casama signup --email you@example.com # or: casama login --email you@example.com ``` You can also pass the address for a single command with the global `--api` option (`casama --api https://casama.example.com login --email you@example.com`) or set `CASAMA_API_URL`. ## Run a server on your own computer The desktop app on macOS and Linux (not the Mac App Store version) sets up a local server for you, one step at a time. On the sign-in screen, tap **Run on This Mac** (**Run on This Computer** on Linux): 1. **Docker.** The app looks for Docker by itself. If it's missing, **Download Docker Desktop** gets the installer for your Mac's chip; on Linux it opens Docker's install guide. If Docker is installed but closed, the app opens it. The page moves on by itself once Docker runs. 2. **Server.** Tap **Start**. The first start downloads about 10 GB and takes 5 to 10 minutes. **Show Details** shows the installer's own lines. 3. **Account.** Your name, an email and a password. No email is sent; the first account is the instance owner. 4. **AI model.** Sign in with a ChatGPT plan, or paste a model key (or a local Ollama address). You can skip this and add one later under **Settings → Model keys**. 5. **Phone.** Turn on [Casama Link](/self-hosting/remote-access), approve it in your browser with a free Casama Cloud account, and scan the code with your phone's camera. The page says **Phone connected** when the phone has signed in. You can close the setup or quit the app at any step; it opens again at the step it reached. If you skip the model or the phone, a **Finish setting up** card on the home page takes you back. On Linux, when Docker runs but your user may not use it, the page shows the command that fixes it (`sudo usermod -aG docker $USER`, then log out and back in). For the server step, the app downloads the source of the release whose images are published (the `selfhost` tag) into its support folder, and runs `install.sh --local --pull `, which pulls the published images instead of building them. The first start downloads about 10 GB of images, so it needs that much free disk. Then it waits for the server and connects to `http://localhost:8080`. If a port is taken (8080, 8443, 8790 or TURN's 3478), it picks the next free one and keeps it. Every port listens on `127.0.0.1` only, so only this computer can reach it. If a server already answers there, it connects right away. Closing the setup while it installs stops the installer; starting again picks up where it left off. Windows isn't supported yet (the installer needs bash and OpenSSL). Use WSL and `./install.sh --local`. The setup's last step connects your phone. To do it later, turn on Casama Link under **Settings → Casama Link → Use on Your Phone**. See [Use your server on your phone](/self-hosting/remote-access). ## Other ways to deploy | Method | What runs | Computers | Where to start | | --------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------- | | `install.sh` (recommended) | Everything on one Docker host | Docker on the same host, or another provider | This page | | Coolify | The same compose file, through Coolify | Docker on the Coolify server | `deploy/coolify/README.md` | | Kubernetes (Helm) | API, worker, supervisor and optionally the web app | Pods in their own namespace | [Helm chart](/self-hosting/operations#kubernetes-with-helm) | | Render, Railway, DigitalOcean App Platform | API and worker only | [Casama Link](/self-hosting/casama-link-cloud), the desktop companion, or a supervisor elsewhere | `deploy/README.md` | ### Coolify Coolify runs Docker Compose stacks with the Docker socket, so it can host the full stack. 1. On the Coolify server, run `./install.sh --no-start --domain casama.example.com` once from a checkout to generate `infra/compose/.env`. 2. In Coolify, create a Docker Compose resource from the repository with the compose file `infra/compose/docker-compose.yml`, and paste the variables from `infra/compose/.env`. 3. Let Coolify's proxy route your domain to the `caddy` service on port 80 and set `CASAMA_SITE=:80`, because Coolify terminates TLS. 4. Build the computer image once on the server: ```sh docker compose -f infra/compose/docker-compose.yml --profile images build computer-headless ``` ### Render, Railway and DigitalOcean App Platform These platforms have no Docker socket, so they run only the API and worker, against a Supabase project (Supabase Cloud or your own Supabase) for Postgres and Auth. Bots get computers from [Casama Link](/self-hosting/casama-link-cloud), from people's own machines through the [desktop companion](/guide/companion), or from a supervisor you run elsewhere (`SUPERVISOR_URL` and `SUPERVISOR_TOKEN`). | Platform | File | Notes | | ------------------------- | ----------------------------- | -------------------------------------------------------- | | Render | `deploy/render/render.yaml` | Blueprint: an API web service and a worker | | Railway | `deploy/railway/railway.json` | Two services from the same repository; set `MODE` on each | | DigitalOcean App Platform | `deploy/digitalocean/app.yaml`| `doctl apps create --spec deploy/digitalocean/app.yaml` | Before the first start, apply the migrations to the Supabase database from a checkout: ```sh supabase db push --db-url "$DATABASE_URL" ``` Every platform needs `DATABASE_URL`, `SUPABASE_URL`, `SUPABASE_ANON_KEY`, `SUPABASE_JWT_SECRET` (from the Supabase project settings), `INTERNAL_TOKEN` (32 or more random characters) and `PUBLIC_APP_URL`. On Railway, the API service sets `MODE=api` and `PORT=8787`; the worker sets `MODE=worker` and `API_INTERNAL_URL` to the API's private address on port 8787. ## Production hardening ### Use gVisor for computers gVisor (`runsc`) gives each computer its own kernel boundary. Install it on the Linux host and register it with Docker (see the gVisor documentation), then check that Docker lists it: ```sh docker info | grep -i runsc ``` A first install picks it up automatically. On an existing install, set it yourself: 1. In `infra/compose/.env`, set `SANDBOX_RUNTIME=runsc`. 2. Run `casama selfhost up`. New computers start under gVisor. Running computers keep their runtime until they sleep and wake. Without gVisor, computers use Docker's default runtime (runc) together with the other controls: a non-root user, a read-only root filesystem, no capabilities, `no-new-privileges`, per-computer networks, the egress proxy and resource limits. ### Run computers on a second host For public servers, keep untrusted code and the Docker socket off the machine that holds your data. Run the supervisor, egress proxy and TURN relay on a second host, and point the API and worker at it over a private network or WireGuard. See [Run computers on a separate host](/self-hosting/operations#run-computers-on-a-separate-host). ### Firewall - Allow inbound 80/tcp, 443/tcp and 3478 (UDP and TCP) only. Allow 8790/tcp only if you serve Pages on a port. - Keep Grafana on the loopback interface and reach it through an SSH tunnel. - Never expose the supervisor (8788), the API's internal port (8787) or Postgres to the internet. - Docker's published ports bypass some host firewalls (ufw, for example). Check from another machine that only the ports above answer. ### Other checks - Serve Pages from their own domain, so bots' pages never share an origin with Casama. See [Pages](/self-hosting/configuration#core-and-urls). - Turn on email confirmation and set up [SMTP](/self-hosting/configuration#email). - Restrict who can sign up with `DISABLE_SIGNUP` or the [sign-up allowlist](/self-hosting/configuration#sign-ups-and-allowlists). - Set up [encrypted backups](/self-hosting/operations#back-up-your-server) and copy them off the machine. - Consider [encryption at rest](/self-hosting/configuration#encryption-keys) for workspace content. - Keep `COMPUTER_HOST_MEMORY_GB` at a number the machine can hold. See [Server capacity](/self-hosting/operations#server-capacity). ## Related - [Configuration](/self-hosting/configuration) - [Operations](/self-hosting/operations) - [Computer providers](/self-hosting/computers) - [Use your server on your phone](/self-hosting/remote-access) - [Troubleshooting](/self-hosting/troubleshooting) - [Quick start](/quick-start) - [CLI](/develop/cli) # Operating your server This page covers day-to-day work on a running Casama server: upgrades, backups, monitoring, logs, audit-log forwarding and scaling, plus the Kubernetes Helm chart. The commands use the [Casama CLI](/develop/cli), which wraps `install.sh` and `docker compose` for your checkout. ## Everyday commands Run these from the checkout, or pass `--dir ~/casama` (or set `CASAMA_SELFHOST_DIR`). | Task | Command | | ------------- | ----------------------------------------------------------------------------- | | Status | `casama selfhost status` | | Logs | `casama selfhost logs -f` (api and worker), or name services: `logs migrate supervisor` | | Start | `casama selfhost up` | | Stop | `casama selfhost down` (data is kept) | | Upgrade | `casama selfhost upgrade` | | Back up | `casama selfhost backup --out /backups` | | Restore | `casama selfhost restore /backups/` | | Phone access | `casama selfhost remote status` (see [Use your server on your phone](/self-hosting/remote-access)) | Each one maps to plain Compose, if you prefer: ```sh docker compose -f infra/compose/docker-compose.yml --env-file infra/compose/.env ps ``` `casama selfhost down` stops the stack but leaves running bot computers alone, because the supervisor creates them outside Compose. After the next `up`, the worker archives and stops any that sat idle for 5 minutes. ::: danger Don't delete the volumes `docker compose down -v` deletes the database, computer archives and certificates. The CLI never passes `-v`. ::: ## Upgrade 1. Back up first: ```sh casama selfhost backup --out /backups ``` 2. Upgrade: ```sh casama selfhost upgrade ``` This runs `git pull --ff-only` in the checkout, then `./install.sh`. The installer keeps `infra/compose/.env`, adds any settings the new release introduced, rebuilds the images (or, if you installed with `--pull`, pulls the published ones for `CASAMA_VERSION`), applies new database migrations and restarts the services that changed. A server pinned to one image tag stays on it: run `./install.sh --pull` (or `--pull `) to move it. If you set `CASAMA_SERVER_IMAGE`, the API and worker stay on that image until you change or empty it. 3. Check the result with `casama selfhost status` and the admin console. `casama selfhost upgrade` runs the installer with no options. If you installed with `--with-desktop`, `--monitoring`, `--web` or `--search`, upgrade by hand instead so those parts are updated too: ```sh git pull --ff-only ./install.sh --with-desktop --monitoring --web --search ``` The installer doesn't rebuild an existing web image. After an upgrade with `--web`, rebuild it: ```sh docker compose -f infra/compose/docker-compose.yml --env-file infra/compose/.env --profile web build web docker compose -f infra/compose/docker-compose.yml --env-file infra/compose/.env --profile web up -d ``` Notes: - Migrations run automatically in the one-shot `migrate` service at every start, once each, in order. They're tracked in `public.casama_migrations`. - Running computers keep the image they started with. Sleeping archives a computer's home folder and removes its container, and waking makes a fresh container from the current image, so each computer picks up the new image, with its files, sign-ins and settings, the next time it sleeps and wakes or restarts. That is also how the tools inside (agent-browser, Playwright and the others) stay current: they're pinned in the images and arrive with a new release, never by updates inside running computers. A computer that never sits idle for 5 minutes keeps the old image until it restarts. Warm pool computers on an old image are replaced within a minute. - Runs survive restarts. Runs waiting for an approval, a key or a takeover pick up again after the upgrade, and time spent waiting doesn't count toward a run's 30-minute limit. A run whose recorded steps no longer match the new code ends with "Casama was updated while this was waiting". An action that was in the middle of running when the worker stopped isn't repeated blindly: lookups and low-risk tools run again, and anything else tells the bot that Casama restarted while it ran, so it checks first. A run still marked as working two minutes after its workflow ended is marked failed. - If `git pull --ff-only` fails, you have local changes to tracked files (for example an edited `docker-compose.yml`). Commit them on a local branch or stash them, then try again. - With remote access on, the upgrade keeps the `connector` running: the installer reads `CASAMA_REMOTE_ACCESS` from `.env`. ### Published images `./install.sh --pull [tag]` and the desktop app's **Run on This Mac** setup use published images instead of building them. They're at `ghcr.io/stackwares/casama/`, for `linux/amd64` and `linux/arm64`: | Image | What it is | | --- | --- | | `server` | The API and the worker | | `supervisor` | The sandbox supervisor | | `egress-proxy` | The computers' only way to the internet | | `turn` | The live view relay | | `connector` | Casama Link's connector (remote access) | | `backup` | The scheduled backup container | | `computer-headless`, `computer-desktop` | Bot computers | Each release is tagged with its short commit id, plus `edge` and `latest`. The web app isn't published: `--web` builds it on your machine. The git tag `selfhost` marks the commit whose images are `latest`, which is what the desktop app downloads. ## Back up your server ```sh casama selfhost backup --out /backups ``` Each run writes a timestamped folder, for example `/backups/2026-11-11T09-30-00`, with: | File | Contents | | ----------------- | -------------------------------------------------------------- | | `postgres.dump` | The whole database (`pg_dump` custom format) | | `objects.tar.gz` | Computer archives and checkpoints from the `objects` volume | | `library.tar.gz` | The Library's kept files and the pictures, videos and sounds in chats, from the `library` volume (left out when it's empty) | | `env` | A copy of `infra/compose/.env`, with every key | | `vault-key` | The database's Vault root key. The saved secrets in the dump (model keys, app sign-ins) can't be read on another machine without it | `--out` defaults to `casama-backups` in the current directory. With S3 object storage, the archives only cover the local volumes, so back up the bucket with your provider's tools. `library.tar.gz` is the same file the scheduled [off-site backup](#off-site-backups) writes, so `casama selfhost restore` takes either. Backups made before it was included restore as before, without the Library's files. ### Encrypt backups and keep a set number Backups hold every key for your server, so encrypt them before they leave the machine. Casama uses [age](https://age-encryption.org). 1. Install age (`apt install age` or `brew install age`). 2. On another machine, create a key pair: ```sh age-keygen -o backup.key ``` It prints the public key (`age1...`). Keep `backup.key` off the server. 3. Back up with encryption and retention: ```sh casama selfhost backup --out /backups --encrypt --recipient age1... --keep 14 --keep-days 30 ``` | Option | What it does | | ---------------------- | -------------------------------------------------------------------------------------------------- | | `--out ` | Where backup folders go (default `casama-backups`). | | `--encrypt` | Encrypts each file with age (`postgres.dump.age` and so on) and removes the plaintext. | | `--recipient ` | An age public key (`age1...`) or SSH public key to encrypt to. Repeat for more. | | `--keep ` | Keep only the newest n backups in `--out`. | | `--keep-days ` | Remove backups older than n days. With `--keep` too, a backup goes only when it's outside both. | `CASAMA_BACKUP_RECIPIENTS` (comma-separated) can stand in for `--recipient`. Retention only removes the timestamped folders the CLI itself wrote. ### Schedule backups Run the backup daily with cron and copy the folder off the machine. For example, in the crontab of a user who can run Docker: ```text 30 3 * * * casama selfhost backup --dir /opt/casama --out /backups --encrypt --recipient age1... --keep 14 >> /var/log/casama-backup.log 2>&1 ``` Then sync `/backups` to other storage with your usual tool. ### Off-site backups `./install.sh --backups` starts a `backup` container that does this every day, without cron. It dumps the database, the Library's files, optionally the computer archives, encrypts each file with age, and uploads the folder to any S3-compatible bucket (Cloudflare R2, AWS S3, Backblaze B2, MinIO). The `.env` and the Vault key (`vault-key`) are included only when `BACKUP_AGE_RECIPIENTS` is set, so set it: without the Vault key a restore on another machine loses every saved secret. If encryption fails, the folder is deleted and nothing is uploaded. | Setting | What it does | | --- | --- | | `BACKUP_S3_BUCKET` | Bucket name. Empty keeps backups only in the local `backups` volume. | | `BACKUP_S3_ENDPOINT` | `https://.r2.cloudflarestorage.com` for R2. Empty for AWS. | | `BACKUP_S3_REGION` | `auto` for R2. The bucket's region for AWS. | | `BACKUP_S3_ACCESS_KEY_ID`, `BACKUP_S3_SECRET_ACCESS_KEY` | The bucket's key. | | `BACKUP_S3_PREFIX` | Folder in the bucket (default `casama`). | | `BACKUP_TIME` | `HH:MM` in UTC (default `03:30`). | | `BACKUP_KEEP_DAYS` | Delete backups older than this many days (default `30`). | | `BACKUP_AGE_RECIPIENTS` | Comma-separated age public keys (`age1…`) or SSH public keys. | | `BACKUP_OBJECTS` | `true` to include computer archives. | | `BACKUP_PING_URL` | Called after each success. `/fail` is appended after a failure. | ```sh docker compose -f infra/compose/docker-compose.yml --env-file infra/compose/.env \ --profile backup run --rm backup now docker compose -f infra/compose/docker-compose.yml --env-file infra/compose/.env \ --profile backup run --rm backup list ``` To read one back: download the folder, `age -d -i backup.key -o postgres.dump postgres.dump.age`, then `pg_restore --list postgres.dump`. Restore the database with [Restore](#restore) after decrypting. Casama Cloud's settings are in `deploy/casama-cloud/settings.env`. ### Restore `restore` replaces the current data with the backup. ```sh casama selfhost restore /backups/2026-11-11T09-30-00 # encrypted backup: casama selfhost restore /backups/2026-11-11T09-30-00 --identity backup.key ``` It stops the API and worker, puts the backup's Vault key in place and restarts the database to load it, restores the database with `pg_restore --clean` as the database's admin user (so sign-in accounts and saved secrets come back with their owners), unpacks the computer archives into the `objects` volume and the Library's files (`library.tar.gz`, from either kind of backup) into the `library` volume, and starts the stack again. If the server's [encryption keys](/self-hosting/configuration#encryption-keys) changed since the backup, put the backup's `CONTENT_ENCRYPTION_KEY` back (or keep it in `CONTENT_ENCRYPTION_KEY_PREVIOUS`), or sealed content stays unreadable. A backup made before `vault-key` was added has no key. It restores fine on the machine it came from; on a new machine, saved secrets (model keys, app sign-ins) have to be entered again. `restore` doesn't touch `infra/compose/.env`. To restore onto a new machine: 1. Clone the same release of the repository. 2. Copy the backup's `env` file to `infra/compose/.env` (decrypt it first with `age -d -i backup.key -o infra/compose/.env env.age` if it's encrypted). 3. Run `./install.sh`. It keeps that `.env`, so the new stack uses the same keys. 4. Run `casama selfhost restore `. ::: warning Test your restores The backup holds the database, computer archives and `.env`. It doesn't include the other Docker volumes (for example `db-config`, which holds the database's own configuration, or Caddy's certificates). Restore onto a spare machine now and then, and check that you can sign in, that bots answer with their saved model keys, and that a computer wakes with its files. ::: ## Monitoring The `monitoring` profile adds Prometheus, node-exporter and a Grafana dashboard. 1. Turn it on: ```sh ./install.sh --monitoring ``` Or add the profile to a running stack: ```sh docker compose -f infra/compose/docker-compose.yml --env-file infra/compose/.env --profile monitoring up -d ``` 2. Grafana listens on `127.0.0.1:3001` on the server. From your computer, open an SSH tunnel: ```sh ssh -L 3001:127.0.0.1:3001 you@casama.example.com ``` 3. Open `http://localhost:3001` and sign in as `admin` with `GRAFANA_ADMIN_PASSWORD` from `infra/compose/.env`. The **Casama overview** dashboard is already provisioned. Prometheus keeps 30 days of data and isn't published on the host. It scrapes the API's `/metrics` inside the stack with `METRICS_TOKEN`, and node-exporter for host metrics. The config is in `infra/monitoring/prometheus.yml`. ### Metrics The API serves Prometheus metrics at `/metrics` with a bearer token (`METRICS_TOKEN`). Caddy doesn't route `/metrics`, so it's only reachable inside the stack. The values are computed from Postgres on each scrape. | Metric | What it measures | | --------------------------------------- | ------------------------------------------------------- | | `casama_runs_15m` | Runs created in the last 15 minutes, by status | | `casama_run_failure_ratio_15m` | Failed runs out of finished runs, last 15 minutes | | `casama_time_to_first_token_seconds` | Run start to first model token, p50 and p95, last hour | | `casama_computer_start_seconds` | Computer start or wake time, p50 and p95, last hour | | `casama_computers` | Computers by state | | `casama_cost_per_run_usd` | Average cost of completed runs, last hour | | `casama_queue_depth` | Queued and running workflows, by queue | | `casama_http_requests_total` | API responses by status | | `casama_http_request_seconds_sum`, `_count` | Total API response time and responses timed | ### Alerts `infra/monitoring/alerts.yml` defines these rules: | Alert | Fires when | Severity | | ------------------------------ | ------------------------------------------------------------------ | -------- | | `CasamaRunFailuresHigh` | More than 5% of runs failed in 15 minutes (at least 20 finished), for 5 minutes | page | | `CasamaSandboxMemoryHigh` | A host is above 85% memory for 10 minutes | page | | `CasamaTimeToFirstTokenSlow` | p95 time to first token is above 3 seconds for 15 minutes | warn | | `CasamaQueueBacklog` | More than 200 runs are waiting, for 10 minutes | warn | | `CasamaApiDown` | Prometheus can't scrape the API for 2 minutes | page | | `CasamaDiskFilling` | A disk is over 85% full for 15 minutes | page | The profile includes Alertmanager. Set `ALERT_EMAIL` in `infra/compose/.env` and alerts are emailed there through the same SMTP server as sign-in emails (`SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`, sent from `SMTP_ADMIN_EMAIL`). Without `ALERT_EMAIL`, alerts show only in Prometheus. ### Limits that keep the server up - **Bot computers' memory:** the installer sets `COMPUTER_HOST_MEMORY_GB` to the machine's memory less 4 GB (at least 2 GB), when it isn't set yet. Past it, a computer waits to start with `capacity_full` instead of starving the database. Change the number in `infra/compose/.env`; a computer without a recorded size counts as `COMPUTER_MEMORY_MB` (2,048 by default). See [Server capacity](#server-capacity). - **Logs:** every Casama container keeps at most 5 log files of 20 MB, and each bot computer 3 of 10 MB. - **The worker's health:** the worker container is unhealthy when its minute tick hasn't run for 3 minutes; `casama selfhost status` shows it. - **Disk per computer:** not capped on ordinary Docker storage. A hard limit needs XFS project quotas on the sandbox host; `CasamaDiskFilling` warns before the disk is full. ### Server capacity The worker samples the host every 5 minutes: free memory, load, disk use, and the memory the bot computers that are running take. Samples are kept for 90 days. Under **Settings → Admin console**, the **Server capacity** card shows computers' memory against `COMPUTER_HOST_MEMORY_GB`, free memory, disk and load, the daily peak over 30 days, computer starts refused, and how many weeks until it's full at the current trend. Without a budget it says "Set COMPUTER_HOST_MEMORY_GB on the server to measure computers against its room." The instance owners (`INSTANCE_ADMIN_EMAILS`, else the first account) get alerts in the app's inbox, by push and by email (Resend or SMTP), each kind at most once a day: | Alert | When | | -------------- | ----------------------------------------------------------------------- | | Early warning | Computers' daily peak was over 60% of the budget on 3 of the last 7 days | | Full | A computer start was refused because the budget was full | | Low memory | Free host memory under 1.5 GB for 10 minutes | | Disk | The disk is over 80% full | These alerts need no monitoring profile. Push for them needs the server's own `FCM_SERVICE_ACCOUNT`; on a server linked with Casama Link but without one, they reach the inbox and email only. ### The admin console Instance owners see a health summary under **Settings → Admin console**: the database, the worker, the sandbox supervisor, the live view relay, personal computers, email, error reporting, the enterprise license and telemetry, each with whether it's configured and healthy, plus the [Server capacity](#server-capacity) card. ### Remote app settings Under Settings → admin console → **App settings**, the instance owner can change every installed app without a release. The settings are JSON: ```json { "min_versions": { "ios": "0.9.0", "android": "0.9.0" }, "update_urls": { "ios": "https://apps.apple.com/app/…", "android": "https://play.google.com/store/apps/details?id=…" }, "maintenance": null, "announcements": [ { "id": "spring-update", "title": "New: routine ideas", "body": "Start a routine from an idea.", "level": "info", "url": "https://casama.ai/changelog", "ends_at": "2026-12-01T00:00:00Z", "platforms": ["ios", "android"] } ], "flags": { "new_home": true } } ``` - `min_versions`: apps older than this on a platform show **Time to update Casama** instead of the app, with an **Update** button to `update_urls` for that platform. Platforms: `ios`, `android`, `macos`, `windows`, `linux`, `web`. - `maintenance`: `{ "message": "Back at 3 pm UTC." }` covers every app with that message until it's `null` again. - `announcements`: up to 10 banners. Each has an `id`, a `title`, an optional `body`, `url`, `level` (`info` or `warning`), a time window, `platforms` and `min_version` / `max_version`. A dismissed banner stays dismissed on that device. - `flags`: on/off switches the app reads by name. Apps read the settings without signing in (`GET /v1/app-config`), every half hour and whenever they come back to the front, and keep the last copy for when they're offline. ### Health endpoints | Endpoint | What it checks | | ----------- | ------------------------------------------------------------------ | | `/healthz` | The API process answers. Always `200` while it's up. | | `/readyz` | The API can reach the database. `503` with `"degraded"` otherwise. | The supervisor has its own `/healthz` on port 8788, inside the stack. ## Logs ```sh casama selfhost logs -f # api and worker casama selfhost logs migrate # database migrations casama selfhost logs -f supervisor egress # computers and their internet access casama selfhost logs auth # Supabase Auth: sign-in and email ``` `logs` shows the last 200 lines of each service; `-f` follows. The API, worker, supervisor and egress proxy write JSON lines, one event each. The egress proxy logs each outbound connection a computer makes. To see bot computers, which run outside Compose: ```sh docker ps --filter name=casama-c- ``` Set the API and worker's detail with `LOG_LEVEL` (see [Telemetry and observability](/self-hosting/configuration#telemetry-and-observability)). For run-level traces, use Langfuse or an OpenTelemetry collector (see [Telemetry and observability](/self-hosting/configuration#telemetry-and-observability)). ## Audit-log forwarding Audit-log forwarding streams each workspace's audit log to your own systems. It's an enterprise feature: it needs a `CASAMA_LICENSE_KEY` that includes `audit_forwarding`. Without one, the endpoints answer `402`. Workspace owners and admins manage forwarders through the API at `/v1/orgs/{id}/audit-forwarders` (`GET` to list, `POST` to add, `DELETE /{forwarder_id}` to remove). Each forwarder sends to one destination: | `kind` | `config` | `secret` | | --------- | ---------------------------------------------------------------- | ---------------------------------------------------------------- | | `webhook` | `url` | Required: the signing secret | | `otlp` | `url` (Casama posts to `/v1/logs`) | Optional: JSON of extra headers, for example an auth token | | `s3` | `bucket`; optional `endpoint`, `region` (default `us-east-1`), `prefix` (default `casama-audit`) | Required: `{"access_key_id":"...","secret_access_key":"..."}` | For example, a signed webhook: ```sh curl -X POST https://casama.example.com/v1/orgs/$ORG_ID/audit-forwarders \ -H "authorization: Bearer $TOKEN" -H "content-type: application/json" \ -d '{"kind":"webhook","config":{"url":"https://siem.example.com/casama"},"secret":"a-long-random-secret"}' ``` `$TOKEN` is a signed-in admin's access token (see [API](/develop/api)). Add `"from":"start"` to send the whole history instead of starting from now. How delivery works: - The worker runs a pass every minute and sends new rows in order, in batches of up to 500. - **Webhook:** JSON `{forwarder_id, events}` with an `X-Casama-Signature: t=,v1=` header, the HMAC-SHA256 of `.` with your secret. - **OTLP:** each row becomes a log record under `service.name=casama`, scope `casama.audit`. - **S3:** one JSON Lines object per batch at `//YYYY/MM/DD/-.jsonl`, path-style, so AWS S3, R2 and MinIO work. - Delivery is at least once. A failed batch stays put (the forwarder's `last_error` says why) and goes again on the next pass. Secrets are stored in Supabase Vault. ## Scaling **Worker concurrency.** `RUN_CONCURRENCY` (default `20`) is how many runs one worker processes at once. Raise it on a bigger machine, then run `casama selfhost up`. The worker opens up to `RUN_CONCURRENCY + 5` database connections. Watch `casama_queue_depth` and the `CasamaQueueBacklog` alert to see when you need more. **Computer size.** `COMPUTER_MEMORY_MB` (default `2048`) sets each new computer's memory. Each computer also gets 1 CPU, 512 processes, a 1 GB `/tmp` and 512 MB of shared memory. Plan host memory as about 2 GB per running computer, plus the stack itself. **Warm pool.** `WARM_POOL_SIZE` keeps that many headless computers started and unassigned, so a new computer starts in seconds instead of booting. A new computer with the default size claims one, and the pool refills after each claim and every minute. Desktop and custom-size computers always start cold. Each pool member uses memory while it waits. It works with the Docker provider only. **Idle computers.** The worker archives computers to object storage and stops them after 5 minutes without activity, so only computers in use take memory. Open terminals, running commands and live viewers keep a computer awake. ### Run computers on a separate host On a public server, keep untrusted code and the Docker socket off the machine with your data. The supervisor, egress proxy and TURN relay must run together on the computer host: the supervisor attaches the proxy and the relay to each computer's network by container name. 1. On the computer host, clone the same release and copy `infra/compose/.env` from the app host. 2. In `infra/compose/docker-compose.yml` on the computer host, publish the supervisor's port on the private interface only, for example under `services.supervisor`: ```yaml ports: - "10.0.0.2:8788:8788" ``` 3. Build and start only those services: ```sh docker compose -f infra/compose/docker-compose.yml --env-file infra/compose/.env build supervisor egress turn COMPOSE_PROFILES=images docker compose -f infra/compose/docker-compose.yml --env-file infra/compose/.env build computer-headless docker compose -f infra/compose/docker-compose.yml --env-file infra/compose/.env up -d supervisor egress turn ``` 4. On both hosts, set `TURN_PUBLIC_HOST` to a name that points at the computer host, and open 3478 (UDP and TCP) there. 5. On the app host, the compose file sets `SUPERVISOR_URL: http://casama-supervisor:8788` in the shared `x-casama` block. Change it to the computer host's private address (`http://10.0.0.2:8788`), then stop and remove the local `supervisor`, `egress` and `turn` services. 6. Connect the two hosts over a private network or WireGuard. The supervisor checks `SUPERVISOR_TOKEN` on every call, but it should never be reachable from the internet. With computers on another host, their archives live in that host's `objects` volume. Back it up there, or switch to [S3 object storage](/self-hosting/configuration#object-storage) so both hosts see the same store. Add the computer host's node-exporter to `infra/monitoring/prometheus.yml` to get its memory alerts. ## Kubernetes with Helm `infra/helm/casama` runs the API, worker, supervisor and, optionally, the web app on Kubernetes. Computers run as pods in their own namespace through the supervisor's Kubernetes provider. The chart doesn't run Postgres or Supabase: point it at Supabase Cloud or your own Supabase (for example the Supabase Helm chart). 1. Install: ```sh helm install casama infra/helm/casama -n casama --create-namespace \ --set publicUrl=https://casama.example.com \ --set pagesUrl=https://pages.casama.example.com \ --set supabase.url=https://xyz.supabase.co \ --set supabase.anonKey=... --set supabase.serviceRoleKey=... --set supabase.jwtSecret=... \ --set database.url=postgres://postgres:...@db.xyz.supabase.co:5432/postgres \ --set ingress.apiHost=casama.example.com --set ingress.pagesHost=pages.casama.example.com ``` 2. Point Supabase Auth's "before user created" hook at `https://casama.example.com/hooks/auth/before-user-created` if you want the sign-up allowlist. 3. Upgrade later with `helm upgrade` and the same values. Migrations run first. What the chart does: - **Migrations** run as a pre-install and pre-upgrade Job. The migration files are copied out of the server image, so the chart and image never drift apart. The Job uses `database.adminUrl` (defaults to `database.url`). - **Secrets**: `INTERNAL_TOKEN`, `SUPERVISOR_TOKEN`, `COMPUTER_TOKEN_SECRET` and `METRICS_TOKEN` are generated once and kept across upgrades. A value you set wins, then the existing Secret, then a new random one. The Secret is kept on uninstall. Bring your own with `existingSecret`. - **Computers** run as pods in `computers.namespace`. The supervisor's Role there allows only pods and pod proxying. Set `computers.runtimeClass` to a gVisor or Kata runtime class if your cluster has one. - **Ingress** routes the API host's API paths to the API (and `/` to the web app when it's on), and the Pages host to the API's Pages port. - The supervisor keeps computer archives on a 20 Gi `ReadWriteOnce` volume, with one replica. ### Values | Value | Default | What it does | | -------------------------- | ------------------------------------- | -------------------------------------------------------------------- | | `image.registry` | `ghcr.io/stackwares/casama` | Where the `server`, `supervisor`, `computer-headless`, `computer-desktop` and `web` images come from. The `web` image isn't published: build and push your own and set `web.image`. | | `image.tag` | `latest` | Image tag for all of them. | | `image.pullSecrets` | `[]` | Pull secrets for a private registry. | | `publicUrl` | `https://casama.example.com` | The API's public address. | | `pagesUrl` | `https://pages.casama.example.com` | Pages' public address. | | `supabase.url` | `https://your-project.supabase.co` | Supabase address. | | `supabase.anonKey` | Required | Supabase anon key. | | `supabase.serviceRoleKey` | Required | Supabase service role key. | | `supabase.jwtSecret` | Required | Supabase JWT secret. | | `database.url` | Required | Full-access Postgres URL for the API. | | `database.workerUrl` | `database.url` | Least-privilege URL for the worker. | | `database.adminUrl` | `database.url` | URL migrations run with (`supabase_admin` on self-hosted Supabase). | | `existingSecret` | (empty) | Use your own Secret with the generated keys and `CONTENT_ENCRYPTION_KEY`. | | `secrets.*` | (empty: generated) | `internalToken`, `supervisorToken`, `computerTokenSecret`, `metricsToken`, `contentEncryptionKey`. | | `extraEnv` | `{}` | More environment for the API and worker, for example `RESEND_API_KEY`. | | `api.replicas` | `2` | API replicas. | | `worker.replicas` | `1` | Worker replicas. | | `worker.runConcurrency` | `20` | `RUN_CONCURRENCY` for the worker. | | `supervisor.enabled` | `true` | Run the supervisor and computers. | | `computers.namespace` | `casama-computers` | Namespace for computer pods. | | `computers.create` | `true` | Create that namespace. | | `computers.runtimeClass` | (empty) | Runtime class for computer pods (gVisor, Kata). | | `computers.memoryMb` | `2048` | Passed to the supervisor as `COMPUTER_MEMORY_MB`, which only the Docker provider reads. Computer pods get no limits from it. | | `web.enabled` | `false` | Run the web app. Needs `web.image`. | | `web.image` | `""` | The web app image you built from `client/Dockerfile.web` and pushed (it isn't published). | | `migrations.enabled` | `true` | Run the migration Job. | | `ingress.enabled` | `true` | Create an Ingress. | | `ingress.className` | (empty) | Ingress class. | | `ingress.apiHost` | `casama.example.com` | Host for the API (and the web app). | | `ingress.pagesHost` | `pages.casama.example.com` | Host for Pages. | | `ingress.tls` | `[]` | Ingress TLS blocks. | Each component also has a `resources` value. ### What the chart leaves out - **Live view.** The chart doesn't run a TURN relay, so desktop computers have no live view. - **The egress proxy.** Computer pods use the cluster's network. Add a NetworkPolicy to the computers namespace that blocks private ranges and cloud metadata addresses. - **The warm pool**, which needs the Docker provider. - **Computer resource limits.** The Kubernetes provider sets pod limits only for a computer with its own size, so add a LimitRange to the computers namespace for default limits. - **Supervisor settings beyond the defaults.** `extraEnv` reaches the API and worker only. Hosted providers or S3 object storage on the supervisor need a change to its Deployment. Check the chart without installing anything locally: `scripts/check-helm.sh` runs `helm lint` and `helm template` in the official Helm Docker image. ## Related - [Self-hosting](/self-hosting/) - [Configuration](/self-hosting/configuration) - [Computer providers](/self-hosting/computers) - [Troubleshooting](/self-hosting/troubleshooting) - [CLI](/develop/cli) - [API](/develop/api) # Use your server on your phone (Casama Link) A Casama server on your own Mac or PC normally answers only on that computer. Casama Link gives it an `https://` address your phone can reach from anywhere, with no domain, no router settings and no open ports. You sign in on the phone by scanning a code, and notifications reach the Casama apps from the App Store and Google Play. This page takes you from a server on your computer to your phone signed in to it, then explains what goes where, what it costs, and how to turn it off. Casama Link can also give a self-hosted server Casama Cloud's computers and model credits; that part is billed and has its own page: [Cloud computers and credits](/self-hosting/casama-link-cloud). ## Before you start You need: - **A server on this computer**, started by the desktop app's **Run on This Mac** setup or installed with `./install.sh --local`. See [Run a server on your own computer](/self-hosting/#run-a-server-on-your-own-computer). - **Your account on that server.** Remote access refuses to turn on while nobody has signed up, because it closes sign-ups and the first account would otherwise belong to whoever finds the address first. - **A free Casama Cloud account** where you are an owner or admin of a workspace. You can make one while you approve the link. - **Outbound port 7844, TCP and UDP.** The `connector` container dials out to Cloudflare on it. Most home networks allow it. Some company networks and VPNs don't. - **A Casama Cloud that gives out addresses.** The CLI and the app use `https://api.casama.ai`. If that cloud doesn't hand out addresses, linking stops with "This Casama Cloud does not give out addresses." A server that already has its own `https://` domain doesn't need an address. It can still [link for notifications only](#link-without-an-address). ## Set it up ### 1. Turn on remote access **In the desktop app**, on the computer that runs the server: 1. Open **Settings**, then **Casama Link** (under Connections). The row only shows for the server's instance owner. 2. Choose **Use on Your Phone**. 3. Your browser opens Casama Cloud's **Link a Server** page. Sign in if asked, check that it shows the same code as the app, pick the workspace and choose **Link**. 4. The app goes through **Link this server**, **Get an address**, **Restart the server** and **Connect**. The restart takes about a minute. 5. When it's done, the app shows a QR code for your phone. The **Use on Your Phone** button appears only when the app is connected to the server it installed itself. For a server you installed another way, the screen shows the command below. **In a terminal**, from the server's checkout: ```sh casama selfhost remote on ``` It prints a code and a link, and opens the link in a browser. Approve the code there (it works for 15 minutes). The command then gets the address, restarts the stack with it, waits up to three minutes for the connector, and prints the address. | Option | What it does | | ----------------- | ----------------------------------------------------------------------------------- | | `--name ` | What to call this server in Casama Cloud. Default: the machine's name. | | `--invites` | Let people you invite by email make an account. See [Who can sign up](#who-can-sign-up). | | `--no-invites` | Close sign-ups again. | | `--relink` | Link again even when the server has a key, for example after it was revoked. | | `--no-browser` | Only print the link. Useful over SSH. | | `--cloud ` | Use another Casama Cloud (default `CASAMA_CLOUD_URL`, then `https://api.casama.ai`). | | `-v`, `--verbose` | Show the installer's output while the server restarts. | Check it at any time: ```sh casama selfhost remote status ``` It says whether the address answers from outside and, when it doesn't, where it stops: Casama Cloud's record, the connector, or the address itself. ### 2. Turn on two-step sign-in The address can be reached from the whole internet. Turn on two-step sign-in for your account in **Settings → Two-step sign-in**, so a guessed password isn't enough. The Casama Link screen reminds you until you do. ### 3. Sign in on your phone 1. Install Casama from the App Store or Google Play. 2. Scan the code: - with the phone's camera, then open the link, or - in the app's sign-in screen, choose **Scan a Code from Your Computer**. 3. The app asks **Sign in to** your server's address. Choose **Sign in**. The code holds the server's address and a one-time sign-in code. It works once, for five minutes, and showing a new code ends the old one. Anyone who scans it is signed in as you, so don't share a picture of it. Each time a code is used, your account gets a "New sign-in" notice. If your account has two-step sign-in, the phone still asks for the second step. To show a code again: - in the app: **Settings → Sign In on Another Device**, or **Show Sign-In Code** on the Casama Link screen, or - in a terminal where the CLI is signed in: `casama pair`. Both work on any Casama server, Casama Cloud included. You can also type the address by hand: on the phone's sign-in screen, choose **More options**, then **Server**. ### 4. Keep the computer awake Phones reach the server only while the computer is on, awake and online. On a Mac, turn on **Keep This Mac Awake While Plugged In** on the Casama Link screen. It holds the Mac awake while Casama is open and the charger is connected. On other systems, change the computer's own power settings. ## How it works ```text Phone ── https ──> Cloudflare edge ── tunnel ──> connector ──> Caddy ──> API, Auth, Pages (*.casama.link) (your computer, dials out on 7844) Your server ── check-in every hour, notifications ──> Casama Cloud (control desk only) ``` 1. **Linking.** Your server asks Casama Cloud for a code. A workspace owner or admin approves it, and the server collects a key (`kcc_…`) once. That key can hold an address and send notifications. It can't spend the workspace's credits. 2. **The address.** Casama Cloud makes a Cloudflare tunnel for your server and two names on `casama.link`: `https://<12 random characters>.casama.link` for the app, and the same name with `-p` added for bots' [Pages](/guide/pages), which stay on their own origin. 3. **The connector.** The `connector` container (Cloudflare's `cloudflared`, pinned) holds the tunnel open. It only dials out, and nothing on your computer is published to the network. The API fetches the tunnel's secret from Casama Cloud and hands it to the connector through a private Docker volume. 4. **Your phone's traffic** goes to Cloudflare's edge and down the tunnel to your computer. It never passes through Casama's servers. 5. **Check-ins.** Every hour the server tells Casama Cloud it's there. If Cloudflare's tunnel was made again, the server fetches the new secret. If the connector stays disconnected for five minutes, the server asks for the tunnel again. Losing touch with Casama Cloud never takes a working address down: the stored secret keeps the connector running. 6. **The app on the server's own computer** keeps using the local address (`CASAMA_LOCAL_URL`, for example `http://localhost:8080`). It stays signed in and works with no internet. Only other devices use the public address. ### Who can see what | Part | Who can see it | | ------------------------ | -------------------------------------------------------------------------------------------------- | | Your chats, files and API calls | Your server, and Cloudflare in transit: TLS ends at Cloudflare's edge, as on any Cloudflare-proxied site, and the tunnel to your computer is encrypted again. Casama's servers never carry or store it. | | Sign-in codes | Only your server. The code is in the part of the link after `#`, which browsers don't send to `casama.ai`, and the phone redeems it at your server. Casama Cloud can't sign in to your server. | | Notifications | Casama Cloud passes them to Firebase and Apple, with their text, unless **Private Notifications** is on. It doesn't store the text or the device tokens. | | Live video from away | The relay passes video it can't read: WebRTC encrypts it between the bot's computer and your phone. | | Your server's record | Casama Cloud keeps the workspace it's linked to, its name and id, its address, the platform and version it reports, and when it last checked in. | What Casama Cloud can do: it runs the tunnels and the `casama.link` names in its own Cloudflare account, so it can take an address down or point it elsewhere. It can't read what passes through the tunnel. If you want no third party in the path at all, give the server your own domain or use a private network such as a VPN instead. ## Who can sign up Turning remote access on sets `DISABLE_SIGNUP=true`, because anyone who learns the address can reach the sign-in screen. People who already have an account sign in as before; the app tells everyone else "This server isn't taking new accounts." To let more people in, turn on **Let Invited People Sign Up** on the Casama Link screen (or run `casama selfhost remote on --invites`). Only an email address with a pending invite to a workspace on your server can then make an account. The server's sign-up hook checks it before the account is made, and refuses the sign-up if the check can't run. The server restarts to change this setting. ## Notifications The apps from the App Store and Google Play only accept notifications sent with Casama's own Firebase key, and call rings on iPhone with Casama's own Apple key. So a linked server with no Firebase key of its own (`FCM_SERVICE_ACCOUNT`) hands its notifications and call rings to Casama Cloud, which sends them on. **Private Notifications** (on the Casama Link screen, instance owner only) keeps the text on your server. The phone then shows "New activity", call rings show "Casama" instead of the bot's name, and the app loads the rest from your server when you open it. The switch takes effect within seconds, with no restart. Without a link, a self-hosted server still fills the in-app inbox; it just can't push to the store apps. ## Live view away from the computer Live view of a bot's desktop is video through a relay. Your server's own relay listens only on your computer, so: | Where you watch | What you get | | ----------------------------------------- | ------------------------------------------------------------------ | | On the computer that runs the server | Live video, as always. No internet needed. | | Anywhere else, Casama Cloud plan Plus and up | Live video through Casama Cloud's relay, and you can take control. | | Anywhere else, Free plan | The screen as a screenshot about once a second. | "Anywhere else" includes a phone on the same Wi-Fi: it reaches the server through the public address too. The plan is the one of the Casama Cloud workspace the server is linked to. The Casama Link screen (**Live View Away From Here**) and `casama selfhost remote status` say which applies. How the relay is reached: your phone connects to it directly. A bot's computer has no route to the internet except the egress proxy, so with remote access on, the `turn` container forwards one more port (3479, never published) to that relay and nowhere else. The relay accepts only short-lived credentials that your server gets from Casama Cloud. They last up to 12 hours, and a server can ask for them at most 24 times a day. ## When the phone can't reach the server If the server stops answering while the app is open, a bar over the app says **Can't reach your Casama server**, or **Your server is offline** when Cloudflare answered but your computer didn't (the computer is asleep, off or without internet). The app checks again every 10 seconds and when you bring it back to the front, and reloads by itself once the server answers. **Try Again** checks at once. ## Servers per plan A Casama Cloud workspace can link this many servers at once: | Plan | Servers | Live video away from the computer | | ---- | ------- | --------------------------------- | | Free | 1 | No (screenshots) | | Plus | 1 | Yes | | Pro | 3 | Yes | | Max | 10 | Yes | The address, sign-in by QR code and notifications are free on every plan. See [Usage, budgets and plans](/guide/usage). ## Limits - Uploads through the address are limited to 100 MB each, and a reply must start within 100 seconds. These are Cloudflare's limits. - The address is random, but it isn't a secret. Treat the server as public: a good password and two-step sign-in. - Notifications through Casama Cloud are capped at 2,000 devices an hour per server. - A server that hasn't checked in for 14 days may have its tunnel put away. The address stays, and the tunnel comes back within a minute of the server starting again. - An address you turned off, or a server that was removed, keeps its name reserved for 90 days. - Addresses used for phishing or malware are taken down. Report one to `security@casama.ai`. ## Turn it off In the app: **Settings → Casama Link → Turn Off**. In a terminal: ```sh casama selfhost remote off ``` The address stops answering, the connector stops, and the server goes back to answering only on this computer. Every setting remote access changed goes back to what it was, sign-ups included. The server stays linked: turning it on again gives it the same address. To unlink completely, remove the server in your Casama Cloud workspace: **Settings → Billing**, open **Charges by server, Casama Link servers and keys**, find it under **Linked Servers** and choose **Remove**. That frees its place on the plan, also when the server is offline or gone. ## Link without an address A server on its own domain already has an address, but without a Firebase key of its own it can't notify the store apps. Link it to Casama Cloud for notifications and call rings alone: ```sh casama selfhost remote link ``` It shows a code to approve, saves the key and restarts the server. Nothing about who can reach the server changes: no address, no tunnel, and sign-ups stay as they are. **Private Notifications** works the same way. `remote link` takes `--name`, `--cloud`, `--relink`, `--no-browser` and `--verbose`. ## What gets set `casama selfhost remote on` and the desktop app write these to `infra/compose/.env`, then re-run the installer, which starts the `connector` container (Compose profile `link`). You shouldn't need to edit them by hand. | Name | What it holds | | ------------------------ | ----------------------------------------------------------------------------- | | `CASAMA_REMOTE_ACCESS` | `on` or `off`. `on` starts the connector and the relay forwarder. | | `CASAMA_CLOUD_URL`, `CASAMA_CLOUD_KEY` | The link to Casama Cloud. A linked key holds an address and sends notifications. It can't spend money. | | `CASAMA_INSTANCE_ID` | This server's id at Casama Cloud. The same id gets the same address back. | | `CASAMA_PUBLIC_URL`, `CASAMA_PAGES_URL` | The public address, and the one for bots' pages. | | `CASAMA_LOCAL_URL` | The address on this computer, which its own app keeps using. | | `DISABLE_SIGNUP`, `SIGNUP_INVITED_ONLY`, `SIGNUP_HOOK_ENABLED`, `SIGNUP_HOOK_URI` | Who can make an account. See [Who can sign up](#who-can-sign-up). | | `TRUSTED_CLIENT_IP_HEADER`, `AUTH_RATE_LIMIT_HEADER` | `cf-connecting-ip`, so rate limits count the real caller. | | `CASAMA_REMOTE_ACCESS_BEFORE` | The values from before, so turning off restores them exactly. | `casama selfhost up`, `down` and `logs` add the `link` profile by themselves while remote access is on. ## Troubleshooting Start with `casama selfhost remote status`, then see [Remote access](/self-hosting/troubleshooting#remote-access-casama-link) in Troubleshooting. It follows the request's path: the phone, Cloudflare, the connector, and Casama Cloud. ## Related - [Casama Link overview](/guide/casama-link) - [Cloud computers and credits](/self-hosting/casama-link-cloud) - [Self-hosting](/self-hosting/) - [Configuration](/self-hosting/configuration#casama-link) - [Troubleshooting](/self-hosting/troubleshooting#remote-access-casama-link) - [CLI](/develop/cli) # Troubleshooting Problems you might hit running your own Casama server, each as symptom, cause and fix. Most start with the same two commands: ```sh casama selfhost status casama selfhost logs migrate api worker auth ``` Instance owners can also check the health of each service under Settings → admin console. ## Install ### "Docker is not running (or this user cannot use it)" **Cause:** The Docker daemon isn't running, or your user isn't allowed to use it. **Fix:** Start Docker (`sudo systemctl start docker`, or open Docker Desktop). On Linux, add your user to the `docker` group (`sudo usermod -aG docker $USER`), sign out and back in, and run `docker info` to check. ### "Docker Compose v2 is needed" **Cause:** Only the old `docker-compose` (v1) is installed, or no Compose at all. **Fix:** Install the Docker Compose plugin so `docker compose version` works, then run the installer again. ### "Couldn't pull the images" **Cause:** No internet access, or the registry rate-limited anonymous pulls. Supabase's images come from `public.ecr.aws`, which allows only a few anonymous pulls at a time. The installer already pulls two at a time and retries five times. **Fix:** Wait a few minutes and run `./install.sh` again. Images that finished downloading are kept. ### "Warning: less than 8 GB of memory" **Cause:** The machine has less memory than Casama needs for a few computers. **Fix:** The install continues, but computers may fail to start. Use a bigger machine, lower `COMPUTER_MEMORY_MB`, or run computers elsewhere (see [Computer providers](/self-hosting/computers)). ### "The API did not become ready" **Cause:** Something in the stack failed to start within three minutes. Usual suspects: the `migrate` service, Supabase Auth, or the API crashing on a bad setting. **Fix:** 1. Check which services are down: `casama selfhost status`. 2. Read their logs: `casama selfhost logs migrate api auth`. 3. If `api` logs `Invalid environment: : ...`, fix that setting in `infra/compose/.env` and run `casama selfhost up`. 4. If `migrate` logs `Auth/Realtime schemas did not appear`, see the next entry. ### Migrations wait, then fail with "Auth/Realtime schemas did not appear" **Cause:** `migrate` waits up to four minutes for Supabase Auth and Realtime to create their database schemas before it applies Casama's migrations. If Auth or Realtime keeps crashing, they never appear. **Fix:** Read `casama selfhost logs auth realtime` and fix what they report (the next entry covers the most common one). Then run `casama selfhost up`; `migrate` runs again and applies only migrations it hasn't applied yet (tracked in `public.casama_migrations`). ### Supabase Auth won't start **Symptom:** `auth` restarts over and over; sign-in fails with a gateway error. **Cause:** Usually one of: - `SIGNUP_HOOK_URI` is a plain `http://` address. Supabase Auth only accepts `https://` hook URLs (plain http only on localhost), and refuses to start otherwise, even with the hook off. - `SAML_PRIVATE_KEY` is in PKCS#8 format. Auth needs PKCS#1. Installers before November 2026 wrote PKCS#8. **Fix:** Run `./install.sh` again: it converts the SAML key and leaves the rest of `.env` alone. Set `SIGNUP_HOOK_URI` to empty or to `https:///hooks/auth/before-user-created`. Then run `casama selfhost up`. ### I re-ran the installer with `--domain`, but the address didn't change **Cause:** When `infra/compose/.env` exists, the installer keeps it. `--domain`, `--local` and `--http-port` only apply to the first run. **Fix:** Edit the address settings in `.env` yourself. See [Core and URLs](/self-hosting/configuration#core-and-urls). ### Caddy can't get a certificate **Symptom:** The browser shows a TLS error; `casama selfhost logs caddy` shows ACME errors. **Cause:** The domain doesn't point at the server yet, or ports 80 and 443 aren't reachable from the internet. **Fix:** Check the DNS record (`dig +short casama.example.com`) and your firewall, then run `docker compose -f infra/compose/docker-compose.yml --env-file infra/compose/.env restart caddy`. Behind another proxy that terminates TLS, set `CASAMA_SITE=:80` (see [Behind another proxy](/self-hosting/configuration#behind-another-proxy)). ## Health checks ### The root page says "Casama is running", but the app can't sign in **Cause:** That note means Caddy is up but the web app isn't installed; it only answers the root page. Other paths show the real status. **Fix:** Check the API directly: ```sh curl -i https://casama.example.com/readyz ``` `200` with `"status":"ok"` means the API and database are fine. A `503` with `"degraded"` means the API can't reach the database: check `casama selfhost logs db api`. A `502` with "Casama isn't ready yet" means Caddy can't reach that service. ## Sign-in and email ### Confirmation and sign-in emails never arrive **Cause:** Supabase Auth sends email only through SMTP, and a new server has none. New accounts are confirmed automatically (`EMAIL_AUTOCONFIRM=true`), so passwords work, but emailed sign-in links, codes and password resets don't. **Fix:** Set `SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS` and `SMTP_ADMIN_EMAIL` (see [Email](/self-hosting/configuration#email)), then `casama selfhost up`. Check delivery problems in `casama selfhost logs auth`. ### Email links open a page that doesn't exist **Cause:** Older compose files built Auth's links as `
/verify`, but Auth is served under `/auth/v1`. Or the links land on the API's address when you expected your web app. **Fix:** Upgrade: the bundled compose file now sends links to `
/auth/v1/verify`. To land people on your web app after they open a link, set `AUTH_SITE_URL` to its address (see [Email](/self-hosting/configuration#email)), then `casama selfhost up`. ### Invites show a code instead of sending an email **Cause:** Neither SMTP (`SMTP_HOST`) nor Resend (`RESEND_API_KEY`) is set, so Casama can't send email. **Fix:** Share the code with the person, or set the SMTP settings (or `RESEND_API_KEY`) and `EMAIL_FROM`, then restart. ### Every sign-up is refused with "limited to approved email addresses" **Cause:** `SIGNUP_ALLOWED_EMAILS` doesn't include that email or its domain. If no one can sign up at all, `AUTH_HOOK_SECRET` is missing or differs between Auth and the API; without a valid secret, an allowlist refuses everyone. **Fix:** Check the list and that `SIGNUP_HOOK_ENABLED=true` and `AUTH_HOOK_SECRET=v1,whsec_...` are set, then `casama selfhost up`. ### Nobody has the admin console **Cause:** The instance owner is the first account, unless `INSTANCE_ADMIN_EMAILS` is set. If it's set, only those emails are owners. **Fix:** Set `INSTANCE_ADMIN_EMAILS=you@example.com` and run `casama selfhost up`. ## The app can't reach the server ### "Can't connect" in the app or CLI **Cause:** The app or CLI points at the wrong address, or the server isn't reachable from that device. `--local` servers answer only on the machine they run on. **Fix:** 1. In the app, tap **More options** → the **Server** chip (or **Use a different server**) and check the address, including `https://`. 2. In the CLI, check `casama config`, and set it with `casama config --api-url
`. 3. From the device, open `
/healthz` in a browser. It should return `{"status":"ok"}`. ### The web app on another domain gets CORS errors **Cause:** In production, the API allows browser calls only from its public address and the origins in `CORS_ORIGINS`. **Fix:** Add the web app's origin, for example `CORS_ORIGINS=https://app.example.com`, then `casama selfhost up`. The native apps and the CLI don't need this. ### Links to bots' pages point at `localhost:8790` **Cause:** Pages are served from their own origin, and `CASAMA_PAGES_URL` defaults to `http://localhost:8790`. **Fix:** Give Pages their own domain with `CASAMA_PAGES_SITE` and `CASAMA_PAGES_URL` (see [Core and URLs](/self-hosting/configuration#core-and-urls)). ### OAuth connections, hosted MCP or agent-to-agent calls return 502 or the web app **Cause:** Caddy forwards only the paths in the `@api` matcher of `infra/compose/selfhost/Caddyfile` to the API; everything else goes to the web app. Older Caddyfiles left out some of `/oauth/*` (the redirect target for app connections), `/mcp`, `/a2a/*`, `/links/*`, `/link/*` and `/telephony/*`. **Fix:** Upgrade (`casama selfhost upgrade`), or add the missing paths to the `@api` matcher yourself, for example `/oauth/* /mcp /mcp/* /a2a/* /links/* /link/* /telephony/*`. Then restart Caddy: `docker compose -f infra/compose/docker-compose.yml --env-file infra/compose/.env restart caddy`. ### Signed-out requests get "rate_limited" behind a tunnel **Cause:** Behind a tunnel on the same machine (Cloudflare Tunnel, for example), every request reaches Caddy from the tunnel's address, so all signed-out callers share one rate limit. **Fix:** Set `TRUSTED_CLIENT_IP_HEADER` to the header that carries the caller's real address (`cf-connecting-ip` for Cloudflare), then `casama selfhost up`. ## Computers ### Bots say they have no computer **Cause:** The API or worker can't reach the supervisor, or it isn't configured. The admin console shows "Sandbox supervisor: Not configured" or unhealthy. **Fix:** Check `casama selfhost logs supervisor`. The supervisor refuses to start without `SUPERVISOR_TOKEN` (16+ characters), `COMPUTER_TOKEN_SECRET` and `EGRESS_CONTROL_TOKEN`; re-run `./install.sh` to add missing generated settings. If it logs `DEFAULT_PROVIDER= isn't configured on this supervisor`, add that provider's settings or remove `DEFAULT_PROVIDER`. ### A computer fails to start **Cause:** Common ones: - The computer image is missing. The installer builds (or with `--pull`, downloads) the headless image; the desktop image only with `--with-desktop`. - `SANDBOX_RUNTIME=runsc` is set but gVisor isn't installed or registered with Docker. - The host is out of memory or disk. **Fix:** 1. Check the images: `docker images | grep computer-`. Get the desktop one with `./install.sh --with-desktop`. 2. Check `docker info | grep -i runsc`. If it's missing, set `SANDBOX_RUNTIME=` (empty) and run `casama selfhost up`, or install gVisor. 3. Check `free -h` and `df -h`, and the supervisor's logs. ### "The computer could not be reached" **Cause:** The API answers `503` with `computer_unavailable` when it can't reach a computer, for example while it's stopping, restarting or waking, or when the supervisor is down. A personal computer whose desktop app isn't connected answers `409` with `device_offline` instead. **Fix:** Wait a moment and try again. If it keeps happening, check `casama selfhost logs supervisor` and `docker ps --filter name=casama-c-`. ### A computer can't reach a website **Cause:** The egress proxy blocks private, loopback, link-local, CGNAT and reserved addresses, plus anything in `EGRESS_BLOCKED_CIDRS`. Non-HTTP traffic (SSH, for example) has no route out. **Fix:** Check `casama selfhost logs egress`, which logs each refused connection. Services on your LAN aren't reachable from computers by design; `OUTBOUND_ALLOW_CIDRS` only applies to the API and worker. ### Bots can't reach Ollama or another service on my network **Cause:** The server's outbound calls block private addresses unless you allow them. On Linux, `host.docker.internal` doesn't resolve inside the containers by default. **Fix:** Set `OUTBOUND_ALLOW_CIDRS` to the network (for example `192.168.1.0/24`), run `casama selfhost up`, and use the host's LAN address in the credential's base URL. ### Plugins' servers don't start on the computer **Symptom:** Installing a plugin with local (stdio) servers fails, or its tools never appear. **Cause:** Plugin servers run inside the bot's computer, started by `computerd`. A computer still on an image built before your upgrade, or a desktop image that wasn't rebuilt, has an older `computerd` that can't run them. Hosted templates and snapshots built from older images have the same problem. **Fix:** Rebuild the images with `./install.sh --with-desktop` (or without `--with-desktop` if you don't use desktops), then let the computer sleep and wake, or restart it from the app. For hosted providers, rebuild your templates or snapshots from the new images. ### Many old computer containers are still running **Cause:** The supervisor creates computers outside Compose, so `casama selfhost down` leaves them. The worker stops idle computers after 5 minutes, but only while it's running. **Fix:** Start the stack again with `casama selfhost up`. To see them: `docker ps --filter name=casama-c-`. ## Live view ### Live view stays on "connecting" **Cause:** Viewers reach the computer's screen only through the TURN relay on port 3478. It's usually blocked by a firewall, or `TURN_PUBLIC_HOST` names a host viewers can't reach (for example `localhost` on a server). **Fix:** 1. Open 3478, UDP and TCP, on the server's firewall and any cloud security group. 2. Check that `TURN_PUBLIC_HOST` in `.env` resolves to the server from the viewer's device. 3. Check the admin console's "Live view relay" line, and `casama selfhost logs turn`. 4. Make sure the computer uses the desktop image. Networks that block both UDP and port 3478 can't use live view: the bundled relay doesn't serve TLS on 5349. For hosted providers, the relay must be reachable from the internet. ### Away from home, live view shows screenshots **Cause:** The server is on your own computer and you reached it through its Casama Link address. The server's relay sits behind your router, so live video away from home goes through a relay at Casama Cloud, which comes with the Plus plan and up. Without it you see the screen about once a second. **Fix:** 1. Run `casama selfhost remote status`, or open **Settings → Casama Link**. It says whether live view away from the computer is included. 2. If it is included and you still see screenshots, restart the stack once (`casama selfhost up`), so the `turn` container starts forwarding to the relay, and check `casama selfhost logs turn` for "forwarding port 3479". 3. A bot's computer that was already streaming is restarted with the relay the first time someone watches from away. Close live view and open it again. ## Remote access (Casama Link) Start with: ```sh casama selfhost remote status ``` It checks the path a phone's request takes, from the far end back: Casama Cloud's record of your server, the `connector` on your computer, and the address as the outside world sees it. The Casama Link screen in the app shows the same, with **Check Again**. ### "Create your account on this server first" **Cause:** Remote access closes sign-ups, and until an account exists the first person to sign up owns the server. **Fix:** Open the app on the computer, sign up on your server, then turn remote access on. ### "The server isn't running" **Cause:** `remote on` checks the server's accounts in its database first, and the stack is down. **Fix:** `casama selfhost up`, then try again. ### "This server already has a public address" **Cause:** The server's `CASAMA_PUBLIC_URL` is an `https://` address that isn't this machine: a domain, or a tunnel of your own. Addresses from Casama Link are for servers without one. **Fix:** Nothing to do for reaching it. For notifications in the apps from the stores, run `casama selfhost remote link`. ### "This Casama Cloud does not give out addresses" **Cause:** The Casama Cloud the server links to (`CASAMA_CLOUD_URL`, `--cloud`, or `https://api.casama.ai`) doesn't run Casama Link's addresses. **Fix:** Check the address you passed. A Casama Cloud you run yourself needs the `CASAMA_LINK_*` settings listed under [Settings only Casama Cloud uses](/self-hosting/configuration#settings-only-casama-cloud-uses). ### "This server's Casama Cloud key can't hold an address" **Cause:** `CASAMA_CLOUD_KEY` is a key for cloud computers and credits, made in Casama Cloud's Billing screen. It has no `remote_access` scope. **Fix:** Run `casama selfhost remote on --relink` to get a linked key. That replaces the old key, so to keep cloud computers and credits too, use one key with all four scopes. See [One key per server](/self-hosting/casama-link-cloud#2-configure-your-server). ### "That code ran out before it was approved" **Cause:** A link code works for 15 minutes. **Fix:** Run the command again (or choose **Use on Your Phone** again) and approve the new code. Only an owner or admin of the Casama Cloud workspace can approve it. ### "Your plan connects 1 server" **Cause:** The Casama Cloud workspace already has as many servers linked as its plan allows. **Fix:** Remove a server you no longer use in that workspace (**Settings → Billing**, then **Charges by server, Casama Link servers and keys**, then **Linked Servers**), or link this one to another workspace with `casama selfhost remote on --relink`. ### The connector isn't connected **Symptom:** "The address is set up, but this server's connector hasn't reached it yet", or the app says "This network blocks the connection." **Cause:** The `connector` container reaches Cloudflare on outbound port 7844, TCP and UDP. A VPN, a company network or a strict firewall often blocks it. **Fix:** 1. `casama selfhost logs connector` shows what it tried. 2. Turn the VPN off, or allow outbound 7844, and wait a minute. 3. If the logs say it's waiting for the tunnel secret, check `casama selfhost logs api` for `casama link:` lines. The API fetches the secret from Casama Cloud at start and checks in every hour. ### "The connector isn't running" **Cause:** The `connector` container isn't there, usually because the stack was started without the `link` profile. **Fix:** Start it with `casama selfhost up` (which adds the profile while remote access is on), or re-run `./install.sh`. With plain Compose, add `--profile link`. ### The connector is connected, but the address doesn't answer **Cause:** A new address can take a minute. After that it is usually Caddy or the API not running. **Fix:** `casama selfhost status`, then `casama selfhost logs caddy api`. ### "This server's address changed" **Cause:** Casama Cloud gave the server another address than the one in its `.env`. The server won't run the tunnel for an address its sign-in links and webhooks don't use. **Fix:** Run `casama selfhost remote on` again, so the stack is set up with the new address. ### The phone says "Your server is offline" or "Can't reach your Casama server" **Cause:** "Your server is offline" means Cloudflare answered but the computer behind the address didn't: it's asleep, off or without internet, or the stack is down. "Can't reach your Casama server" means nothing answered at all, often because the phone itself is offline. **Fix:** Wake the computer and check `casama selfhost status`. The app checks again every 10 seconds and reconnects by itself. On a Mac, turn on **Keep This Mac Awake While Plugged In** on the Casama Link screen. ### The app on the computer signed me out after turning it on **Cause:** The app on the server's own computer should keep using the local address. That needs `CASAMA_LOCAL_URL` in `.env`, which `casama selfhost remote on` sets. **Fix:** Check that `CASAMA_LOCAL_URL` is set (for example `http://localhost:8080`) and that the app's server is that address, not the public one. ### Notifications don't arrive on the phone **Cause:** Only linked servers can reach the apps from the stores, and only when the server has no Firebase key of its own: a `FCM_SERVICE_ACCOUNT` from another Firebase project can't reach them. A server whose key Casama Cloud refused stops sending through it until the server restarts. **Fix:** Check the Casama Link screen: notifications go through Casama Cloud when **Private Notifications** is offered there. Empty `FCM_SERVICE_ACCOUNT` if it holds a key for another project, run `casama selfhost up`, and check `casama selfhost logs worker` for `push relay` lines. ### Remote access was turned off by Casama Cloud **Cause:** The server was removed from its workspace, its key was revoked, or the address was suspended after a report. **Fix:** `casama selfhost remote status` says which. Removed or revoked: run `casama selfhost remote on --relink`. Suspended: write to `security@casama.ai`. ## Backups and restores ### "age is not installed" **Fix:** Install age (`apt install age` or `brew install age`) on the machine running the backup or restore. ### "This backup is encrypted; pass --identity with your age key file" **Fix:** Run `casama selfhost restore --identity backup.key` with the private key that matches a recipient the backup was encrypted to. "age could not decrypt ... (wrong identity?)" means the key doesn't match. ### `pg_restore` prints many warnings during a restore **Cause:** Supabase owns some database objects that `pg_restore --clean` can't drop or recreate. **Fix:** None needed: the data is restored. Check by signing in once the stack is back up. ### After restoring on a new machine, sign-in or encrypted content fails **Cause:** `restore` doesn't restore `infra/compose/.env`. A new install generated new keys, so tokens, the JWT secret or `CONTENT_ENCRYPTION_KEY` no longer match the data. **Fix:** Put the backup's `env` file at `infra/compose/.env`, run `./install.sh` (it keeps that file), then restore again. See [Restore](/self-hosting/operations#restore). ### The Library's files are missing after a restore **Cause:** `casama selfhost backup` doesn't archive the `library` volume, and `restore` doesn't unpack `library.tar.gz` from the scheduled backup container. **Fix:** Extract `library.tar.gz` into the `library` volume yourself, for example with a one-off container that mounts it. See [Back up your server](/self-hosting/operations#back-up-your-server). ### "No install.sh in ..." **Cause:** `casama selfhost` commands need the checkout. They look at `--dir`, then `CASAMA_SELFHOST_DIR`, then the current directory. **Fix:** Pass `--dir /path/to/casama` or set `CASAMA_SELFHOST_DIR`. ## Related - [Self-hosting](/self-hosting/) - [Configuration](/self-hosting/configuration) - [Operations](/self-hosting/operations) - [Computer providers](/self-hosting/computers) - [FAQ](/faq)