Behavior & Limits

GuaranteesCopy Anchor Link

Refused at Plan Time. A declaration the target platform cannot enforce, such as limits it cannot apply, an egress mode it cannot express, or a lifetime ceiling it has no primitive for, fails when the stack is planned with SANDBOX_CAPABILITY_UNSUPPORTED or SANDBOX_LIMIT_INVALID. Nothing is provisioned. The exception today is GCP, which accepts disk and doesn't apply it.

No Silent No-Op at Runtime. An operation or option the platform does not support raises OPERATION_NOT_SUPPORTED. One exception today: Kubernetes and Local ignore env and tenantKey on create.

The Declaration Bounds Every Sandbox. The binding creates sandboxes only from the alien.ts declaration. No call takes an image, cpu, memory, or egress argument, and preview takes only a declared port. A create-time timeoutMs can shorten the declared lifetime, never extend it.

Ready When Created. create resolves only once the sandbox can run a command, so the first command never races the sandbox's start.

Every Command Has a Timeout. timeoutMs is required and has no default. At the timeout the command and its process group are stopped, and the timeout is reported only after the command has stopped. A child process that detaches with setsid escapes that signal; it ends when the sandbox ends.

One Exit Frame, Last. runCommand yields exactly one exit frame, after all output. A failure is an error, not a frame, and a stream that ends without exit did not complete.

Idempotent Terminate. Terminating a sandbox that does not exist succeeds on every platform.

Lost Calls Say Whether They Ran. SANDBOX_UNREACHABLE means the operation did not take effect and is safe to retry. SANDBOX_OUTCOME_UNKNOWN means it was sent and may have taken effect; repeating a command or job start can run it twice.

LimitsCopy Anchor Link

What Each Platform AcceptsCopy Anchor Link

AWS SizesCopy Anchor Link

A Lambda MicroVM runs at one of five sizes and bursts to four times its baseline memory with no way to opt out. Alien therefore picks the largest size whose peak memory and disk fit inside the declared memory and disk, then requires the declared cpu to be at least that size's peak vCPU. A declaration no size satisfies is refused rather than rounded.

The smallest declaration AWS accepts is memory: "2Gi", disk: "8Gi", cpu: "1". A sandbox with no .limits runs at the 2 GiB baseline size.

Azure SizingCopy Anchor Link

cpu is a multiple of 250m from 250m to 16 cores. memory is at most 2 GiB per core and disk at most 20 GiB per core of the declared cpu. Anything else is refused at plan time.

Network EgressCopy Anchor Link

Egress policy applies to outbound connections. It does not block link-local addresses such as the cloud's instance metadata endpoint.

FilesCopy Anchor Link

Paths are resolved differently per platform:

Platform NotesCopy Anchor Link

AWSCopy Anchor Link

Lambda MicroVMs, which run on Firecracker virtualization.

• {region} in a bundle's bucket name or in a privateBaseImage reference resolves to the deployment's region.
• deny needs the deployment's network mode to be create or byo-vpc-aws. The default VPC isn't enough because it has no private subnets.
• Alien starts MicroVMs with no IAM role.
• list isn't available: listing MicroVMs needs an account-wide permission that Alien doesn't grant.
• At maxLifetimeSeconds, AWS terminates the MicroVM even if a command is running. That command fails with SANDBOX_OUTCOME_UNKNOWN.
• AWS keeps a suspended MicroVM for up to 8 hours.

GCPCopy Anchor Link

Gemini Enterprise Agent Platform sandboxes. Alien creates an Agent Platform instance and a sandbox template for each Sandbox resource.

• Google requires the Agent Sandbox service agent (service-PROJECT_NUMBER@gcp-sa-vertex-sandbox.iam.gserviceaccount.com) to have Artifact Registry Reader on the image's repository, and the image must not require root.
• A sandbox that goes over its cpu or memory ceiling is terminated. disk isn't applied.
• At maxLifetimeSeconds, the sandbox is terminated even if a command is running.
• Google documents a TTL of 7 days for a custom-container sandbox.

AzureCopy Anchor Link

Azure Container Apps Sandboxes, in one sandbox group per Sandbox resource.

• Ceilings follow the sizing rule and are enforced inside the sandbox: going over the memory ceiling raises an out-of-memory error there.
• If a sandbox starts without its egress policy, the binding raises SANDBOX_NOT_AS_DECLARED.
• The image needs sh, setsid, od, tr, sleep, and kill, which Alien uses to enforce command timeouts.
• Pausing during a command deletes the sandbox once the command's timeout passes.
• There is no lifetime ceiling, so terminate sandboxes when you're done with them.
• No preview: an Azure sandbox port is either public or behind an interactive sign-in, and neither can be limited to one port.

Kubernetes / On-PremCopy Anchor Link

Pods under a sandboxed RuntimeClass.

• The cluster needs a RuntimeClass named gvisor with a sandboxed handler (gvisor, runsc, kata, kata-containers, or kata-qemu).
• Pods run as a non-root user with no Linux capabilities, a read-only root filesystem, and no service account token.
• Each Sandbox resource keeps 2 idle pods ready. When none is idle, create fails until the pool refills.
• Egress uses a NetworkPolicy, which only works if the cluster's CNI enforces NetworkPolicy.
• Only the process that created a sandbox can reach it.

LocalCopy Anchor Link

Docker containers, which share the host kernel. Use Local for development, not to isolate hostile code.

• Containers run as a non-root user with no Linux capabilities and a read-only root filesystem. The only writable path is /sandbox, which can't run executables directly, so run scripts through their interpreter (python3 script.py).
• deny gives the container no network, so it can't be combined with previewPorts.
• Preview ports are published on 127.0.0.1 only.
• The image needs sh, setsid, od, tr, sleep, and kill, which Alien uses to enforce command timeouts.

Design DecisionsCopy Anchor Link

Only create, run, and terminate need no capability. Every other operation is a named capability, because at least one platform lacks it or reaches it differently. Code that runs on several platforms checks capabilities() first instead of finding out from an error.

A refused declaration beats an ignored one. A ceiling a platform cannot enforce would give you a sandbox that looks bounded and is not. Alien refuses it at plan time instead.

Limits are ceilings, not requests. On AWS, Alien sizes a MicroVM by the peak it can burst to, not its baseline, so a declared ceiling is never exceeded. A declaration no size fits is refused rather than rounded up.

Sandboxes are frozen by default. Customer setup provisions the Sandbox resource on every platform. Only AWS can rebuild it during a rollout, which is what "live" needs.

A remotely published sandbox must allow egress. The grant behind a Remote binding cannot carry a declared egress policy or port list, so a remotely published sandbox must declare allow and no previewPorts.