> 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/self-hosting.md). # Self-hosting overview Run the twins server inside your own network, on one machine, on Kubernetes, or on AWS, Google Cloud or Azure. Run twins inside your own network. Your agents then act on twin worlds that never leave it. {% hint style="info" %} **Getting the install files.** The Docker Compose file, Helm chart, Terraform modules and twins images are shared with you by Drizz. Ask your Drizz contact for access before you start. {% endhint %} | | | | ------------- | -------------------------------------------------------------------------------------------------------------------- | | **Runs on** | Docker Compose · Kubernetes · AWS · Google Cloud · Azure · air-gapped networks | | **You need** | A disk that is the server's own. No cloud account, no identity provider and no model key. | | **Keep** | Two volumes: `records` (Postgres) and `worlds` | | **Watch out** | Lambda, Cloud Run, App Service and Container Apps cannot run twins. See [Where it cannot run](#where-it-cannot-run). | ## Prerequisites * A disk that is the twins server's own: a block disk, or a network file system with working locks that only one server writes at a time. * A model the server can reach (`OPENAI_API_KEY`), only for a world founded from a written `brief`. A baseline, a `scenario`, a `population` or a `size` needs none. ## What runs Self-hosting runs the same image and command as every Drizz deployment, with the stores it needs beside it. | Service | What it is | | ----------------------- | ------------------------------------------------------------------------------------------------------ | | Twins server (`worlds`) | Every world, its MCP endpoint and API, and the operator routes. | | Postgres | The organizations, people, API keys and the record of what each did. | | Cache (Valkey, BSD-3) | The request allowance, counted once for every process. Any cache that speaks the Redis protocol works. | | Web console (`console`) | Optional. The web console, signed in to with an API key. | The twins server keeps each world in SQLite files on a volume of its own. Postgres keeps everything else. ```mermaid flowchart LR agent["Your agent"] -->|MCP| server operator["You: CLI and operator API"] -->|API key| server console["Web console (optional)"] --> server subgraph net["Your network"] server["Twins server"] server --> pg[("Postgres: people, keys, records")] server --> cache[("Valkey cache: request allowance")] server --> vol[("Worlds volume: SQLite files")] end server -.->|optional copies| bucket[("S3 bucket")] agent -.->|the agent's own model calls| model["Your model provider"] ``` Nothing in twins calls out. The only traffic that leaves your network is your agent's own model calls. One exception: a world founded from a written `brief` needs a model the server can reach. ## Where it can run The twins server needs a disk that is its own. Every compute service in AWS's, Microsoft's and Google's own guides ([AWS](https://docs.aws.amazon.com/decision-guides/latest/compute-on-aws-how-to-choose/choosing-aws-compute.html), [Azure](https://learn.microsoft.com/en-us/azure/architecture/guide/technology-choices/compute-decision-tree), [Google Cloud](https://docs.cloud.google.com/docs/compute-area/choose-compute-options)) falls on one side of that line. | Cloud | Runs twins | How | | ------------ | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | | Any | A Linux machine with Docker (EC2, Lightsail, Azure VMs, VMware, Compute Engine, a server of your own) | `deploy/docker-compose.selfhost.yml` | | Any | Kubernetes: EKS (EC2 nodes), AKS, GKE Standard and Autopilot, OpenShift, EKS Anywhere, a cluster of your own | `deploy/charts/twins` | | AWS | EKS on Fargate | The chart with `worlds.persistence.existingClaim`: a statically provisioned EFS volume | | AWS | ECS on Fargate or on EC2 | `deploy/terraform/aws` (`capacity.type`) | | Azure | AKS | `deploy/terraform/azure` | | Google Cloud | GKE | `deploy/terraform/gcp` | ## Where it cannot run | Cloud | Does not run twins | Why | | ------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | AWS | Lambda, App Runner, AWS Batch | Short functions or jobs, or no volume a server can keep. | | Azure | App Service | Microsoft: "Don't use storage mounts for local databases, such as SQLite" ([storage mounts](https://learn.microsoft.com/en-us/azure/app-service/configure-connect-to-azure-storage)). | | Azure | Container Apps | A new revision runs beside the old one until it is ready ([revisions](https://learn.microsoft.com/en-us/azure/container-apps/revisions)). Two servers would write one set of SQLite files over a network share on every update. | | Azure | Container Instances, Functions, Batch | Azure Files over SMB only, or functions and jobs. | | Google Cloud | Cloud Run | Google: NFS volumes are mounted without locking, and writes are held in memory until flushed ([NFS volumes](https://docs.cloud.google.com/run/docs/configuring/services/nfs-volume-mounts)). | | Google Cloud | App Engine, Cloud Run functions | No disk a server keeps. Google points new apps from App Engine to Cloud Run. | ## Choose an install path
Docker ComposeOne Linux machine with Docker. The quickest way to try twins, or to run it for a small team.Docker Compose
Kubernetes (Helm)Any cluster. Bundled stores to try it, managed stores, a gateway or ingress and TLS for production.Kubernetes (Helm)
AWS, Google Cloud, AzureTerraform modules that build the cloud's managed pieces and install twins on them.AWS, Google Cloud and Azure
Air-gappedA network with no internet. One bundle carries every image across.Air-gapped installs
After you install, these pages apply to every path: * [Your own sign-in](/twins/self-hosting/your-own-sign-in.md): let people sign in through Okta, Entra, Keycloak, Auth0 or Authentik. * [Upgrades](/twins/self-hosting/upgrades.md): move to a new version, and roll back. * [Backups](/twins/self-hosting/backups.md): what to keep, and how to put it back. * [Monitoring](/twins/self-hosting/monitoring.md): metrics, alerts, and what to do for each one. ## Sign-in is off by default A self-hosted server has no identity provider to sign in through. You mint every key on the server: enroll an address, then issue a key for it. Each install page shows how. To use your own identity provider instead, see [Your own sign-in](/twins/self-hosting/your-own-sign-in.md). ## What to keep * `records`: Postgres. People, keys and the record of what each did. * `worlds`: every world's data. Back up both. The cache holds nothing that outlives a restart. See [Backups](/twins/self-hosting/backups.md). ## Next * [Docker Compose](/twins/self-hosting/docker-compose.md): the quickest way to try twins on one machine. * [Kubernetes (Helm)](/twins/self-hosting/kubernetes.md): any cluster, from a trial to production. * [AWS, Google Cloud and Azure](/twins/self-hosting/clouds.md): Terraform modules on each cloud's managed services. *** *Last updated: 27 October 2026*