Sandbox

Run Agent Apps projects inside Docker containers for isolation and testing before deployment.

Prerequisites

  • Docker — check with docker --version.
  • npm run build — the base Docker image uses the compiled dist/. If you installed via the release branch, this is already done.

Quick Start

cd my-app
agent-apps sandbox-build          # Build the Docker image
agent-apps sandbox-app --args '[]' # Run the main skill inside the container

Building Images

sandbox-build creates a Docker image from your project in two layers:

  1. Base image (agent-apps-sandbox) — Node 22, compiled framework (dist/), production dependencies. Auto-built from the framework source if missing.
  2. Project image (<name>-sandbox) — your project files copied on top of the base.
agent-apps sandbox-build                    # Build with default name (from main skill)
agent-apps sandbox-build --name my-app      # Build with explicit name

The project image is tagged as <name>-sandbox (e.g., my-app-sandbox).

What Goes Into the Image

The project Dockerfile copies your entire project directory into /app/project and runs npm install --omit=dev. A .dockerignore is auto-generated if missing, excluding node_modules, .git, .agent, .agent-apps, and .kiro.

Running in a Sandbox

sandbox-app runs CLI args inside a container:

agent-apps sandbox-app --args '["hello", "--name", "World"]'   # Run a specific skill
agent-apps sandbox-app --args '[]'                              # Run the main skill (no args)
agent-apps sandbox-app --args '[]' --detach true                # Run in background

Port Mapping for Web Apps

The container runs in isolation — to access a web server, you need to expose ports via constraints:

# main.skill.md
metadata:
  sandbox:
    profiles:
      my-app:
        constraints:
          network: { allow: [8080] }

Or pass constraints directly:

agent-apps sandbox-app --args '[]' --constraints '{"network": {"allow": [8080]}}'

AWS Credentials in Containers

If your app calls AWS services (e.g., Bedrock for markdown skills), the container needs credentials. For local Docker testing, pass them as environment variables:

# Extract credentials and run manually
eval $(aws configure export-credentials --format env 2>/dev/null)
docker run --rm -p 8080:8080 \
  -e "AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID" \
  -e "AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY" \
  -e "AWS_SESSION_TOKEN=$AWS_SESSION_TOKEN" \
  my-app-sandbox

If your credentials are in ~/.aws/credentials (shared credentials file) rather than environment variables, you must extract them first — Docker's -e VAR syntax only forwards variables that are already set in your shell.

For deployed services, use an IAM instance role instead. See Deploy.

Sandbox Config

Sandbox configuration lives in the main skill's metadata under sandbox.profiles.<name>:

metadata:
  sandbox:
    profiles:
      my-app:
        engine: docker
        constraints:
          fs:
            - { path: ./data, mode: rw }
          network: { allow: [8080] }
          env: [AWS_REGION, MY_API_KEY]
          resources:
            memory: 512m
            cpu: 1

Constraints

Field Type Description
fs {path, mode}[] Filesystem mounts. Paths relative to project root. Mode: ro or rw.
network "none" | "host" | {allow: number[]} Network access. Default: no restrictions.
env string[] Environment variable names to forward into the container.
resources.memory string Memory limit (e.g., 512m, 2g).
resources.cpu number CPU limit (e.g., 1 = 1 core).

Other Commands

sandbox-status

Check running sandbox containers:

agent-apps sandbox-status

sandbox-list

List all Agent Apps sandbox containers:

agent-apps sandbox-list

sandbox-stop

Stop a running sandbox container:

agent-apps sandbox-stop --name my-app

Workflow: Local → Sandbox → Deploy

The typical development workflow:

  1. Local — run directly from source for fast iteration:

    cd my-app && agent-apps

  2. Sandbox — verify it works in a container (catches missing deps, path issues):

    agent-apps sandbox-build
docker run --rm -p 8080:8080 my-app-sandbox

  3. Deploy — push to production:

    agent-apps deploy-app

See Deploy for the full deployment guide.

Ask AI