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.
| Operation | AWS | Google Cloud | Azure | Kubernetes | Local |
|---|---|---|---|---|---|
| Create, run, terminate | Yes | Yes | Yes | Yes | Yes |
| Read and write files | Yes | Yes | Yes | Yes | Yes |
Reconnect with get | Yes | Yes | Yes | Yes | Yes |
list | No | Yes | No | Creating process only | Yes |
| Jobs | Yes | Yes | Agent images only | Yes | No |
| Pause and resume | Yes | No | Yes. Memory and running processes are kept. | No | No |
| Preview ports | Declared ports, credentials last 30 minutes | Declared ports, callers that can run commands in the sandbox, credentials last at most 5 minutes | Agent images only. Declared ports, credentials last at most 15 minutes. | Declared ports, in-cluster callers only, credentials last at most 15 minutes | Declared ports on 127.0.0.1, no expiry |
| Runtime egress policies | Yes | No | No | Yes | No |
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
| Option | AWS | Google Cloud | Azure | Kubernetes | Local |
|---|---|---|---|---|---|
sandboxId | Ignored | Display name only | Ignored | Used | Used |
env | Refused | Refused | Validated | Ignored | Ignored |
tenantKey | Refused | Refused | Refused | Ignored | Ignored |
timeoutMs | Shortens lifetime | Shortens lifetime | Shortens lifetime | Shortens lifetime of a new sandbox | Refused, 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
| Platform | maxLifetimeSeconds | Pause behavior |
|---|---|---|
| AWS | 1 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 Cloud | Any positive value. The provider sets the upper bound. | No state-preserving pause. |
| Azure | Any 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. |
| Kubernetes | 1 to 2,147,483,647. Counts from when your app claims the pod, not from pod start. | No pause. |
| Local | Refused | No 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
| Limit | AWS | Google Cloud | Azure | Kubernetes | Local |
|---|---|---|---|---|---|
| CPU and memory | MicroVM size | Enforced by terminating the sandbox | Sizing rule | Pod resource limits | Docker limits |
| Disk | MicroVM size | Ephemeral storage limit, at most 10 GiB | At most 20 GiB per core | Ephemeral storage limit | /sandbox size limit |
maxProcesses | Refused | Refused | Refused | Refused | Supported |
| Output per stream | 4 MiB | 4 MiB | 4 MiB. Native: no truncation flag. | 4 MiB | Not capped |
| File size | 32 MiB | 32 MiB | 32 MiB. Native: provider limits. | 32 MiB | Not capped |
| Jobs per sandbox | 16 | 16 | 16. Native: unsupported. | 16 | Unsupported |
| Command timeout | Required | Required | Required. Native: at most 24 hours. | Required | Required, at most 24 hours |
| Create readiness wait | 60 s | Up to 660 s across three stages | 120 s for the provider, then up to 60 s for the agent | Warm-pool claim | Container start |
| Limit | Value |
|---|---|
| AWS Sandbox resource id | At most 17 characters, or 16 with .egress("none") |
| Egress policy size | 4,096 targets and 256 KiB of canonical JSON |
| Gateway clock skew | SDK at most 60 seconds ahead of the gateway |
| Gateway identity token | At most 24 hours |
| Kubernetes warm pool | 2 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 memory | Peak memory | Peak CPU | Disk |
|---|---|---|---|
| 512 MiB | 2 GiB | 1 | 8 GiB |
| 1 GiB | 4 GiB | 2 | 8 GiB |
| 2 GiB | 8 GiB | 4 | 8 GiB |
| 4 GiB | 16 GiB | 8 | 16 GiB |
| 8 GiB | 32 GiB | 16 | 32 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
| Platform | Path resolution | Refused path error |
|---|---|---|
| AWS, Google Cloud, Kubernetes | Under /sandbox. A leading / means /sandbox. ., .., and symlinks are refused. | SANDBOX_COMMAND_FAILED |
| Azure agent | Under /sandbox. A leading / means /sandbox. ., .., and symlinks are refused. | INVALID_INPUT for binding checks, SANDBOX_COMMAND_FAILED for agent refusals |
| Azure native | A leading / is removed and .. is refused. Azure resolves the rest. | INVALID_INPUT before sending files |
| Local | Under /sandbox. A leading / means /sandbox. .. is refused. Symlinks aren't checked. | OPERATION_NOT_SUPPORTED |
Egress
Modes
| Declaration | Behavior |
|---|---|
.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 setup | Supported | A deployment compute cluster and private sandbox subnets. For an existing VPC, supply SandboxSubnetIds, SandboxGatewaySubnetIds, and SandboxGatewaySubnetCidrs. |
| AWS, direct deploy | Supported | A new VPC created by the deployment. Default and existing VPCs are refused. |
| Kubernetes | Supported | A sandboxed RuntimeClass and a CNI that passes the NetworkPolicy probe. |
| Azure, Google Cloud, Local | Refused at plan time | No 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".
| Policy | Allows |
|---|---|
"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:
| Target | Example | Matches |
|---|---|---|
| Hostname | api.example.com | That host |
| Wildcard hostname | *.example.org | example.org and every subdomain |
| IPv4 address | 203.0.113.10 | That address |
| IPv4 CIDR | 198.51.100.0/24 | That range |
| Any of the above with a port | api.example.com:443 | Only 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
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.
| Value | AWS | Google Cloud | Azure | Kubernetes | Local |
|---|---|---|---|---|---|
{ 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 excluded | Docker bridge. Container isolation depends on the runtime honoring enable_icc. |
{ mode: "allowDomains", domains } | Saved privilegedSupervisor declarations only: exact hostnames through an in-guest filter | Refused | Native hostname filter. DNS lookups can still escape. | Refused | Refused |
{ 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, thenSIGKILL2 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
ENTRYPOINTorCMDhas 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 failure | Fix |
|---|---|
SANDBOX_IMAGE_USER_INVALID: non-root UID with group 0 | Set 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/passwd | Add the account, or use a numeric UID and GID. |
BUILD_CONFIG_INVALID: USER differs across architectures | Use 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
| Platform | Initial setup and image updates |
|---|---|
| AWS | Source 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 Cloud | A release can replace a frozen Sandbox's image. |
| Azure | A release can replace a frozen Sandbox's image. Automatic setup refuses Sandbox resources. |
| Kubernetes, Local | The 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:
| Platform | Saved image behavior |
|---|---|
| AWS | Ordinary 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 Cloud | The agent and commands share one non-root UID. There's no separate startup process. |
| Azure native | Startup and exec use the image USER, which may be root. |
| Kubernetes | UID 65534 startup is unchanged. |
| Local | A 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
imageUserfield 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
| Situation | Error or result | Action |
|---|---|---|
| Command or job may have run | SANDBOX_OUTCOME_UNKNOWN | Check its effects before repeating it. |
| Command timeout | SANDBOX_COMMAND_FAILED, or SANDBOX_OUTCOME_UNKNOWN if the stop can't be confirmed | Don't assume there were no effects. |
| Sandbox reached its lifetime mid-command (AWS, Google Cloud) | SANDBOX_OUTCOME_UNKNOWN | Size the lifetime for the longest command. |
| AWS or Google Cloud create readiness failure | SANDBOX_UNREACHABLE | A retry can create a second sandbox. |
| Azure image still building | SANDBOX_UNREACHABLE | Retry after the image is ready. |
| Azure create response lost | SANDBOX_OUTCOME_UNKNOWN | Creation may have succeeded. |
| Azure provider readiness timeout | SANDBOX_COMMAND_FAILED | Inspect the failure before creating again. |
Azure agent reports PATH_NOT_FOUND or JOB_NOT_FOUND | SANDBOX_COMMAND_FAILED | Correct the path or job id. The binding doesn't retry. |
| Azure agent readiness timeout | SANDBOX_UNREACHABLE | Check the image startup before retrying. |
| Azure effective egress differs | SANDBOX_NOT_AS_DECLARED | Creation fails. Investigate the policy. |
| Google Cloud file transport failure | SANDBOX_COMMAND_FAILED | Diagnose connectivity. This isn't a path check. |
| AWS agent outbound path check fails | EGRESS_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 failure | OPERATION_NOT_SUPPORTED | Check service reachability and the current process's sandbox claim. |
| Kubernetes pods never pass their network check | OPERATION_NOT_SUPPORTED, saying the cluster may not enforce NetworkPolicy | Use a network plugin that enforces NetworkPolicy. |
| Unsupported operation or option | OPERATION_NOT_SUPPORTED | Check capabilities() and options. |
| Invalid request, including a zero lifetime | INVALID_INPUT | Correct 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.