> ## Documentation Index
> Fetch the complete documentation index at: https://docs.springwinter.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Build Coding Agent Sandboxes on AWS

> Design isolated coding agent sandboxes on AWS with ephemeral tasks, repository credentials, resource limits, network policy, artifact persistence, and teardown.

A coding agent sandbox is disposable compute that clones a repository, edits files, runs tools, returns a patch or commit, and then disappears. The sandbox must treat repository code and generated commands as untrusted.

*Updated October 9, 2026.*

**Run each coding session in a fresh isolated task with short-lived credentials and automatic teardown.**

## Separate control and execution planes

Deploy the agent API, scheduler, and session database as ordinary services. Launch execution sandboxes as one-off tasks. Do not execute customer code inside the long-running control-plane container.

Current Springwinter Workers are continuous ECS services, not a first-class per-session sandbox API. A Springwinter service can coordinate sessions, but the execution layer currently needs direct ECS `RunTask`, AWS Batch, or another sandbox runtime.

## Session lifecycle

1. Authenticate the user and authorize repository access.
2. Create a session record with CPU, memory, duration, and network limits.
3. Mint a short-lived GitHub installation token.
4. Launch one isolated task with a unique session ID.
5. Clone only the authorized repository and ref.
6. Run the agent with a workspace-local tool policy.
7. Stream bounded logs and heartbeats.
8. Upload the patch, test report, and selected artifacts.
9. Revoke credentials and stop the task.
10. Delete temporary state after the retention period.

## Isolation controls

Use a non-root user, read-only base filesystem, dedicated writable workspace, dropped Linux capabilities, strict CPU and memory limits, and a task role with no default cloud access. Deny access to metadata and private networks except required endpoints.

Fargate gives each task a dedicated isolation boundary, including separate kernel, CPU, memory, network interface, and ephemeral storage. Containers inside one task still share task resources, so do not place different tenants in sidecars of the same task.

## Credentials and artifacts

Never bake GitHub, package-registry, cloud, or model credentials into the image. Deliver session-scoped credentials at startup and expire them quickly. Upload only explicit outputs. A workspace tarball may contain secrets copied from the repository or generated during tests.

## Tool policy

Allow required compilers and package managers, but limit privileged operations. Set maximum subprocess count, output bytes, disk usage, wall time, and idle time. Record which tools ran without logging secret values.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can a Springwinter Worker be the coding sandbox?">
    A Worker can run trusted internal automation, but a multi-tenant coding sandbox should use one disposable task per session. Current Springwinter Workers are long-running services rather than per-request isolated tasks.
  </Accordion>

  <Accordion title="Should the agent receive the user's cloud credentials?">
    No. Give the sandbox a session-specific role or no cloud role. Grant only the exact resources and actions needed, with short expiry and auditable session identity.
  </Accordion>

  <Accordion title="Where should the final code change live?">
    Return a patch, commit, or pull request through the control plane. Persist selected test results and logs separately, then destroy the execution workspace.
  </Accordion>
</AccordionGroup>

## Sources and further reading

* [RunTask API](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html)
* [Fargate security considerations](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/fargate-security-considerations.html)
* [ECS container security best practices](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/security-tasks-containers.html)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.