EC2 CIAB Runtime

The EC2 runtime starts a fresh EC2 instance for each coding-agent session, gives it a provisioned AMI with your toolchain, runs the agent, and terminates on idle. Strong isolation, real cost controls, suitable for production and multi-tenant.

Prerequisites

• AWS account reachable from the API host.
• IAM role or access key that can RunInstances, TerminateInstances, CreateTags, DescribeInstances, DescribeVpcs, DescribeSubnets, DescribeSecurityGroups.
• A VPC with at least one subnet and a security group that allows outbound HTTPS.
• A pre-built AMI with the coding-agent binary and your preferred toolchain.

Configure

AGENTCY_FEATURES_CIAB=true
CIAB_RUNTIME=ec2

# AWS
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=…        # or use instance profile / assume role
AWS_SECRET_ACCESS_KEY=…

# EC2 launch template
CIAB_EC2_AMI_ID=ami-0abc123
CIAB_EC2_INSTANCE_TYPE=t4g.small
CIAB_EC2_SUBNET_ID=subnet-…
CIAB_EC2_SECURITY_GROUP_IDS=sg-…,sg-…
CIAB_EC2_IAM_INSTANCE_PROFILE=arn:aws:iam::1234:instance-profile/agentcy-ciab
CIAB_EC2_VOLUME_SIZE_GB=40
CIAB_EC2_SPOT=true          # use spot; Agentcy retries on interruption

# Cost guardrails
CIAB_EC2_MAX_RUNTIME_MINUTES=90
CIAB_EC2_MAX_HOURLY_USD=5
CIAB_SESSION_IDLE_TIMEOUT=600

AMI setup

A minimal AMI:

# On a vanilla Ubuntu 24.04 base
apt-get update && apt-get install -y \
  build-essential git curl jq ripgrep \
  python3 python3-pip nodejs npm \
  ca-certificates openssh-server
npm install -g @anthropic-ai/claude-code
useradd -m -s /bin/bash ciab
mkdir /home/ciab/work && chown ciab:ciab /home/ciab/work

Install the bootstrap service — it runs on instance start, fetches session config from a signed S3 URL, and exposes port forwarding back to Agentcy:

# /etc/systemd/system/agentcy-ciab.service
[Unit]
Description=Agentcy CIAB bootstrap
After=network.target

[Service]
ExecStart=/usr/local/bin/agentcy-ciab-bootstrap
User=ciab
Restart=on-failure

[Install]
WantedBy=multi-user.target

agentcy-ciab-bootstrap is provided by agentcy-ciab-client — cross-compile with cargo build --release -p agentcy-ciab-client --bin agentcy-ciab-bootstrap and bake into the AMI.

What happens on session start

1. API creates a session row with runtime: ec2, state: pending.
2. API calls RunInstances with user-data containing a signed S3 URL to the session config (seed repo, env vars, agent prompt).
3. Instance boots, the agentcy-ciab-bootstrap service:
   • Downloads the session config.
   • Clones the seed repo (if any) into /home/ciab/work.
   • Opens a reverse WebSocket back to the API (no inbound ports needed).
   • Launches the coding agent.
4. Output streams over the WebSocket → API SSE → UI.
5. When idle timeout or max-runtime hits, API calls TerminateInstances.

Preview URLs

If the agent binds to a local port, agentcy-ciab-bootstrap exposes it over the reverse tunnel. Access it via a signed URL:

https://your-agentcy/sandbox/preview/<session_id>/<port>/?token=…

The token is a short-lived JWT scoped to {session_id, port}. Revoked when the session ends.

IAM role for the session (optional)

Often you want the agent to have cloud access — to aws s3 ls a bucket, for example. Bind an instance profile:

CIAB_EC2_IAM_INSTANCE_PROFILE=arn:aws:iam::1234:instance-profile/agentcy-ciab-work

Scope the role narrowly. Default-deny, allow only the resources you need.

Cost control

• Spot instances — CIAB_EC2_SPOT=true uses spot with a cap price equal to on-demand. On interruption, Agentcy retries once then fails the session.
• Max runtime — hard-kill after CIAB_EC2_MAX_RUNTIME_MINUTES regardless of activity.
• Hourly cap — once the org has burned CIAB_EC2_MAX_HOURLY_USD in this hour, new sessions fail with cost_cap_reached.
• Idle reaper — kills sessions after no WebSocket traffic for CIAB_SESSION_IDLE_TIMEOUT.

Costs per session show in Activity and in /admin/usage aggregated.

Troubleshooting

• Boot loop. Check instance system logs (aws ec2 get-console-output). Most failures are bootstrap misconfiguration or S3 permission.
• Reverse tunnel not connecting. Security group outbound to Agentcy's public host + port (443 unless you moved the API).
• Stuck in pending. IAM lacks RunInstances or the subnet is out of IPs. API logs show the AWS error.

Next

• Sandbox & Artifacts — preview signing, persistence.
• Local Runtime — for dev.
• CIAB Overview