API Reference
Builder methods, options, and outputs for Alien Containers.
Constructor
new alien.Container(id: string)| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Container resource ID. Use lowercase DNS-compatible names such as api or vector-reader. |
code
Sets what the container runs.
.code({ type: "image", image: "ghcr.io/acme/api:v1" })
.code({ type: "source", src: "./api", toolchain: { type: "docker" } })| Field | Type | Required | Description |
|---|---|---|---|
type | "image" | "source" | Yes | Use an existing image or build from source. |
image | string | For image | Container image reference. |
src | string | For source | Source directory. |
toolchain | ToolchainConfig | For source | Build toolchain. |
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.
Supported source toolchains are the same toolchains used by Workers:
| Toolchain | Use For |
|---|---|
typescript | TypeScript or JavaScript projects compiled with Bun. |
rust | Rust projects compiled with Cargo. |
docker | Projects with a Dockerfile. |
cpu
Sets CPU requirements.
.cpu(1)
.cpu({ min: "0.5", desired: "2" })| Parameter | Type | Required | Description |
|---|---|---|---|
value | number | { min: string; desired: string } | Yes | CPU in vCPUs. A number sets both min and desired. |
memory
Sets memory requirements.
.memory("1Gi")| Parameter | Type | Required | Description |
|---|---|---|---|
size | string | Yes | Memory request, for example "512Mi", "1Gi", or "16Gi". |
ports
Adds internal ports.
.port(8080)
.ports([8080, 9090])| Method | Description |
|---|---|
.port(port) | Adds one internal port. |
.ports(ports) | Adds several internal ports. |
Every container must define at least one port.
expose
Publicly exposes one port through provider load-balancing infrastructure.
.port(8080)
.expose("http")
.exposePort(8080, "tcp")| Method | Description |
|---|---|
.expose("http" | "tcp") | Exposes the first configured port. |
.exposePort(port, "http" | "tcp") | Exposes a specific port. |
Only one port may be exposed publicly. Additional ports remain internal.
replicas and autoscaling
.replicas(3)
.minReplicas(2)
.maxReplicas(20)
.autoScale({
min: 2,
desired: 4,
max: 20,
targetCpuPercent: 70,
targetMemoryPercent: 80,
targetHttpInFlightPerReplica: 100,
})| Method | Description |
|---|---|
.replicas(count) | Fixed replica count. |
.minReplicas(count) | Sets autoscaling minimum and desired replicas. |
.maxReplicas(count) | Sets autoscaling maximum replicas. |
.autoScale(config) | Sets the full autoscaling object. |
Use either fixed replicas or autoscaling.
stateful and storage
.stateful(true)
.persistentStorage("500Gi")
.ephemeralStorage("100Gi")| Method | Description |
|---|---|
.stateful(enabled) | Enables stable replica identity. |
.persistentStorage(size) | Adds persistent storage mounted at /data and marks the container stateful. |
.ephemeralStorage(size) | Requests scratch storage that may be lost when a replica restarts or moves. |
gpu
.gpu({ type: "nvidia-t4", count: 1 })| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | GPU type identifier. |
count | number | Yes | Number of GPUs. |
GPU placement depends on the machine pools available for the deployment.
healthCheck
.healthCheck({
path: "/health",
port: 8080,
method: "GET",
timeoutSeconds: 1,
failureThreshold: 3,
})| Field | Type | Default | Description |
|---|---|---|---|
path | string | "/health" | HTTP path to check. |
port | number | Container port | Port to check. |
method | string | "GET" | HTTP method. |
timeoutSeconds | number | 1 | Probe timeout. |
failureThreshold | number | 3 | Consecutive failures before unhealthy. |
environment, links, and permissions
.environment({ LOG_LEVEL: "info" })
.link(storage)
.permissions("execution")| Method | Required | Description |
|---|---|---|
.environment(vars) | No | Merges environment variables into the container config. |
.link(resource) | No | Injects binding access to another resource. |
.permissions(profile) | Yes | Permission profile name. |
placement
.cluster("compute")
.pool("gpu")| Method | Description |
|---|---|
.cluster(id) | Advanced: run on a specific container cluster. If omitted, Alien can assign or create the default cluster. |
.pool(name) | Advanced: run on a specific machine pool within the cluster. |
command
.command(["./server", "--port", "8080"])Overrides the image default command.
Outputs
Container outputs are available in stack state after provisioning.
| Field | Type | Description |
|---|---|---|
name | string | Runtime container name. |
status | "pending" | "running" | "stopped" | "failing" | Current status. |
currentReplicas | number | Replicas currently running. |
desiredReplicas | number | Target replica count. |
internalDns | string | Internal service DNS name. |
url | string | undefined | Public URL when a port is exposed. |
replicas | ReplicaStatus[] | Per-replica status details when reported by the platform. |