Overview

A Container runs a service or background process in each customer's cloud. Point it at an existing image, or point it at source code and Alien builds an image during release. Use Containers for HTTP services, databases, vector stores, stream processors, GPU-backed services, and anything that needs stable internal DNS or persistent local storage.

Alien creates the required cloud infrastructure, places the container replicas on the customer's machines, and monitors them during rollout. The image's configured command starts your app directly. For source code, alien build first produces that runnable image; no Worker runtime wraps the process.

Deployment Modes

Containers can run in three modes inside the customer's cloud. The same alien.Container definition works across all of them — the choice is made at install time, not in code.

Mode	What it is	When to choose
Managed VMs	Alien provisions VMs (EC2 / Compute Engine / Azure VMs) in the customer's cloud and runs containers on them through a shared control plane.	Default. Lowest operational overhead — no cluster to maintain.
Managed Kubernetes	Alien creates a dedicated Kubernetes cluster (EKS / GKE / AKS) in the customer's cloud and runs containers on it.	The customer standardizes on Kubernetes but doesn't already have a cluster, or wants Alien to own the cluster lifecycle.
BYO Kubernetes	Install into the customer's platform team's existing cluster via Alien's namespace-scoped enterprise Helm chart.	The customer's platform team already operates a cluster and wants the deployment confined to a single namespace under their governance.

Platform Mapping

Platform	Runtime	Managed by
AWS	EC2, EBS, load balancers	Alien
GCP	Compute Engine, Persistent Disk, load balancers	Alien
Azure	Virtual Machines, Managed Disks, load balancers	Alien
Kubernetes / On-Prem	Deployment or StatefulSet	Kubernetes

When to Use

Use Container when the service needs to keep running between requests, serve internal traffic over stable DNS, attach persistent or high-throughput local storage, use GPUs, or run an existing image.

Use Worker for request-response code. Use Daemon for a machine-oriented process that should run once on every eligible machine or node.

Quick Start

alien.ts

import * as alien from "@alienplatform/core"

const api = new alien.Container("api")
  .code({ type: "image", image: "ghcr.io/acme/api:2026-05-17" })
  .cpu(1)
  .memory("1Gi")
  .port(8080)
  .publicEndpoint("web", 8080, "http")
  .minReplicas(2)
  .maxReplicas(10)
  .permissions("execution")
  .build()

export default new alien.Stack("app")
  .add(api, "live")
  .build()

Stateful Services

Stateful containers get stable replica identity and can attach persistent storage.

alien.ts

const postgres = new alien.Container("postgres")
  .code({ type: "image", image: "postgres:16" })
  .cpu(2)
  .memory("8Gi")
  .port(5432)
  .stateful(true)
  .persistentStorage("500Gi", { mountPath: "/var/lib/postgresql/data" })
  .replicas(1)
  .permissions("database-runtime")
  .build()

Replicas get stable ordinals (postgres-0, postgres-1, …), and each ordinal keeps its volume: the volume survives replica restarts and replacement, and the replica is placed where its volume lives.

Public and Internal Networking

Every port is internal unless you attach a named public endpoint to it. Other linked services can reach internal ports through service discovery. Public exposure creates cloud load-balancing for the named endpoint.

const service = new alien.Container("service")
  .code({ type: "image", image: "ghcr.io/acme/service:v4" })
  .cpu(1)
  .memory("512Mi")
  .port(8080)
  .port(9090)
  .publicEndpoint("web", 8080, "http")
  .permissions("execution")
  .build()

Additional ports remain internal unless you attach another endpoint.

TCP endpoints pass traffic through a network load balancer without TLS termination — use them for databases and other non-HTTP protocols:

.publicEndpoint("pg", 5432, "tcp")

Commands

Containers can participate in the Commands protocol. Setting .commandsEnabled(true) injects the ALIEN_COMMANDS_* configuration, but it does not start a runtime or polling sidecar. Your app starts createCommandReceiver() from @alienplatform/commands (or the Rust receiver), registers its handlers, and runs the pull loop itself.

Configuration

Method	Required	Description
`.code(code)`	Yes	Container image or source build configuration.
`.cpu(value)`	Yes	CPU request. Use a number for the same min/desired value or a `{ min, desired }` object.
`.memory(size)`	Yes	Memory request such as `"512Mi"` or `"2Gi"`.
`.port(number)` / `.ports(numbers)`	Yes	Internal container ports.
`.publicEndpoint(name, port, protocol)`	No	Publicly expose a named endpoint on a container port as `"http"` or `"tcp"`.
`.replicas(count)`	No	Fixed replica count. Cannot be combined with autoscaling.
`.minReplicas(count)` / `.maxReplicas(count)`	No	Convenience autoscaling controls.
`.autoScale(config)`	No	Full autoscaling configuration.
`.stateful(boolean)`	No	Enables stable identity. Required for persistent local storage.
`.persistentStorage(size, options?)`	No	Persistent volume mounted at `/data` (or `options.mountPath`). Sets `stateful(true)`.
`.ephemeralStorage(size)`	No	Extra scratch storage that may be lost when a replica moves.
`.gpu(config)`	No	Request GPU capacity.
`.healthCheck(config)`	No	HTTP health check used during rollout and refresh.
`.environment(vars)`	No	Environment variables injected into the container.
`.link(resource)`	No	Gives the container binding access to another resource.
`.permissions(profile)`	Yes	Permission profile used for cloud access.
`.pool(name)`	No	Capacity group to run on.
`.command(args)`	No	Overrides the image command.
`.commandsEnabled(boolean)`	No	Injects configuration so an app-owned command receiver can lease this container's commands. Does not start a runtime or sidecar. Default: `false`.
`.stopGracePeriod(seconds)`	No	Grace period for stopping replicas during updates, drains, and deletes.

See API Reference for every builder method and Behavior & Limits for platform behavior and limits.

On this page