Lab containers

Generated Markdown for references/concept_lab_containers.md.

Open book page Back to the skill graph

# Lab containers

_OCI containers as first-class lab machines: each runs in a micro-VM, sharing the VM namespace, segments, snapshots and agent channel (PRD §18)._

Labs often need infrastructure that already ships as a container image — a
database, a web app, a build service. Rather than bolt a container runtime
onto the host, vmlab runs each declared container inside its own **micro-VM**:
a pinned Alpine kernel plus a purpose-built init that unpacks the OCI image as
the root filesystem and supervises the workload. That one design choice buys
full machine parity with zero extra privileges:

- **One namespace.** VM and container names share DNS, `depends_on` waves,
  `forward { to = … }` targets and provision scoping. To the rest of the lab
  a container is just another machine on the segment — and to the daemon,
  the CLI and the API they answer the same `machine` commands, differing only
  in what they report they can do (a container has no framebuffer; a VM keeps
  no console log).
- **Full snapshot parity.** Offline and online snapshots, standalone or
  lab-wide, identical to VMs.
- **The same automation.** The [vmlab-agent](../references/entity_vmlab_agent.md) runs inside
  the micro-VM, so `vmlab container exec`/`shell`, `vmlab osinfo`, clipboard,
  the wscript [machine handle](../references/entity_vm_api.md), playbooks and file copy
  all work — network or no network.
- **Volumes & ports.** Named or bind volumes ride virtiofs (CIFS fallback),
  and `port {}` blocks are sugar for segment forwards.


```wcl
container "db" {
  image   = "postgres:17"
  profile = "container"
  memory  = 1GiB
  nic    { segment = "corp" }
  env    { name = "POSTGRES_PASSWORD" value = "lab" }
  volume { name = "pgdata" target = "/var/lib/postgresql/data" }
}
```

Declare one with a [`container {}` block](../references/entity_container_block.md); drive it
with `vmlab container <verb>`, the wscript
[container tour of the machine API](../references/entity_container_api.md), or its page in the web console.
Images pull from any registry (digest-pinned in lab state), and `mode = :idle`
boots the environment without starting the workload — handy as a toolbox
machine.


## Related

- [container {} block](../references/entity_container_block.md)

- [Container handle](../references/entity_container_api.md)

- [How vmlab fits together](../references/concept_architecture.md)

- [share {} block](../references/entity_shares.md)

- [OCI distribution](../references/concept_oci.md)

- [vmlab-agent](../references/entity_vmlab_agent.md)

[← Back to SKILL.md](../SKILL.md)