Primitives
Environments, services, deployments, instances, and networks.
Five objects. Everything in unisrv.hcl is one of them.
Environment
The top-level scope, owning every service, deployment, instance, and network inside it. Resolved from project in your unisrv.hcl, or pinned with --env <name>.
The same file applied to a second environment gives an independent copy. That is how per-PR and per-agent environments work, torn down with unisrv destroy.
Service
An HTTPS entrypoint. It holds the hosts it answers on, and a list of locations mapping path prefixes to targets, so app.example.com can route /api to one deployment, / to another, and /legacy to an external URL.
Hosts are optional: every service is always reachable at a derived {service}-{environment-slug}.unisrv.dev. Claim a domain when you want a permanent address of your own.
Deployment
N replica instances of one container image, plus the resources each gets. You scale and redeploy here: change the image tag, run unisrv up, and its instances are replaced.
A deployment is routable from at most one service. With no port and no location it is a worker — it runs, nothing routes to it. replicas = 0 is scale to zero.
Instance
One container inside an isolated Firecracker microVM, with its own kernel, network stack, and resource limits. VM-level isolation at container startup speed.
Instances are ephemeral: created, running, stopped, never restarted. Stopping destroys, and a new one takes its place, which forces immutable deploys.
Resources are reserved per instance, never overcommitted. The vCPU ratio is the guaranteed share of a physical core behind each vCPU — 1.0 is dedicated, lower is burstable.
| Resource | Range | Default |
|---|---|---|
| vCPUs | 1–32 | 1 |
| Memory | 128 MB – 32 GB | 512 MB |
| vCPU ratio | 0.125, 0.25, 0.5, 1.0 | 0.25 |
Storage is scratch-only. Anything written inside an instance is gone when it is replaced. Fine for a preview database, wrong for durable data — use an external provider.
Images are standard OCI, pulled fresh from any registry at instance creation. There is no build step and no node-side cache, so prefer immutable tags or digests over latest.
Network
A private CIDR-scoped network that deployments join to reach each other. Within one network, a deployment's name resolves to the IPs of its running instances: an api deployment reaches postgres:5432.
That is how you keep a database off the internet while the app in front of it is public.
How a request reaches your container
The edge proxy resolves the host to a service, matches the path against its locations in order, and forwards to one instance of that location's deployment. It reaches the node over the mTLS tunnel that node dialled out; the container sees plain HTTP. See How it works.