Docs

Sandbox behavior and limits

What a Sandbox guarantees, which operations and options each platform supports, and the limits, lifetimes, egress rules, and errors your app has to handle.

Guarantees

Declared limits are enforced or refused. Limits are ceilings, not scheduling hints. A platform that can't enforce one, such as maxProcesses outside Local or maxLifetimeSeconds on Local, refuses the stack at plan time instead of ignoring it.

Unsupported operations raise. Calling an operation the platform lacks raises OPERATION_NOT_SUPPORTED. Call capabilities() to branch before calling.

Create waits for readiness. create returns only when the sandbox can run a command.

Timeouts mean the command stopped. A command timeout is reported only after the command's process group has verifiably stopped. A timeout that leaves untrusted code running is never reported as a timeout.

Egress enforcement is outside the sandbox. Gateway policies and provider network rules run outside the guest. Code inside, including root, can't widen them. A gateway failure never falls back to direct internet access.

No cloud credentials in the guest. Alien attaches no cloud identity to a sandbox. See Instance metadata.

Not guaranteed: create and getOrCreate aren't idempotent. A retried create can make a second sandbox, and two concurrent getOrCreate calls for one id can both create one. On Azure, getOrCreate with a sandboxId finds a sandbox an earlier call made for that id, and concurrent calls end with one sandbox.

Operations by platform

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

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

OperationAWSGoogle CloudAzureKubernetesLocal
Create, run, terminateYesYesYesYesYes
Read and write filesYesYesYesYesYes
Reconnect with getYesYesYesYesYes
listNoYesNoCreating process onlyYes
JobsYesYesAgent images onlyYesNo
Pause and resumeYesNoYes. Memory and running processes are kept.NoNo
Preview portsDeclared ports, credentials last 30 minutesDeclared ports, callers that can run commands in the sandbox, credentials last at most 5 minutesAgent images only. Declared ports, credentials last at most 15 minutes.Declared ports, in-cluster callers only, credentials last at most 15 minutesDeclared ports on 127.0.0.1, no expiry
Runtime egress policiesYesNoNoYesNo

AWS and Azure report preview only when ports are declared. On Kubernetes, get asks the cluster each time, so it sees a sandbox another process terminated, and it waits while another process is still setting a sandbox up.

On Azure, pause keeps the sandbox's memory and running processes, with or without idlePauseSeconds. A pause takes about 2.5 seconds plus about 2.3 seconds per GiB of memory in use (about 15 seconds at 6 GiB), and resume takes about 1 second.

Google Cloud's resume can return a fresh container, so Google Cloud doesn't offer pause. No platform reports snapshot.

Create options by platform

OptionAWSGoogle CloudAzureKubernetesLocal
sandboxIdIgnoredDisplay name onlyIgnoredUsedUsed
envRefusedRefusedValidatedIgnoredIgnored
tenantKeyRefusedRefusedRefusedIgnoredIgnored
timeoutMsShortens lifetimeShortens lifetimeShortens lifetimeShortens lifetime of a new sandboxRefused, including reuse

Use command-level env for portable code. Azure refuses create-time PATH, IFS, SHELLOPTS, BASHOPTS, LD_*, and invalid shell variable names, because the timeout wrapper resolves its tools through them. Agent images also reserve ALIEN_SANDBOX_*.

Lifetime

PlatformmaxLifetimeSecondsPause behavior
AWS1 to 28,800. Sessions are capped at 8 hours even without it.The in-guest command timeout stops while paused. A waiting command call can still time out.
Google CloudAny positive value. The provider sets the upper bound.No state-preserving pause.
AzureAny positive value. Alien deletes the sandbox after the deadline and refuses calls to it.Agent commands use in-guest timeouts. Native commands can trigger sandbox deletion 10 seconds after their timeout.
Kubernetes1 to 2,147,483,647. Counts from when your app claims the pod, not from pod start.No pause.
LocalRefusedNo pause.

A create-time timeoutMs can't extend the declared lifetime. Without a declared lifetime, AWS still caps sessions at 8 hours and Google Cloud applies its service default. An Azure sandbox without a deadline runs until it's terminated. Always terminate sandboxes after saving their results.

idlePauseSeconds pauses an idle sandbox where the platform supports pause.

