Skip to content

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.

The pieces ​

A Casama server is a small set of services around one Postgres database:

ServiceWhat it does
APIThe HTTP API under /v1, the live run stream, incoming webhooks, A2A and the hosted MCP server
WorkerRuns bots: each run is a durable workflow that survives a crash or restart
SupabasePostgres, Auth, Realtime and Vault. Every table has row-level security
SupervisorStarts, stops and talks to computers. It is the only service with the Docker socket
ComputersOne container per computer, with computerd inside
Egress proxyEvery computer's way to the internet. It blocks private addresses
TURN relayCarries the live view of a desktop computer
Pages serverServes 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, backup, SearXNG for web search, a PDF renderer, Caddy for HTTPS, the web app, and Prometheus and Grafana for monitoring.

Repository map ​

FolderWhat's in it
apps/serverThe API (src/api) and the worker (src/worker), billing, Casama Link (src/link) and the pages server (src/pages)
apps/supervisorThe supervisor's HTTP API and terminal proxy
packages/contractsEvery route and schema (Zod). The OpenAPI document and the Dart client are generated from it
packages/agentThe agent runtime: the run loop, context building, memory, tools, the model gateway and integrations
packages/dbThe Drizzle schema pulled from the migrations, the database client, withUserSession, and test helpers
packages/domainPure logic with no I/O: roles, approvals, budgets, limits
packages/sandboxThe 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-checkcasama-plugin-check, the plugin checker, also run as a GitHub Action
packages/evalsAgent evaluations and their tasks
packages/observabilityLogging, OpenTelemetry and error reporting
clientThe Flutter app for iOS, Android, macOS, Windows, Linux and the web
dart/casama_apiThe generated Dart REST client. Don't edit it by hand
dart/casama_sdkThe Dart SDK: sign-in, typed run events, live run watching
dart/cliThe casama CLI
dart/computerdThe agent inside each computer, and on your own machine in desktop companion mode
supabaseMigrations (the source of truth for the schema) and pgTAP tests in supabase/tests
infraCompose files, computer images, the egress proxy, TURN, the remote access connector, backups, Helm, monitoring
eeEnterprise features under a separate license: audit log export and SAML single sign-on
skillsThe skills bundled with every server
galleryThe gallery site: themes, wallpapers, skills, apps, starter bots, routine ideas and plugins
siteThe casama.ai website
docs-siteThese docs (VitePress)
deployOne-click deploy templates for hosting platforms
examplesA sample plugin and a sample SDK app
scriptsDevelopment, test and packaging scripts
docsProject 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) 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.