> 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/drizz-twins.md).

# Drizz Twins

Private, realistic copies of Google Calendar and Gmail, so you can see what your AI agent actually did.

Ask an agent to move a meeting to 3pm. It replies "Done! Moved to 3pm." Did it notice the Dentist appointment already at 3pm? You can't tell from the reply.

Drizz Twins lets you check. Your agent works on a **twin**: a private, fake copy of Google Calendar or Gmail that behaves like the real one. Afterwards you read the twin's own record of every call your agent made, and the calendar or mailbox as it stands. Nothing touches a real account, and the data is made up.

{% hint style="success" %}
New to Drizz Twins? The [Quickstart](/twins/getting-started/quickstart.md) takes a few minutes and ends with every call your agent made on screen.
{% endhint %}

## How it works

```mermaid
flowchart LR
    SEED["Describe a world<br/>(seed.md)"] --> WORLD["Create the world<br/>twin world create"]
    WORLD -->|"MCP address + token"| AGENT["Your agent acts<br/>over MCP"]
    AGENT -->|"tool calls"| TWIN["The twin records<br/>every call and change"]
    TWIN --> READ["Read the calls and state<br/>twin world calls"]
```

1. Describe what is on the calendar and in the inbox, in a plain-text seed file.
2. Create a world from it: your own private copy, with an MCP address and a token.
3. Your agent connects to that address over MCP, as it would to the real product.
4. Read back every call it made, and the state before and after.

## Get started

|                                                            |                                                                                      |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| [**Introduction**](/twins/getting-started/introduction.md) | What a twin is, why you test on one instead of a real account, and what you get back |
| [**Quickstart**](/twins/getting-started/quickstart.md)     | Install, make a world, connect your agent, read its calls                            |
| [**Key concepts**](/twins/getting-started/concepts.md)     | Twins, worlds, seeds, leases, keys, tokens and the record of calls                   |

## Use twins

|                                                                              |                                                                                                                           |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| [**Describe a world**](/twins/using-twins/describe-a-world.md)               | Write a seed file: what is on the calendar and in the mailbox when a world starts                                         |
| [**Connect your agent**](/twins/using-twins/connect-your-agent.md)           | Give your agent a world's MCP address and token, from Claude Code, Cursor, Codex, a stdio-only client, Scalekit or Python |
| [**Run your agent**](/twins/using-twins/run-your-agent.md)                   | Run any agent in a world, control its clock, make mail arrive mid-run, inject faults                                      |
| [**See what your agent did**](/twins/using-twins/see-what-your-agent-did.md) | Read every call, watch calls live, read the state, keep or copy a world, delete it                                        |
| [**Web console**](/twins/using-twins/web-console.md)                         | Make twins, connect an agent and watch every call from your browser                                                       |
| [**Several twins as one unit**](/twins/using-twins/several-twins.md)         | Raise several twins from a blueprint, so they reset, renew and lapse together                                             |

## Available twins

|                                                           |                                                                              |
| --------------------------------------------------------- | ---------------------------------------------------------------------------- |
| [**Google Calendar**](/twins/available-twins/calendar.md) | Events, recurring events, attendees, other calendars and sharing, free/busy  |
| [**Gmail**](/twins/available-twins/gmail.md)              | Messages, threads, labels, drafts, attachments, filters and mailbox settings |

## Self-host

|                                                                  |                                                                                   |
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| [**Self-hosting overview**](/twins/self-hosting.md)              | Run the twins server inside your own network: one machine, Kubernetes, or a cloud |
| [**Docker Compose**](/twins/self-hosting/docker-compose.md)      | The twins server, Postgres and the cache on one Linux machine                     |
| [**Kubernetes (Helm)**](/twins/self-hosting/kubernetes.md)       | Any Kubernetes cluster with the Helm chart, from a trial to production            |
| [**AWS, Google Cloud and Azure**](/twins/self-hosting/clouds.md) | Terraform modules built on each cloud's managed services                          |
| [**Your own sign-in**](/twins/self-hosting/your-own-sign-in.md)  | Sign people in through your own OpenID Connect provider instead of issuing keys   |
| [**Upgrades**](/twins/self-hosting/upgrades.md)                  | Upgrade the server, and roll back safely after a database migration               |
| [**Backups**](/twins/self-hosting/backups.md)                    | Back up and restore the two volumes the server needs                              |
| [**Monitoring**](/twins/self-hosting/monitoring.md)              | Scrape metrics, turn on alerts, and know what to do when one fires                |
| [**Air-gapped installs**](/twins/self-hosting/air-gapped.md)     | Install on a network with no internet, from one bundle that carries every image   |

## Reference

|                                                            |                                                                                                       |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| [**CLI reference**](/twins/reference/cli.md)               | Every `twin` command for signing in, making worlds, running agents and reading what happened          |
| [**Keys and limits**](/twins/reference/keys-and-limits.md) | Signing in, where your key is kept, keys for CI, roles, and how many worlds you can hold for how long |
| [**Troubleshooting**](/twins/reference/troubleshooting.md) | The usual errors when making worlds and connecting agents, and what to do                             |
| [**Glossary**](/twins/reference/glossary.md)               | The words you'll see in Drizz Twins, each in a sentence or two                                        |

## Next

* [Quickstart](/twins/getting-started/quickstart.md): make your first world and read your agent's calls.
* [Introduction](/twins/getting-started/introduction.md): why you test on a twin instead of a real account.
* [Connect your agent](/twins/using-twins/connect-your-agent.md): point your own agent at a world.

***

*Last updated: 27 October 2026*