Docs

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.

alien.ts
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.

PlatformRuns onPublic endpointsPersistent volumes
AWSEC2 machines in a ComputeClusterALB for HTTP, NLB for TCPgp3 EBS
Google CloudCompute Engine machines in a ComputeClusterBackend services behind an HTTPS or TCP proxyPersistent Disk
AzureAzure VMs in a ComputeClusterApplication Gateway for HTTP, Azure Load Balancer for TCPManaged Disks
KubernetesDeployment, or StatefulSet when statefulNo TCP endpointsPersistentVolumeClaim templates
MachinesJoined hostsNo TCP endpointsNot supported
LocalDockerHTTP and TCPBind 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

alien.ts
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:

src/client.ts
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 | null

A Container with .commandsEnabled(true) receives commands through a pull receiver it starts itself:

src/index.ts
import { createCommandReceiver } from "@alienplatform/commands"

const receiver = createCommandReceiver()
receiver.command("status", async () => ({ ready: true }))
await receiver.run()

Permissions

SetGrants
container/provisionLoad balancers, volumes, and certificates. Used by initial setup or for live provisioning.
container/management, container/heartbeatInspecting and managing container infrastructure.
container/volume-backupsLets AWS Data Lifecycle Manager snapshot and expire this stack's volumes.
key/native-volumeEncrypting volumes with a customer-managed Key.

Next

On this page