AWS resume waits until commands can run and refuses a terminated sandbox. AWS, Google Cloud, and Azure terminate wait for deletion. Kubernetes terminate deletes only sandboxes claimed by the current process.

Limits

LimitAWSGoogle CloudAzureKubernetesLocal
CPU and memoryMicroVM sizeEnforced by terminating the sandboxSizing rulePod resource limitsDocker limits
DiskMicroVM sizeEphemeral storage limit, at most 10 GiBAt most 20 GiB per coreEphemeral storage limit/sandbox size limit
maxProcessesRefusedRefusedRefusedRefusedSupported
Output per stream4 MiB4 MiB4 MiB. Native: no truncation flag.4 MiBNot capped
File size32 MiB32 MiB32 MiB. Native: provider limits.32 MiBNot capped
Jobs per sandbox161616. Native: unsupported.16Unsupported
Command timeoutRequiredRequiredRequired. Native: at most 24 hours.RequiredRequired, at most 24 hours
Create readiness wait60 sUp to 660 s across three stages120 s for the provider, then up to 60 s for the agentWarm-pool claimContainer start
LimitValue
AWS Sandbox resource idAt most 17 characters, or 16 with .egress("none")
Egress policy size4,096 targets and 256 KiB of canonical JSON
Gateway clock skewSDK at most 60 seconds ahead of the gateway
Gateway identity tokenAt most 24 hours
Kubernetes warm pool2 idle pods per Sandbox resource

Output beyond the cap is dropped, and the exit frame reports truncated: true. A finished job counts toward the 16 until a poll reads its result. Google Cloud runs commands longer than 30 seconds through its jobs API.

Kubernetes idle pods reserve the declared CPU and memory. A create fails while the pool is empty.

A Kubernetes pod is handed to a sandbox only after its NetworkPolicy is proven in force. On a cluster that doesn't enforce NetworkPolicy, pods never become ready, and create fails with an error that says so.

AWS sizes

A Lambda MicroVM bursts to four times its baseline, and AWS has no setting to cap that. Alien therefore picks the largest size whose peak memory and disk fit inside your declared ceilings, then checks that the declared CPU covers that size's peak CPU.

Baseline memoryPeak memoryPeak CPUDisk
512 MiB2 GiB18 GiB
1 GiB4 GiB28 GiB
2 GiB8 GiB48 GiB
4 GiB16 GiB816 GiB
8 GiB32 GiB1632 GiB

Without .limits(), the 2 GiB baseline size is used. The smallest accepted declaration is cpu: "1", memory: "2Gi", disk: "8Gi". A declaration no size fits is refused rather than rounded.

CPU doesn't choose the size. AWS couples CPU to memory, so a low CPU ceiling with a high memory ceiling is refused instead of silently giving you a smaller machine.

Azure sizes

CPU is a multiple of 250m, from 250m to 16 cores. A value such as 333m is refused even though it's in range.

Memory is at most 2 GiB per declared core, and disk at most 20 GiB per declared core. Limits are enforced inside the sandbox: an over-allocation raises MemoryError in the guest while the sandbox keeps running.

Files by platform

PlatformPath resolutionRefused path error
AWS, Google Cloud, KubernetesUnder /sandbox. A leading / means /sandbox. ., .., and symlinks are refused.SANDBOX_COMMAND_FAILED
Azure agentUnder /sandbox. A leading / means /sandbox. ., .., and symlinks are refused.INVALID_INPUT for binding checks, SANDBOX_COMMAND_FAILED for agent refusals
Azure nativeA leading / is removed and .. is refused. Azure resolves the rest.INVALID_INPUT before sending files
LocalUnder /sandbox. A leading / means /sandbox. .. is refused. Symlinks aren't checked.OPERATION_NOT_SUPPORTED

Egress

Modes

DeclarationBehavior
.egress("none")No outbound connections. No gateway.
.egress("internet")Outbound traffic through the deployment's egress gateway, with per-sandbox policies, public-destination checks, and a fixed outbound IP on AWS networks Alien creates.
Platform"internet"Requirements
AWS, CloudFormation or Terraform setupSupportedA deployment compute cluster and private sandbox subnets. For an existing VPC, supply SandboxSubnetIds, SandboxGatewaySubnetIds, and SandboxGatewaySubnetCidrs.
AWS, direct deploySupportedA new VPC created by the deployment. Default and existing VPCs are refused.
KubernetesSupportedA sandboxed RuntimeClass and a CNI that passes the NetworkPolicy probe.
Azure, Google Cloud, LocalRefused at plan timeNo deployment gateway.

