> For the complete documentation index, see [llms.txt](https://docs.drizz.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.drizz.dev/twins/getting-started/concepts.md). # Key concepts The words you will meet in Drizz Twins, from twins and worlds to keys, tokens and the record of calls. The few ideas behind Drizz Twins, in one page. | | | | ----------------- | -------------------------------------------------------------------------------------------- | | **Covers** | Twins, worlds, seeds, leases, limits, roles, keys, tokens, the record of calls, environments | | **Default lease** | 6 hours with `twin world create`, 1 hour with `twin start` | | **World limit** | 25 worlds per organization at a time, unless an admin raised it | | **Watch out** | Calls you make with `twin api` go into the same record as your agent's | ## Terms | Term | What it means | | ------------------- | ------------------------------------------------------------------------------------------------------------- | | **Twin** | A fake copy of a product (Google Calendar, Gmail) that answers like the real one. Each twin is an MCP server. | | **World** | One private, seeded copy of a twin. Yours alone: nothing you do there is seen anywhere else. | | **Seed** | The plain-text file (`seed.md`) that says what is in a world when it starts. | | **Lease** | How long a world lives if you never delete it. | | **World limit** | How many worlds your organization can hold at once. | | **Organization** | Your company's account. People in it have roles. | | **API key** | Your credential. It makes, lists and deletes worlds. Your agent never gets it. | | **World token** | One world's credential. Your agent sends it to reach that world, and only that world. | | **Record of calls** | The twin's own log of every call made in a world (the trace). | | **Environment** | Several twins raised together as one unit. | ## Twin A twin copies a real product's behaviour: its operations, its data shapes and its failure modes. Your agent connects to it over MCP, the standard way AI agents call tools, exactly as it would connect to the real product. See the [Google Calendar](/twins/available-twins/calendar.md) and [Gmail](/twins/available-twins/gmail.md) pages for what each covers. ## World A world is one private copy of a twin, with your data in it. An agent gets its own world, drives it, and nobody else sees what it did. To your agent, a world is two things: an **MCP address** and a **token**. Each `twin world create` makes a new, separate world. Run different agents side by side, or the same agent twice. A `--label` groups worlds so you can list and delete them together: ```bash twin world create seed.md --folder a1 --label demo twin world create seed.md --folder a2 --label demo twin world list --label demo twin world cleanup --label demo ``` By default your worlds are private to you. Set `TWIN_WORLD_SHARED=1` to make worlds your organization shares instead: a teammate's key can read them, and only an admin's key can delete them. ## Seed A seed file describes a world's starting state in plain text: the events on the calendar and the emails in the mailbox. ```markdown ## Setup twin: calendar, gmail now: Mon 09:00 ## World: calendar Wed 15:00-16:00 Dentist Thu 09:00-09:30 Team sync ## World: gmail Fri 16:42 Priya -> me "Call?" #priya // A call on {Thu}, 2-4pm? ``` `now:` pins the world's clock, so "Thursday" always means the same day. You can turn a world back into files, too: * `twin world save -o after.md` writes the world as it stands, as a seed file you can read and edit. * `twin world snapshot -o snap.json` writes an exact copy of every app's state. `twin world create snap.json` makes that world again. See [Describe a world](/twins/using-twins/describe-a-world.md). ## Lease Every world has a lease: how long it lives if you never delete it. When the lease ends, the world deletes itself. | How the world was made | Default lease | | ---------------------- | ------------- | | `twin world create` | 6 hours | | `twin start` | 1 hour | Both commands take `--lease ` to set a different time. Delete a world yourself as soon as you are done with it, to free its place. ## World limit Your organization can hold **25 worlds at a time**, unless an admin raised the limit. `twin world list` shows the worlds made on this machine that still exist, and how full your organization is. ## Organization, people and roles Your organization's access comes from Drizz. People sign in with their work email. Each person has a role in the organization: **owner**, **admin** or **member**. A role bounds the keys a person can mint: * An owner or an admin may mint a key with any of the six scopes. * A member may mint five. Only `WORLDS_ADMIN` is withheld. ## Two credentials: API key and world token A person and a key are different things, on purpose. ```mermaid flowchart LR PERSON["You"] -->|"twin login"| SIGNIN["Sign in
(work email)"] SIGNIN -->|"mints"| KEY["API key
(kept on your machine)"] KEY -->|"creates"| WORLD[("A world")] WORLD -->|"world token"| AGENT["Your agent"] ``` **The API key** belongs to you. `twin login` mints one for your machine and keeps it in your OS credential store. It makes, lists and deletes worlds. It carries a frozen set of scopes, bounded by your role when it was minted. A key never widens: a later role change does not grant an existing key more. **The world token** belongs to one world. Your agent sends it as `Authorization: Bearer ` to that world's MCP address. It reaches that world and nothing else. {% hint style="info" %} Your agent never gets your API key. When you run it with `twin world run`, its environment gets the world's address and token, never your key. {% endhint %} In CI, where there is no browser, give the CLI a key minted elsewhere: ```bash twin login --with-key - < key.txt ``` Or set it in the `TWINS_API_KEY` environment variable. `twin logout` revokes this machine's key on the server and forgets it. ## Record of calls Every world records every call made in it. For each call, the twin keeps the operation, its outcome, the arguments and data (with secret-looking values masked by their content), and the change it made to the world's state. ```bash twin world calls world # every call twin world calls world --writes # only the calls that changed something twin world calls world --follow # each call as it happens twin world calls world --json # as JSON, for a program to read ``` Calls you make yourself with `twin api` go into the same record. Mail and events you add with `twin world trigger` do not: they are the world's, not the agent's. See [See what your agent did](/twins/using-twins/see-what-your-agent-did.md). ## Environment One seed can name several twins. A seed with `twin: calendar, gmail` gives you a calendar and a mailbox in one folder, and your agent reaches both in the same run. On the server, an **environment** raises several twins as one unit. Its members reset together, renew together and lapse together. See [Several twins together](/twins/using-twins/several-twins.md). ## Next * [Describe a world](/twins/using-twins/describe-a-world.md): write the seed file for your own world. * [Connect your agent](/twins/using-twins/connect-your-agent.md): give your agent a world's address and token. * [See what your agent did](/twins/using-twins/see-what-your-agent-did.md): read the record of calls. *** *Last updated: 27 October 2026*