Spin up private, persistent EC2 workspaces for coding agents in your AWS org
Run CLI agent harnesses from a browser while the workspace stays on a private EC2 runtime with no public IP and no inbound SSH.
Quick start · Architecture · Documentation · Security · Contributing
AgentFormation is an AWS-native template for browser-accessible coding
environments. It installs
Claude Code and
Codex, configures them for Amazon
Bedrock, and runs them on private EC2 instances. An App Runner web app provides
browser terminals, persistent tmux sessions, and file uploads. The resources
stay in an AWS account you control.
Access uses AWS IAM Identity Center, so users sign in with an existing Identity Center identity instead of creating another app password or MFA setting. The deployment operator assigns an Identity Center group to AgentFormation, and each assigned user can provision one runtime from the fixed template.
| Existing AWS sign-in | Private networking | Persistent workspace |
|---|---|---|
| IAM Identity Center; no separate app password | Private subnet, encrypted EBS, no public IP, and no inbound SSH | /workspace and tmux keep running after the browser disconnects |
Important
The first complete deployment builds a runtime image and an App Runner service. It commonly takes more than 30 minutes. This is normal for the AWS services used by the template, not a frozen terminal.
assigned Identity Center group
|
v
AWS IAM Identity Center --SAML--> Cognito bridge --OIDC--> App Runner
web terminal
|
Create runtime |
v
restricted setup job
|
v
private EC2 runtime
Claude Code + Codex + /workspace
|
v
Amazon Bedrock models
- IAM Identity Center group assignment as the only app sign-in path
- Amazon Cognito as an invisible SAML-to-OIDC bridge, with local sign-in excluded
- one private VPC subnet and one NAT gateway by default
- one private, encrypted EC2 runtime and EBS volume per assigned user
- AWS Systems Manager Session Manager instead of inbound SSH
- an EC2 Image Builder pipeline with pinned Claude Code and Codex versions
- pinned AWS CLI, Node.js, and Bun versions for repeatable project setup
- an App Runner web terminal
- a restricted Step Functions job that can create only the fixed runtime stack
- a DynamoDB identity-to-runtime registry
- a short-lived DynamoDB request-control table shared by every web instance
- a short-lived, encrypted S3 upload staging area
You need an organization instance of IAM Identity Center, permission to add a
customer-managed SAML application and assign a group, an AWS CLI profile that can
deploy the resources, Docker with buildx, jq, and access to the selected
Bedrock models. The AWS root user is deliberately not an app login. Root is a
separate emergency identity and should not be used for daily work.
Before deploying, follow the
workstation setup guide to install the correct AWS
CLI and Docker tools for macOS or Linux on amd64/x86_64 or
arm64/aarch64. It also explains why the AWS permission set used for deployment
is separate from the Identity Center group assigned to the AgentFormation app.
For a guided, read-only setup, start Codex from this repository and invoke
$setup-agentformation.
AWS does not expose customer-managed SAML application creation or attribute mapping through its public CLI, API, or CloudFormation resource. Creating the Identity Center application and entering its two attribute mappings is therefore a one-time console step; AgentFormation automates the Cognito side and the rest of the deployment.
If CloudFormation must use an existing service role, add its ARN as
cloudFormationRoleArn in agentformation.local.json. The example omits it
because not every account requires one.
-
Clone the repository and create the private local configuration:
cp agentformation.example.json agentformation.local.json AWS_PROFILE=your-profile ./agentformation doctor AWS_PROFILE=your-profile ./agentformation deploy
The first deploy creates only enough identity infrastructure to print the exact SAML ACS URL and audience, then exits successfully.
Use the configuration guide for every field, moving an older config, or continuing the same deployment from another computer.
-
In IAM Identity Center, create a customer-managed SAML 2.0 application using those two printed values. Map SAML
Subjectto${user:subject}with thepersistentformat, mapemailto${user:email}with theunspecifiedformat, assign a dedicated AgentFormation access group, add one test user directly to that group, and copy the HTTPS address shown for the IAM Identity Center SAML metadata file. Using the address lets Cognito refresh signing certificates automatically. If your console offers only a download, save the XML file instead. -
Put the metadata address in the ignored private config and deploy again. Do not commit the deployment-specific address:
# In agentformation.local.json, set identityCenter.metadataUrl to the HTTPS # address from IAM Identity Center and leave metadataFile empty. AWS_PROFILE=your-profile ./agentformation doctor AWS_PROFILE=your-profile ./agentformation deploy
If you downloaded XML instead, save it as
.agentformation/identity-center-metadata.xml, leavemetadataUrlempty, and setmetadataFileto that path. Set only one metadata source. -
Open the printed web address and choose the sign-in button. If the IAM Identity Center session is still active, there is normally no second prompt. Choose Create environment once; the restricted AWS job creates the private runtime.
-
When a command-line tool opens a browser login that ends at
127.0.0.1orlocalhost, the browser will showERR_CONNECTION_REFUSED. This is expected for a remote runtime. Copy the complete failed address, return to AgentFormation, choose Finish login, paste it, and choose Send to runtime while the CLI is still waiting. Never paste that one-time address into chat or logs. Follow the remote CLI sign-in guide for the complete flow and troubleshooting steps. -
As the optional final setup step, migrate existing Codex or Claude Code preferences and selected session history into the runtime. Start Codex from this repository and invoke
$migrate-agent-configs; it begins with a read-only inventory and requires separate confirmation before moving credentials or chats. A complete migration maps the copied chat index to the remote workspace so ordinarycodex resumeand the in-app/resumecommand work. Usecodex resume --all --include-non-interactive -C /workspaceas the all-folders fallback. Follow the local agent migration guide.
See the complete IAM Identity Center setup guide for the exact console fields and group-assignment steps.
The deploy command is safe to run again. CloudFormation applies the template
changes without creating a second runtime for a user who already has one. The
latest tested AMI is reused; set AGENTFORMATION_REBUILD_IMAGE=1 only when you
intentionally want a fresh image with otherwise unchanged settings.
App Runner supplies a working HTTPS address automatically. To use a custom address instead, associate the domain with the App Runner service and publish the certificate-validation and traffic records requested by App Runner through your DNS provider. Wait until App Runner reports the domain as active, then put only the origin in the ignored local configuration:
"publicUrl": "https://agents.example.com"Run ./agentformation doctor and ./agentformation deploy again. The deploy
command uses that address for Auth.js, Cognito callbacks and logout, browser
upload restrictions, and status output. Do not commit a deployment-specific
hostname to the public repository. Leave publicUrl empty to keep using the
generated App Runner address.
| Guide | Use it for |
|---|---|
| Workstation setup | Installing the AWS CLI and Docker on macOS or Linux, including amd64 and arm64 differences |
| IAM Identity Center setup | Creating the SAML application, attribute mappings, and assigned access group |
| Configuration and upgrades | Choosing settings, moving a deployment, rebuilding images, and applying updates |
| Remote CLI sign-in | Finishing localhost or 127.0.0.1 OAuth callbacks from a browser terminal |
| Agent config migration | Moving selected Codex or Claude Code preferences and history into a runtime |
| Security model and privacy notes | Understanding trust boundaries, access, stored data, and operational responsibilities |
# Show shared stacks, user runtimes, and the web address
AWS_PROFILE=your-profile ./agentformation status
# Immediately block app sign-in and stop compute while preserving the disk
AWS_PROFILE=your-profile ./agentformation users disable --email person@example.com
# Restore app sign-in and restart the preserved runtime
AWS_PROFILE=your-profile ./agentformation users enable --email person@example.com
# Permanently delete the app identity, runtime, and runtime disk
AWS_PROFILE=your-profile ./agentformation users purge \
--email person@example.com --confirm DELETE
# Permanently delete the complete deployment
AWS_PROFILE=your-profile ./agentformation destroy --confirm DELETEGroup assignment in IAM Identity Center is the source of truth. Remove a user
from the assigned group when access should end. Use users disable for an
immediate app-side block that preserves the runtime disk. Remove the group
assignment before users purge; otherwise the user can sign in again and create
a new environment.
Users start in /workspace. Closing a browser does not kill the tmux session,
so reconnecting returns to the same terminal process.
New environments include Git, Docker, Node.js/npm, Bun, jq, ripgrep, and
tmux alongside Claude Code and Codex. A rebuilt image applies to environments
created afterward; it does not silently replace an existing user's persistent
machine. See the configuration and upgrade guide.
AgentFormation isolates app users from one another, but AWS account administrators remain trusted and can inspect or change all resources. The browser cannot choose an instance ID. The server uses the signed-in federated Cognito subject to find the assigned runtime, and the setup job accepts only a fixed, content-hashed CloudFormation template and fixed operator-selected values. Runtimes have no public IP and no inbound security group rules.
Read the security model and the privacy notes before granting access. To report a vulnerability, follow SECURITY.md.
This is not a free-tier-only template. The main costs are App Runner, a NAT
gateway, one EC2 instance and EBS volume per provisioned runtime, Image Builder,
Step Functions, S3, DynamoDB, and Bedrock requests. Check the
AWS Pricing Calculator for your region and sizes.
Disabling access stops EC2 compute but preserves EBS storage. Use purge or
destroy when the runtime data is no longer needed.
Prepare the pinned tools and understand the host-versus-container architecture using the workstation setup guide, then run:
./scripts/check.shThe check runs the frozen install, dependency audit, formatting, lint, types, tests, production build, shell checks, and CloudFormation lint. Pull requests do not receive AWS credentials. A full AWS deployment remains a maintainer-run check because it creates billable resources and uses account-specific Bedrock access.
See CONTRIBUTING.md and the maintainer release checklist.
AgentFormation is a community reference project. There is no guaranteed support or uptime commitment. Bugs and improvements are welcome through GitHub issues and pull requests.
Licensed under the BSD 2-Clause License.
AgentFormation is still experimental—review the security model and try it in a non-production AWS account before depending on it.