Sample Remote Coding Agent

Submit from Claude Code or the web UI, follow the remote agent's progress, and get a PR with verification evidence powered by Amazon Bedrock AgentCore Runtime.

Sample run — simulated: add CSV export to an expense tracker.

Quick start · Web UI · Claude Code · Architecture · Costs and cleanup · Contributing

For developers delegating scoped features, bug fixes, and tests, and platform engineers exploring AWS-hosted coding agents with repository-scoped execution and a shared task console.

Keep working while the agent runs. Submit a task and let remote execution handle the loop.

See what happened. Follow planning, coding, verification, and review from one board.

Review the result in GitHub. Get a PR with verification evidence and an explicit draft outcome when checks do not pass.

Own the deployment. Each repository gets its own AgentCore Runtime and Memory in your AWS account.

Use trusted repositories in a dedicated AWS account. This sample executes repository code; it does not make untrusted code safe. A runtime or publishing failure may produce no PR.

A dedicated AWS account, with credentials for your intended profile and region.

Docker running, Python ≥ 3.11 (tested with 3.12), uv , Node ≥ 20, and the AWS CLI.

A trusted, disposable GitHub repository with a default branch that already builds and passes its tests . The agent never guesses how to build a repository. It reads a root Makefile with a setup: (or bootstrap: ) target and a test: target, or a root package.json with scripts.setup and scripts.test . An empty repository does not work. With no default branch, the run fails at the very end when it opens the pull request ( 422 Validation Failed , "field": "base" ). With no test entry point, every PR comes back as an unverified draft. If your repository is empty, set it up with one of the options below before you register it .

A GitHub account you can create an app under. No token to paste — step 3 creates a GitHub App ; see GitHub access .

Preflight checks AgentCore/model availability and prints any required CDK bootstrap command. The ~1.3 GB ARM64 image builds locally. Claude Code is optional; the web UI works without it.

Setting up an empty repository

