# Design your genesis

Genesis is the first governed state of your Ripple Custody environment. It defines the root domain, launch domains, first users, roles, and initial policies that must exist before the platform can operate safely.

## What is a genesis file

A genesis file is the JSON request body submitted to the one-time `POST /v1/genesis` API operation during initial setup. It creates the initial governed state of the environment before normal authentication, users, and intent approvals exist.

The file typically defines:

- The root domain and any launch-critical subdomains.
- The first users and their role assignments.
- The policies that govern post-launch changes.
- Optional cryptographic setup, validated tickers, and system properties required from day one.


After Genesis runs, later changes use normal governed intents instead of editing or rerunning the genesis file.

## What belongs in genesis

Put state in genesis when the environment needs it before normal governed changes can happen.

| Include in genesis | Usually defer until after launch |
|  --- | --- |
| Root domain and launch-critical subdomains. | Convenience subdomains that can be created later. |
| First users and roles required to satisfy launch workflows. | Routine users who are not needed for initial quorum. |
| Policies required for root administration, user management, policy management, operations, compliance, and recovery. | Low-priority refinements that can be deployed through the initial policy model. |
| Breakglass or recovery controls required for day-one operation. | Emergency controls that are not yet designed or tested. |
| System signing public key, if system-signed API proposals must be available at launch. | System-signed intent enablement and policies that can be safely created after launch. |


Infrastructure configuration belongs outside the governance model. Governance state belongs in genesis.

## Design workflow

Work through genesis in this order:

| Step | Page | Output |
|  --- | --- | --- |
| 1 | [Design your domains](/products/custody/governance/genesis/design-your-domains) | Root domain, launch subdomains, governing strategies, and read access model. |
| 2 | [Plan your first users](/products/custody/governance/genesis/plan-your-first-users) | First users, roles, quorum coverage, and bot users. |
| 3 | [Design your policies](/products/custody/governance/genesis/design-your-policies) | Initial policy set for administration, operations, compliance, fallback, and recovery. |
| 4 | [Genesis payload reference](/products/custody/governance/genesis/payload-reference) | Payload structure for the one-time Genesis API operation. |


The pages are ordered deliberately: policies depend on domains and users. If the domain or user model changes, review the policy model again.

For the full launch sequence, including post-genesis vault registration and smoke testing, see [Genesis launch steps](/products/custody/governance/genesis/launch-steps).

## Final output

Before setup, you should have:

- A domain tree.
- A user and role matrix.
- A policy coverage matrix.
- A breakglass and recovery plan.
- A compliance and screening plan, if compliance screening is part of launch.
- A list of changes intentionally deferred until after launch.


For the underlying model, see [Domains](/products/custody/governance/domains), [Users and roles](/products/custody/governance/users), [Policies](/products/custody/governance/policies), and [Intents and approvals](/products/custody/governance/intents).