Container
A Container is a long-lived service that runs from an image, with replicas, ports, and optional disks and GPUs. It fits API servers, queue consumers, databases, and model servers.
import * as alien from "@alienplatform/core"
const api = new alien.Container("api")
.code({ type: "image", image: "ghcr.io/acme/api:1.4.0" })
.cpu(1)
.memory("1Gi")
.port(8080)
.publicEndpoint("web", 8080)
.healthCheck({ path: "/health" })
.minReplicas(2) // 2 replicas, autoscaling up to 20
.permissions("execution")
.build()
export default new alien.Stack("acme")
.add(api, "live")
.permissions({ profiles: { execution: {} } })
.build().permissions("execution") names the Container's permission profile, the set of cloud permissions it runs with. execution grants nothing here, because the Container uses no other resource.
| Platform | Runs on | Public endpoints | Persistent volumes |
|---|---|---|---|
| AWS | EC2 machines in a ComputeCluster | ALB for HTTP, NLB for TCP | gp3 EBS |
| Google Cloud | Compute Engine machines in a ComputeCluster | Backend services behind an HTTPS or TCP proxy | Persistent Disk |
| Azure | Azure VMs in a ComputeCluster | Application Gateway for HTTP, Azure Load Balancer for TCP | Managed Disks |
| Kubernetes | Deployment, or StatefulSet when stateful | No TCP endpoints | PersistentVolumeClaim templates |
| Machines | Joined hosts | No TCP endpoints | Not supported |
| Local | Docker | HTTP and TCP | Bind mounts |
On AWS, Google Cloud, and Azure, Alien creates a ComputeCluster with a general pool if the stack doesn't declare one. See Behavior and limits for placement, scaling, and what each platform refuses.
A Container is always "live": Alien creates and updates it on every release (see Frozen and live). The image's entrypoint, or .command(), starts your process directly, with no runtime wrapper.
Images from a private registry are copied into the release, so customers never need your registry credentials (see Private images). The API reference lists every builder method.
When to use another type
- Worker: requests and events that each finish within one invocation, at no cost while idle.
- Daemon: exactly one process on every machine, such as a log collector.
- Sandbox: code you don't trust.
Volumes and backups
const key = new alien.Key("volume-key").build()
const db = new alien.Container("db")
.code({ type: "image", image: "postgres:17" })
.cpu(2)
.memory("8Gi")
.port(5432)
.persistentStorage("500Gi", {
mountPath: "/var/lib/postgresql/data",
encryptionKey: key,
backups: { intervalHours: 4, retentionDays: 14 },
})
.replicas(1)
.permissions("execution")
.build().persistentStorage() makes the container stateful. Each replica gets a stable ordinal (db-0, db-1) and keeps its own volume across restarts and replacement.
Backups are on by default: a snapshot every 24 hours, kept for 7 days. Snapshots stay in the customer's account, in the volume's region.
To restore one replica's volume:
alien deployments volumes <deployment>
alien deployments restore-volume <deployment> --resource db --ordinal 0 --snapshot <snapshot-id>See Volumes for how restores work and which platforms take snapshots.
Use it in code
Resolve a linked container's URLs:
import { container } from "@alienplatform/sdk"
const search = container("search")
const internal = await search.getInternalUrl() // first port
const byPort = await search.getInternalUrls() // Record<port, url>
const external = await search.getPublicUrl() // string | nullA Container with .commandsEnabled(true) receives commands through a pull receiver it starts itself:
import { createCommandReceiver } from "@alienplatform/commands"
const receiver = createCommandReceiver()
receiver.command("status", async () => ({ ready: true }))
await receiver.run()Permissions
| Set | Grants |
|---|---|
container/provision | Load balancers, volumes, and certificates. Used by initial setup or for live provisioning. |
container/management, container/heartbeat | Inspecting and managing container infrastructure. |
container/volume-backups | Lets AWS Data Lifecycle Manager snapshot and expire this stack's volumes. |
key/native-volume | Encrypting volumes with a customer-managed Key. |