Unsupported platforms report SANDBOX_EGRESS_GATEWAY_UNAVAILABLE. They don't fall back to direct internet access.

On Kubernetes, sandboxes reach only gateway pods on TCP port 3128 and need no DNS exception. The cluster's network decides the outbound IP. Alien doesn't allocate a fixed NAT IP there.

Allowlists

Pass egress to create or getOrCreate. Without it, .defaultPolicy() applies, and without that the policy is "internet".

PolicyAllows
"internet"Public hostnames. Literal IP addresses need an explicit entry.
{ allow: [...] }Only the listed targets.
{ allow: [] }No new outbound connections.

A target is one of:

TargetExampleMatches
Hostnameapi.example.comThat host
Wildcard hostname*.example.orgexample.org and every subdomain
IPv4 address203.0.113.10That address
IPv4 CIDR198.51.100.0/24That range
Any of the above with a portapi.example.com:443Only that port (1 to 65535)

Hostnames are matched against the TLS SNI or the HTTP Host header, so other protocols need an IP or CIDR target.

  • Private, link-local, and metadata addresses are refused, as are * and public suffixes.
  • IPv6 destinations aren't supported.
  • Targets are lowercased and canonicalized before they're stored.

The gateway can't see what an allowed service forwards elsewhere. Allow only services you trust, and keep wildcards narrow.

Changing a policy

src/run.ts
await box.updateEgress(sandboxId, { allow: ["api.example.com"] })

This works on running sandboxes and on paused AWS sandboxes. New connections use the new policy when the call returns. Open connections to destinations that are no longer allowed close within about 30 seconds.

Pass "internet" to restore the public-hostname policy.

getOrCreate with an explicit egress also updates an existing sandbox. Omitting it keeps the existing policy, so set the policy each time you hand a sandbox new work.

Mail ports

Ports 25, 465, and 587 are blocked for "internet" and for targets without a port. For TLS-first mail, allow the host and port, such as smtp.example.com:465. Plaintext SMTP and STARTTLS need an IP or CIDR entry with an explicit port, such as "<public-mail-server-ip>:587".

Sandboxes share an outbound IP. Mail abuse from one sandbox can get that address blocklisted for every other one.

Outbound IP

On AWS networks created by Alien, gateway traffic leaves through the deployment's NAT with a fixed IP, shown as Outbound IP on the deployment page. On an existing network or Kubernetes, the network administrator decides the outbound addresses.

Gateway

The deployment runs two gateway replicas with 0.25 vCPU and 512 MiB each, even when no sandbox runs.

  • Port 3128 carries traffic; port 3129 takes signed policy updates. Sandboxes can reach only port 3128.
  • Each release pins the gateway image by digest.
  • AWS puts the replicas behind an internal load balancer. Kubernetes uses a cluster Service.

Policies are signed records held in memory, with no database. A policy write replicates to the replicas before it returns, and a sandbox without a policy record has no gateway access.

Policy storage uses half the gateway's memory limit, normally 256 MiB per replica. A full store refuses writes with SANDBOX_EGRESS_POLICY_STORE_FULL and never evicts existing policies.

See Gateway for identity tokens, signing keys, and failure behavior.

Older egress values

Object values still work and keep their original cloud behavior. They don't use the gateway, fixed IP, or runtime allowlists.

ValueAWSGoogle CloudAzureKubernetesLocal
{ mode: "deny" }Same as "none"Same as "none"Same as "none"Same as "none"Same as "none"
{ mode: "allow" }Direct cloud internet path. Explicit root USER refused.Direct internet. Private ranges aren't excluded.Direct internet. Private ranges aren't excluded.DNS through kube-dns, private and special-use destinations excludedDocker bridge. Container isolation depends on the runtime honoring enable_icc.
{ mode: "allowDomains", domains }Saved privilegedSupervisor declarations only: exact hostnames through an in-guest filterRefusedNative hostname filter. DNS lookups can still escape.RefusedRefused

