Concepts at a glance
The five words this documentation uses — workspace, universe, app, host and entrypoint — and how they fit together.
Five words
| Word | What it means |
|---|---|
| Workspace | One project, described by one multiverse.yaml: the repositories it is made of, the apps that run them, and how a copy of it is addressed. One per project, kept wherever you like and used from anywhere with -f. |
| Universe | One complete copy of that workspace: a git worktree of every repository, one runtime project per app, and its own set of hostnames. Numbered (3) or named after a branch (fix/login). |
| App | A runnable unit inside a universe: one repository's compose files, started as their own project. A repository usually has exactly one, and does not have to say so. |
| Host | One address an app answers on, named by a key: host api in universe 3 is api-u3.<domain>. A host knows which service and container port serve it. |
| Entrypoint | A port the shared proxy listens on, named. Every universe shares them, because requests are told apart by hostname rather than by port. |
How they nest
workspace "acme" multiverse.yaml ├── universe 3 ~/acme/universes/3 │ ├── app api project acme-u3-api │ │ ├── service web host api → api-u3.example.test │ │ └── service db no host; reachable inside the app │ └── app web project acme-u3-web │ └── service app-dev host app → app-u3.example.test └── universe fix/login ~/acme/universes/fix-login └── ... the same shape, its own everything
Each level namespaces the one below it. The workspace name prefixes every runtime project, the universe adds its own part, and the app adds a third, so a container is acme-u3-api-web-1 and two repositories can both call a service app without meeting.
It is not a virtual machine
A universe is a namespace, not a sandbox. It shares the machine's kernel, its container runtime, its image cache and its git object store — which is why a new one costs seconds rather than minutes, and why the second one does not double your disk use. What it does not share is the four things that actually collide: checkouts, container names, volumes and hostnames.
Two consequences worth knowing. A universe is not isolated for security purposes: anything running in one can reach the others' containers over the proxy network. And a universe is not reproducible the way an image is — it is your machine, with your daemon and your caches.