Web UI: from this checkout, run scripts/scaffold.sh / (a GitHub URL or a local clone's path also works). It needs git , make , python3 and git credentials that can push, for example gh auth login , and pushes with those rather than through the GitHub App. It clones into a temporary directory, writes a minimal Python project (a Makefile with setup and test targets, one function in src/ , and its pytest tests), runs make setup and make test , and when both pass asks before pushing it as main .

Claude Code: install the plugin ( Option B , step 4), clone the repository, and run /sample-rca:scaffold from the clone. It writes a Python project, or TypeScript if you ask for it by name, runs its setup and tests, pushes it as main after you confirm, and offers to register the repository.

Deploy the fleet. git clone cd sample-remote-coding-agent make setup make preflight make deploy EMAIL=[email protected] Read the account and region from make preflight before deploying. Preflight is read-only; deploy starts spending without confirmation. Allow 15–25 min , mostly the local image build. On completion it prints the console URL, API URL, and region. Check known issues if it stalls.

Read the account and region from make preflight before deploying. Preflight is read-only; deploy starts spending without confirmation. Allow 15–25 min , mostly the local image build. On completion it prints the console URL, API URL, and region. Check known issues if it stalls.

Sign in at the console URL. Cognito emails a temporary password to EMAIL ; check spam and change it on first sign-in.

Sign in at the console URL. Cognito emails a temporary password to EMAIL ; check spam and change it on first sign-in.

Connect GitHub. With nothing registered the console opens on Connect GitHub . Press Create the GitHub App on GitHub — the app arrives pre-described, you confirm it there, and nothing is copied or pasted. Then Install on GitHub and choose Only select repositories : that list bounds which repositories the agent can reach.

Connect GitHub. With nothing registered the console opens on Connect GitHub . Press Create the GitHub App on GitHub — the app arrives pre-described, you confirm it there, and nothing is copied or pasted. Then Install on GitHub and choose Only select repositories : that list bounds which repositories the agent can reach.

Register a disposable repository with + Add repository : the URL, Advanced folded, no credential field. The authorisation starts on its own — it takes you to GitHub and brings you back, and GitHub asks for consent only the first time. The GitHub access panel confirms it by writing a throwaway branch and deleting it. If that panel says the app cannot write here, the app is not installed on this repository: installing and authorising are separate grants, both required, and the panel links the fix. Authorise GitHub is there to retry or to use a different GitHub account. Provisioning runs in parallel and takes 8–12 min to reach READY . A task started sooner returns 409 ConfigurationNotReady ; one started before authorising returns 409 GitHubNotAuthorized . The agent pushes branches and opens PRs. Start with a small repository whose tests already pass. Declare setup/test entry points so verification can run: command detection details .

Register a disposable repository with + Add repository : the URL, Advanced folded, no credential field. The authorisation starts on its own — it takes you to GitHub and brings you back, and GitHub asks for consent only the first time. The GitHub access panel confirms it by writing a throwaway branch and deleting it. If that panel says the app cannot write here, the app is not installed on this repository: installing and authorising are separate grants, both required, and the panel links the fix. Authorise GitHub is there to retry or to use a different GitHub account.

Provisioning runs in parallel and takes 8–12 min to reach READY . A task started sooner returns 409 ConfigurationNotReady ; one started before authorising returns 409 GitHubNotAuthorized .

The agent pushes branches and opens PRs. Start with a small repository whose tests already pass. Declare setup/test entry points so verification can run: command detection details .

Choose how to submit tasks

One deployment, two entry points. Both queue the same remote agent pipeline and produce cards on the same board. Registration is done once in the console, whichever path you use.

Open your repository's board. Type the title on the first line and the description below it. Illustrative example from the GIF: this task assumes an expense-tracker app, which this repository does not include. Write a task that fits your own registered repository.

Click Add card , then Start run (or drag Backlog → Planning). Add and start does both at once. Watch Planning → Coding → Verifying → Done and click the status for details.

Option B: Claude Code

Install the plugin, then restart Claude Code. Web-only users can skip this step. /plugin marketplace add aws-samples/sample-remote-coding-agent /plugin install sample-rca@sample-remote-coding-agent Leave the config fields empty for discovery. RCA_API_URL , RCA_REGION , and RCA_STACK_NAME overrides outrank discovery and may select another fleet. Check the endpoint used: line. Restarting loads the plugin's MCP tools.

Install the plugin, then restart Claude Code. Web-only users can skip this step.

Leave the config fields empty for discovery. RCA_API_URL , RCA_REGION , and RCA_STACK_NAME overrides outrank discovery and may select another fleet. Check the endpoint used: line. Restarting loads the plugin's MCP tools.

Queue acknowledgment takes seconds; execution can take tens of minutes. Unverified runs open draft PRs . Reviewing and Submitting are statuses within Verifying. Done alone is not proof of success: SUCCEEDED means a verification command ran and review judged it green. Follow Open pull request , inspect the diff and evidence, and merge only after human review.

Test the prompt guardrail

A Bedrock guardrail screens every task prompt before a run is queued, and every card before it is saved. Add each line below as its own card:

Each is refused with PromptBlockedByGuardrail naming what tripped ( PROMPT_ATTACK , MISCONDUCT , AWS_ACCESS_KEY ), and no card is saved, so a pasted key is never stored. /sample-rca:remote gets the same refusal. An ordinary task still starts. GuardrailUnavailable means nothing ran; its reason says whether to retry. It screens prompts only, not agent output.

Editable draw.io source · Asset sources

The local MCP server uses an IAM-authorized API; the browser uses CloudFront/S3 and a Cognito-authorized API. Both reach Lambda and SQS. Each repository owns a Runtime; tasks run in isolated sessions with a clone and checkpoint under /mnt/workspace .

The agent runs checkout → plan → code → verify → review → submit , with bounded rework. It writes status/activity to DynamoDB; the console polls through the API. AgentCore Memory is created at registration and deleted at deregistration. Tasks can retrieve earlier lessons; a repository without memory runs without it.

VPC endpoints connect runtime traffic to Bedrock, AgentCore, DynamoDB, ECR API/Docker, S3, and CloudWatch Logs . Lambda runs outside the agent VPC. GitHub receives source code through clone/push/PR traffic. Package installation reaches PyPI/npm, and the documentation tool reaches AWS documentation. These are intended destinations, not an enforced domain allowlist : NAT permits outbound TCP 443, and the DNS firewall blocks named vendor domains only. Boundary details

NAT gateways, interface VPC endpoints, WAF, images, logs, and stored data can cost money even between tasks. Tasks add Runtime, Bedrock, and memory usage. No whole-stack monthly or per-task cost estimate is published.

The default $200 monthly Bedrock budget sends email notifications , not a hard spending cap, and does not cover every service. Monitor your actual account charges. Budget configuration

Deregister every repository in the console first — settings → Deregister , 1-3 min each — then Disconnect on the GitHub App page, and only then destroy the stacks. The other order orphans the runtime, the IAM role, the memory and the credential provider, which no stack owns and which keep costing money. The GitHub App belongs to your GitHub account; delete it there. Follow the exact five-stack teardown for your prefix and region. Stack deletion retains tables, the Cognito pool, access logs, bootstrap ECR images, and runtime log groups. Review the retained-resource cleanup table before deleting them; some are the only history of your runs.

A tool recommends /sample-rca:setup . That command is gone; run make deploy EMAIL=[email protected] from a checkout.

Console returns AccessDenied XML. Check that deployment uploaded index.html before changing IAM.

Temporary password expired. Redeployment does not resend it; see operator recovery notes .

Tools succeed but the board is empty. Check endpoint used: and stale API overrides for another deployment.

Another /remote command answers. Use /sample-rca:remote ; other plugin namespaces are unrelated.

The run fails at submit with could not open a pull request ... (HTTP 422) and "field": "base", "code": "invalid" . The repository had no default branch when the task started. The agent assumed main , and GitHub rejected it as the PR base. The agent's branch is now the repository's only branch, and probably its default, so scripts/scaffold.sh and /sample-rca:scaffold will refuse the repository because it is no longer empty. Either push a main that builds and passes its tests yourself and set it as the default branch, or create a new empty repository, scaffold that, and register it instead. Then run the task again.

Setup notes worth reading before you deploy: VPC quota , Cognito domain , deployment , wrong-account handling , account selection .

Run make setup , make test , and make lint . Local tests use fake AWS services, not a deployed fleet. See contribution guidelines , the code of conduct , the operations reference and the security reference . Keep diagrams and previews in sync with UI changes.

GitHub access: read this

Nothing here stores a GitHub token. One GitHub App serves the deployment, AgentCore Identity's token vault holds its client secret, and each container fetches a short-lived token when it needs one. There is no secret to rotate and no credential field on any page.

Two steps are separate and both are required:

The installation list is the blast radius. A token issued to one repository's container can write to every repository the app is installed on. That is how a GitHub App works and it is the one thing this design gives up against a per-repository fine-grained token, so install it only where you intend to run the agent. This system runs an arbitrary repository's own setup and test commands with a model pointed at them and does not prevent prompt injection, so treat every token the app can issue as reachable by that code. Use a GitHub account that owns nothing you mind losing — the same bound this sample asks for on the AWS side.

Disconnecting on the GitHub App page revokes every repository's authorisation at once. The app belongs to your GitHub account; delete it there when you are finished.

Installing the app is a manual step , once per repository. GitHub requires a human to grant an app access to a repository, and authorising requires a human to approve it — there is no machine-to-machine path, because GitHub implements no client_credentials grant.

One app covers every registered repository , so its installation list is the blast radius, as above.

AgentCore Runtime V2 only , so deployment is limited to us-east-1 , us-east-2 , us-west-2 , eu-west-1 and ap-northeast-1 .

Protect the default branch of the repository you register. Read GitHub access before installing the app anywhere. The account boundary does not stop repository code from making outbound HTTPS requests. Remaining exposure

Bedrock invocation logging is a retention choice; default global. inference profiles can serve outside your deployment region. Review the logging qualification and data residency before sending sensitive code.

See CONTRIBUTING for more information.

This sample uses the MIT-0 License . See attribution for third-party artwork rights.