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.

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 an always-running process on Local or Kubernetes that has no ports, scaling, or persistent storage.

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")
  .replicas(1)
  .permissions("database-runtime")
  .build()

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.

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)`	No	Persistent volume mounted at `/data`. 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.

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