API Reference

Constructor

new alien.Container(id: string)

code

Sets what the container runs.

.code({ type: "image", image: "ghcr.io/acme/api:v1" })
.code({ type: "source", src: "./api", toolchain: { type: "docker" } })

If you use image, Alien deploys that image directly. If you use source, Alien runs the selected toolchain during build/release and turns the result into a container image. In both cases the configured image command starts your app directly; there is no Worker runtime wrapper in front of a Container.

Supported source toolchains are the same toolchains used by Workers:

cpu

Sets CPU requirements.

.cpu(1)
.cpu({ min: "0.5", desired: "2" })

memory

Sets memory requirements.

.memory("1Gi")

ports

Adds internal ports.

.port(8080)
.ports([8080, 9090])

Every container must define at least one port.

publicEndpoint

Publicly exposes a named endpoint through provider load-balancing infrastructure.

.port(8080)
.publicEndpoint("web", 8080, "http")

.publicEndpoint("admin", 9090, "tcp")

.publicEndpoint("tenants", 8080, {
  protocol: "http",
  hostLabel: "tenants",
  wildcardSubdomains: true,
})

Options can be a protocol string ("http" or "tcp") or an object:

Additional ports remain internal unless they have their own endpoint. See External URLs for how hostnames, DNS, and TLS work.

replicas and autoscaling

.replicas(3)

.minReplicas(2)
.maxReplicas(20)

.autoScale({
  min: 2,
  desired: 4,
  max: 20,
  targetCpuPercent: 70,
  targetMemoryPercent: 80,
  targetHttpInFlightPerReplica: 100,
})

Use either fixed replicas or autoscaling.

stateful and storage

.stateful(true)
.persistentStorage("500Gi")
.persistentStorage("500Gi", { mountPath: "/var/lib/postgresql/data" })
.ephemeralStorage("100Gi")

Each ordinal keeps its volume: the volume survives replica restarts and replacement, and the replica is placed where its volume lives.

gpu

.gpu({ type: "nvidia-t4", count: 1 })

GPU placement depends on the machine pools available for the deployment.

healthCheck

.healthCheck({
  path: "/health",
  port: 8080,
  method: "GET",
  timeoutSeconds: 1,
  failureThreshold: 3,
})

environment, links, and permissions

.environment({ LOG_LEVEL: "info" })
.link(storage)
.permissions("execution")

placement

.cluster("compute")
.pool("gpu")

command

.command(["./server", "--port", "8080"])

Overrides the image default command. The container runs your entrypoint directly — there is no runtime wrapper. Bindings run in-process via @alienplatform/bindings.

stopGracePeriod

.stopGracePeriod(300)

Grace period in seconds used when stopping replicas during updates, drains, and deletes. Valid values are 1 through 86400.

commandsEnabled

Enables or disables the Commands protocol.

.commandsEnabled(true)

Outputs

Container outputs are available in stack state after provisioning.