{ mode: "allow" } is required for remote sandboxes. An allowDomains list with no domains is refused, because it denies everything while reading like an allowlist.

To move to the gateway, change the declaration to .egress("internet") and rerun initial setup once. The plan lists the gateway and network resources it adds. Then pass allowlists to create or getOrCreate.

Image startup

On AWS, Google Cloud, and Azure agent images, Alien keeps the image's ENTRYPOINT and CMD and starts it once per sandbox boot, as the image USER, before accepting commands.

  • Alien doesn't wait for the process to be ready and doesn't restart it after exit. The sandbox keeps running after it exits. Use a supervisor if you need either.
  • Its stdout and stderr go to the agent output. Its stdin is /dev/null. The SDK has no API for its status or exit code.
  • If it can't start, Alien doesn't retry during that boot. On Google Cloud the agent then exits. On Azure, creation fails the readiness check.
  • On shutdown, its process group gets SIGTERM, then SIGKILL 2 seconds later. When the agent is PID 1, it also reaps orphaned processes.
  • Resuming the same sandbox doesn't start another copy. A fresh container is a new boot.
  • An image without ENTRYPOINT or CMD has no startup process.

On AWS, an image without USER keeps the earlier startup behavior when the sandbox has no egress connector. Kubernetes runs the supplied image, which must start the agent itself. Local replaces the image command with a keepalive shell.

Environment

The startup process gets HOME from its UID's passwd entry, or / if there is none, and HOSTNAME from the container. Image or create-time values can override both.

Alien sets ALIEN_SANDBOX_EXEC_UID and ALIEN_SANDBOX_EXEC_GID after the image environment, and ALIEN_SANDBOX_ROOT when the agent has it. Gateway mode overrides proxy variables, NO_PROXY, and CA bundle variables such as SSL_CERT_FILE.

A supervisor should pass these to its workers. See Environment variables.

Image user errors

Builds inspect the image's USER, except native Azure catalog builds.

Build failureFix
SANDBOX_IMAGE_USER_INVALID: non-root UID with group 0Set a non-root group, such as USER 65534:65534. USER 1000 without a passwd entry defaults to group 0, and USER app:root also fails.
SANDBOX_IMAGE_USER_INVALID: user name missing from /etc/passwdAdd the account, or use a numeric UID and GID.
BUILD_CONFIG_INVALID: USER differs across architecturesUse the same UID in each architecture's image.

Local refuses an explicit root USER, including names that resolve to UID 0. Kubernetes accepts one only with "internet" or "none" egress.

Local builds reuse a cached image only when its OS and architecture match the target. A mismatched immutable image id fails with IMAGE_BUILD_REJECTED. Use a matching image or a registry tag.

Initial setup and updates

PlatformInitial setup and image updates
AWSSource builds and private base images require "live", because private ECR access is granted after the deployment registers. A frozen Sandbox stays owned by initial setup.
Google CloudA release can replace a frozen Sandbox's image.
AzureA release can replace a frozen Sandbox's image. Automatic setup refuses Sandbox resources.
Kubernetes, LocalThe frozen configuration belongs to initial setup.

Only AWS provisions a Sandbox at runtime, so "live" is refused on every other platform. A live Sandbox's setup inputs (egress, network, build role policy, remote grant) can't change during an update.

A Worker, Container, or Daemon can link a live Sandbox. Other resources, including Build, need it frozen. A Build can't link an "internet" Sandbox, because gateway administration is private to workloads.

AWS image versions

Each release that changes an AWS sandbox image adds a version of it, and AWS keeps at most 50 versions per image. Alien keeps the serving version and the one it replaced. It stops new sessions on older versions, then deletes each one 8 hours 30 minutes later, once AWS has ended every session that could still use it. Running and paused sandboxes keep working.

Retiring versions needs lambda:UpdateMicrovmImageVersion, part of sandbox/provision. Deployments installed before this permission get it when the customer's admin reruns initial setup. Until then, Alien keeps every version and logs a warning at most every 6 hours. Releases keep working until the image reaches 50 versions.

Saved releases

Releases built before the image-user contract keep their behavior until you rebuild them:

