Differences

Internet egressCopy Anchor Link

Unsupported deployments report SANDBOX_EGRESS_GATEWAY_UNAVAILABLE. They do not fall back to direct internet access.

For an existing AWS VPC, use CloudFormation or Terraform. Supply SandboxSubnetIds, SandboxGatewaySubnetIds, and SandboxGatewaySubnetCidrs.

Kubernetes routes outbound traffic only to gateway pods on port 3128. It needs no sandbox DNS exception. The cluster's network determines its outbound IP; Alien does not allocate a fixed NAT IP there.

ImagesCopy Anchor Link

Azure agent images and the image-user contract are planned for the release after v3.3.40. The tables below describe that release. See saved image behavior and Upgrade order for current releases.

To build from a Dockerfile, replace .code() with:

.code({ type: "source", src: "./sandbox", toolchain: { type: "docker" } })

Run alien build, then alien release. A shared Dockerfile needs a base published for both architectures. You can also select a base per architecture:

FROM public.ecr.aws/lambda/microvms:al2023-minimal AS base-arm64
FROM python:3.14-slim AS base-amd64
FROM base-${TARGETARCH}

Docker sets TARGETARCH for each build. Add your application and its dependencies after the final FROM.

Native Azure images and Local images need sh, setsid, od, tr, sleep, and kill for command timeouts. Give changed Azure images a new tag or digest. Azure builds one disk image per reference.

New builds inspect the original image USER, except Azure catalog builds. Catalog builds retain native exec and may run as root.

Local and Kubernetes accept images without USER and keep UID 65534. They refuse an explicit root USER. AWS uses root for absent USER with a connector; modes without one keep UID 60000 and released startup. Explicit root requires a connector. See Users and privileges.

Local builds reuse a cached image only when its OS and architecture match the requested target. Missing images and mismatched tags pull the requested platform. A mismatched immutable image ID fails with IMAGE_BUILD_REJECTED; use a matching image or a registry tag. See image selection.

The GCP sandbox service agent needs Artifact Registry Reader on the image repository.

Image user errorsCopy Anchor Link

Image inspection rejects user identities that cannot run commands safely.

See the identity resolver and architecture check.

Setup and updatesCopy Anchor Link

A Worker, Container, or Daemon can link a live Sandbox. Other resources, including Build, need it frozen. Internet sandboxes also refuse Build consumers because gateway administration is private to workloads.

See Frozen & Live Resources for setup ownership and management permissions.

OperationsCopy Anchor Link

Call capabilities() before using optional operations on new sessions. After reconnecting, call capabilities(sandboxId) for that session's operations.

Azure entries below describe agent images unless marked native. Catalog images and saved native sessions use native transport.

AWS reports preview only when ports are declared. Kubernetes does not report sandboxLifetime at runtime because callers cannot choose a deadline when claiming a warm pod.

GCP's resume can return a fresh container. Do not use it to preserve state. No backend reports a restorable snapshot capability.

Create optionsCopy Anchor Link

Use command-level env for portable code. Azure rejects create-time PATH, IFS, SHELLOPTS, BASHOPTS, LD_*, and invalid shell variable names. Agent images also reserve ALIEN_SANDBOX_*.

LifetimeCopy Anchor Link

A create-time lifetime cannot extend the declaration. Without a declared lifetime, AWS still caps sessions at eight hours. GCP applies its service default. Always terminate sandboxes after saving their results.

AWS resume waits until commands can run. It refuses a terminated sandbox. AWS, GCP, and Azure terminate wait for deletion. AWS reports SANDBOX_UNREACHABLE if it cannot confirm termination within 30 seconds.

Kubernetes terminate only deletes sandboxes claimed by the current process. For another process's sandbox, it returns success without deleting anything.

LimitsCopy Anchor Link

AWS resource IDs may contain at most 17 characters, or 16 with "none" egress.

Output beyond the cap is dropped. The exit frame reports truncated: true. Finished jobs count until a poll reads their result. GCP runs commands longer than 30 seconds through the jobs API.

Kubernetes keeps two idle pods per Sandbox resource. A create fails while the pool is empty. Idle pods reserve the declared CPU and memory.

AWS sizesCopy Anchor Link

Alien picks the largest tier whose peak memory and disk fit. Declared CPU must cover that tier's peak CPU.

The smallest accepted declaration is cpu: "1", memory: "2Gi", disk: "8Gi". Omitting .limits() selects the 2 GiB baseline tier.

Azure sizesCopy Anchor Link

CPU is a multiple of 250m, from 250m to 16 cores. Memory is at most 2 GiB per declared core. Disk is at most 20 GiB per declared core.

FilesCopy Anchor Link

Errors and retriesCopy Anchor Link

SANDBOX_UNREACHABLE is retryable, but it does not make create idempotent. Backends attempt cleanup when readiness fails. A failed create can still leave a sandbox without returning its ID. AWS cannot list these sandboxes. GCP lists the resource's sandboxes without identifying which caller created them.

Plan-time refusal codes appear inside VALIDATION_FAILED messages. These include SANDBOX_CAPABILITY_UNSUPPORTED, SANDBOX_LIMIT_INVALID, and SANDBOX_EGRESS_GATEWAY_UNAVAILABLE.

Domain allowlistsCopy Anchor Link

The deprecated object forms retain their existing behavior.

See Security for the enforcement boundary and DNS limits.