Forks

A fork is an isolated environment within an application. Think of it as a branch of your running system: same platform and application, but its own data, its own active release, and its own PostgreSQL schema.

Every intent submission and query call targets a specific fork via forkId.

What a fork provides

Isolated per fork	Description
Active release	Which compiled IR version rules and queries use
Projection schema	PostgreSQL schema `{platform}_{app}_{fork}`
Ledger & snapshots	Entity state and event history scoped to this fork
Deployment history	Record of which releases were deployed and when

Forks do not share projection rows or entity snapshots. A check-in on fork staging does not appear on fork main.

Common fork patterns

Fork	Typical use
`main`	Production traffic
`staging`	Pre-production validation against real infrastructure
`dev`	Shared development environment
`test-{id}`	Ephemeral fork per CI run or engineer experiment

When you create an application, Causet Cloud typically provisions a main fork automatically.

Creating a fork

In the control plane:

Open your Platform → Application.
Go to Forks.
Click Create fork, choose a forkId and optional description.
Optionally set a parent fork for lineage tracking.

Fork IDs must be unique within the application. Use lowercase alphanumeric IDs with hyphens (e.g. staging, test-pr-42).

Fork ID in API calls

All runtime and query requests include the fork:

curl -X POST ".../applications/concert-app/intents/execute" \
  -d '{
    "forkId": "main",
    "action": "FOLLOW_ARTIST",
    "entityId": "user-1",
    "payload": { "user_id": "user-1", "artist_id": "artist-1" }
  }'

curl -X POST ".../forks/main/queries/shows_for_followed_artists" \
  -d '{ "params": { "user_id": "user-1" } }'

Clients take forkId in configuration — see Deployments: Forks.

Staging before production

The recommended flow:

Deploy a new release to staging.
Run integration tests against staging (unique test data, no production impact).
Deploy the same release to main when tests pass.

Because releases are immutable, the exact IR tested on staging is what goes to production.

Test forks in CI

Use a unique fork per test run to avoid cross-test contamination:

FORK_ID="test-$(uuidgen | tr '[:upper:]' '[:lower:]')"
# deploy release to $FORK_ID
# run tests with forkId = $FORK_ID

See Testing Events for patterns.

Fork health

The control plane shows fork health: runtime connectivity, active release, latest deployment status, and projection worker lag. A fork with a failed deployment or unhealthy runtime will surface in the Forks list before you route traffic to it.

Next steps

Releases — what gets deployed to a fork
Deployments — activate a release on a fork
Entity Inspector — browse entity state per fork

Overview Releases