PlatformSaved image behavior
AWSOrdinary bundles may replace the image command. Gateway and legacy supervisor bundles start it as the command UID. S3 bundle declarations stay on this path.
Google CloudThe agent and commands share one non-root UID. There's no separate startup process.
Azure nativeStartup and exec use the image USER, which may be root.
KubernetesUID 65534 startup is unchanged.
LocalA root or absent-USER image runs commands as UID 65534.

Rebuild from the original OCI base to adopt image-user startup. Declarations saved with privilegedSupervisor stay readable. Set the image USER instead when you rebuild, and use "internet" or "none" egress, because a rebuilt root image with that setting fails AWS preflight.

When you upgrade:

  • Upgrade managers and Operators before publishing releases built with the image-user contract. Older readers reject the imageUser field these releases carry.
  • Upgrade the app's SDK together with managers before publishing Azure agent images, because older clients can't speak the agent transport.
  • Before rolling back a manager, restore a release it can read.

Errors and retries

SituationError or resultAction
Command or job may have runSANDBOX_OUTCOME_UNKNOWNCheck its effects before repeating it.
Command timeoutSANDBOX_COMMAND_FAILED, or SANDBOX_OUTCOME_UNKNOWN if the stop can't be confirmedDon't assume there were no effects.
Sandbox reached its lifetime mid-command (AWS, Google Cloud)SANDBOX_OUTCOME_UNKNOWNSize the lifetime for the longest command.
AWS or Google Cloud create readiness failureSANDBOX_UNREACHABLEA retry can create a second sandbox.
Azure image still buildingSANDBOX_UNREACHABLERetry after the image is ready.
Azure create response lostSANDBOX_OUTCOME_UNKNOWNCreation may have succeeded.
Azure provider readiness timeoutSANDBOX_COMMAND_FAILEDInspect the failure before creating again.
Azure agent reports PATH_NOT_FOUND or JOB_NOT_FOUNDSANDBOX_COMMAND_FAILEDCorrect the path or job id. The binding doesn't retry.
Azure agent readiness timeoutSANDBOX_UNREACHABLECheck the image startup before retrying.
Azure effective egress differsSANDBOX_NOT_AS_DECLAREDCreation fails. Investigate the policy.
Google Cloud file transport failureSANDBOX_COMMAND_FAILEDDiagnose connectivity. This isn't a path check.
AWS agent outbound path check failsEGRESS_PATH_UNEXPECTED. The message names the failed check and its cause.The sandbox's network doesn't match its declaration.
Local route or Kubernetes broker failureOPERATION_NOT_SUPPORTEDCheck service reachability and the current process's sandbox claim.
Kubernetes pods never pass their network checkOPERATION_NOT_SUPPORTED, saying the cluster may not enforce NetworkPolicyUse a network plugin that enforces NetworkPolicy.
Unsupported operation or optionOPERATION_NOT_SUPPORTEDCheck capabilities() and options.
Invalid request, including a zero lifetimeINVALID_INPUTCorrect the request.

A failed create can leave a sandbox behind without returning its id. AWS can't list sandboxes, and Google Cloud lists them without saying which caller created each one.

In TypeScript, isSandboxOutcomeUnknown(error) from @alienplatform/bindings matches SANDBOX_OUTCOME_UNKNOWN even inside a wrapped error.

Plan-time refusals appear inside VALIDATION_FAILED messages, not as an error's code. They include SANDBOX_PLATFORM_UNSUPPORTED (the platform has no Sandbox backend, such as Machines), SANDBOX_CAPABILITY_UNSUPPORTED, SANDBOX_LIMIT_INVALID, and SANDBOX_EGRESS_GATEWAY_UNAVAILABLE.

Design decisions

Limits are refused, not clamped. A stack that declares a limit the platform ignores reads as bounded while the sandbox isn't. Refusing at plan time keeps the declaration honest.

AWS sizes by peak, not baseline. Picking the size whose baseline matches your memory ceiling would let the MicroVM burst to four times that ceiling.

Command timeouts are required. A default timeout is a hang waiting for a slow day, in a sandbox running code you don't control.

Capabilities are published. Each platform lacks something. Publishing the set lets portable code branch before calling instead of discovering a gap through an error.

Preview ports are declared up front. Your app reaches its sandbox through the provider, so it can't widen its own ingress at runtime.

No list on AWS and Azure. Enumerating there needs an account-wide grant that the sandbox role withholds on purpose.

On this page