Skip to content

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 first.

  • Found a bug? Open an issue with steps to reproduce it.
  • Planning a large change? Start a discussion first, so you agree on the approach before you write it.
  • Found a security issue? Don't open an issue. Follow SECURITY.md.

What you need ​

ToolVersionUsed for
Node.js24 or newer (see .nvmrc)The API, worker, supervisor and packages
pnpm12 (packageManager in package.json)JavaScript dependencies
DockerrecentSupabase, computers, the self-host stack
Supabase CLIrecentLocal Postgres, Auth, Realtime and Storage
Dart3 (stable)The CLI, SDK and computerd
Flutter3.50The app
PostgreSQL 17 with pgvector and pgTAP17Tests 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 <id>
dart run bin/casama.dart chat Ada "What can you do?"

See 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 <files> on TypeScript you changed and dart format <files> 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: 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/.