AWS EC2
AWS EC2 provider for ComputeSDK. Each sandbox is one EC2 instance launched from your launch template, on-demand by default or Spot when you opt in. Commands run over SSM Run Command (AWS-RunShellScript). There is no agent or gateway on the box and no inbound ports: the preinstalled SSM agent dials out.
Installation
npm install @computesdk/awsUsage
import { ec2 } from '@computesdk/aws/ec2';
// On-demand, everything else comes from the launch template
const compute = ec2({ launchTemplate: 'my-template' }); // region from AWS_REGION
const sandbox = await compute.sandbox.create();
const result = await sandbox.runCommand('node -v', { env: { CI: '1' }, cwd: '/tmp', timeout: 60_000 });
console.log(result.exitCode, result.stdout);
await sandbox.destroy();Spot
import { ec2, isEc2CapacityError } from '@computesdk/aws/ec2';
const compute = ec2({
region: 'us-east-2',
launchTemplate: 'computesdk-market-medium',
instanceType: [
'c5d.large', 'm7a.large', 'c6in.large', 'r5a.large', 'm5a.large', 'r5ad.large', 'r5b.large',
'r5n.large', 'c5a.large', 'r6a.large', 'm5ad.large', 'r6in.large', 'm6in.large',
],
spot: { maxPricePerHour: '0.05' },
});
try {
const sandbox = await compute.sandbox.create({ name: 'bench-1', metadata: { listing: 'lst_42' } });
} catch (error) {
if (isEc2CapacityError(error)) console.log('No Spot capacity right now:', error.codes);
else throw error;
}Configuration
launchTemplate
yes
Launch template name or id (lt-...)
region
no
AWS region; falls back to AWS_REGION
instanceType
no
One type, or a list to fall back across. Default: the launch template's
subnetIds
no
Subnets to fall back across, one per AZ. Default: the launch template's
spot
no
true or { maxPricePerHour } for Spot. Default: on-demand
credentials
no
AwsCredentialIdentity or AwsCredentialIdentityProvider. Default: AWS SDK credential chain
launchTemplateVersion
no
Default $Default
Advanced: readyTimeoutMs (default 120000), pollIntervalMs (default 2000), maxOutputBytes (default 4 MiB), outputS3Bucket / outputS3KeyPrefix (see large output below).
The launch template owns the AMI, IMDS settings, root volume, security group, networking, and an instance profile that allows SSM. The provider never sets those.
A plain on-demand launch (at most one instanceType, no subnetIds) is a single RunInstances call. Spot, several instance types, or subnetIds use an instant EC2 Fleet over every type × subnet pair (price-capacity-optimized for Spot).
If your launch template doesn't pin a subnet, pass subnetIds; otherwise AWS falls back to the default VPC.
Credentials
There are no API keys in config. Pass a credential provider for short-lived credentials, e.g. on Vercel with OIDC:
Behavior
Sandbox ID is the EC2 instance ID.
Tags: instances and volumes are tagged
computesdk:managed=true(IAM policies can be conditioned on it),computesdk:sandbox-namewhennameis set, and every stringmetadatavalue (sanitized to EC2 tag limits, max 50 tags).Capacity: when no instance launches because of capacity, price, or quota errors,
createthrowsEc2CapacityError(code: 'AWS_EC2_CAPACITY_UNAVAILABLE',codes,errors). Other fleet failures throwEc2FleetError.Readiness:
createreturns once the instance isOnlinein SSM. On timeout (Ec2ReadyTimeoutError) or any error the instance is terminated before throwing.create({ timeout })overridesreadyTimeoutMs.Commands run as root via
AWS-RunShellScript.envis exported andcwdis entered in the same script;timeoutmaps to SSMexecutionTimeout(seconds, rounded up). Timed-out commands return exit code124.Large output: SSM returns at most 24,000 characters of stdout and 8,000 of stderr inline. Larger output is written to
/tmp/computesdk-ssm/on the instance and read back in ~17 KB chunks (a few SSM calls in parallel, then deleted), so it arrives complete but slower: roughly 15–30 s per MB. Each stream keeps its lastmaxOutputBytes(default 4 MiB) and stderr notes any cut. For big output, setoutputS3Bucket(the instance profile needss3:PutObjectand the callers3:GetObject): SSM writes full output there and it is fetched in one request.getByIdreturnsnullfor unknown, terminated/shutting-down, or untagged instances.listreturns managedpending/runninginstances.destroyis idempotent and refuses to terminate untagged instances.getInstance()/getInfo().metadataexpose instance type, AZ, subnet, lifecycle (spot/on-demand), and launch time.Not supported:
getUrl(no inbound traffic) and the filesystem API.
Testing
Last updated
Was this helpful?