Deploy

Deploy Agent Apps projects to cloud infrastructure. The deploy system builds a Docker image from your project, pushes it to a container registry, and creates a managed service.

Prerequisites

• Docker — required to build container images. Check with docker --version.
• AWS credentials — the deploy CLI needs credentials to push images and manage services.
• npm run build — the framework must be built (the base Docker image uses dist/). If you installed via the release branch, this is already done.

Quick Start

Given a web app project:

# main.skill.md
---
name: my-app
metadata:
  role: main
  paths: [./skills]
  web: { port: 8080 }
  model:
    id: us.anthropic.claude-sonnet-4-6
    region: us-east-1
  deploy:
    profiles:
      my-app:
        provider: apprunner
        region: us-east-1
        port: 8080
---

Deploy it:

cd my-app
agent-apps deploy-app

This builds a Docker image, pushes it to ECR, and creates an App Runner service. The output includes the live URL.

Deploy Config

Deploy configuration lives in the main skill's metadata under deploy.profiles.<name>, where <name> is the deployment profile (defaults to the main skill's name):

metadata:
  deploy:
    profiles:
      my-app:
        provider: apprunner
        region: us-east-1
        port: 8080
        instanceRole: arn:aws:iam::123456789012:role/my-role
        env: [MY_API_KEY]
        cpu: 1024
        memory: 2048

Agent-Powered Apps and Bedrock Access

If your app uses markdown skills (agent-generated responses), the deployed container needs AWS credentials to call Bedrock. There are two approaches:

Instance Role (Recommended)

Create an IAM role that App Runner can assume, with Bedrock permissions:

# Create the role (one-time setup)
aws iam create-role \
  --role-name agent-apps-instance \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": { "Service": "tasks.apprunner.amazonaws.com" },
      "Action": "sts:AssumeRole"
    }]
  }'

aws iam attach-role-policy \
  --role-name agent-apps-instance \
  --policy-arn arn:aws:iam::aws:policy/AmazonBedrockFullAccess

Then reference it in your deploy config:

deploy:
  profiles:
    my-app:
      provider: apprunner
      region: us-east-1
      port: 8080
      instanceRole: arn:aws:iam::123456789012:role/agent-apps-instance

The instance role is automatically assumed by the container — no credentials to manage or rotate.

Environment Variables (Not Recommended)

Passing AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY via env works for testing but session tokens expire. Use an instance role for production.

CLI Commands

deploy-app

Build and deploy the project:

agent-apps deploy-app                          # Deploy using config from main skill
agent-apps deploy-app --name staging           # Deploy a specific profile
agent-apps deploy-app --provider apprunner     # Override provider
agent-apps deploy-app --region us-west-2       # Override region

deploy-status

Check the status of a deployment:

agent-apps deploy-status                       # Status of default deployment
agent-apps deploy-status --name staging        # Status of a specific deployment

deploy-logs

Fetch recent logs from a deployed service:

agent-apps deploy-logs                         # Logs from default deployment
agent-apps deploy-logs --name staging          # Logs from a specific deployment
agent-apps deploy-logs --lines 50              # Last 50 lines

deploy-list

List all Agent Apps deployments in a region:

agent-apps deploy-list                         # List in default region
agent-apps deploy-list --region us-west-2      # List in specific region

deploy-remove

Delete a deployment and clean up resources (ECR repository):

agent-apps deploy-remove                       # Remove default deployment
agent-apps deploy-remove --name staging        # Remove a specific deployment

How It Works

The App Runner provider (deploy-apprunner) performs these steps:

1. Build image — builds a Docker image from your project (auto-builds the base agent-apps-sandbox image if missing)
2. Push to ECR — creates an ECR repository if needed, authenticates, tags, and pushes
3. Create/update service — creates a new App Runner service or updates an existing one
4. Wait for RUNNING — polls until the service reaches RUNNING status (up to 10 minutes)

Services are identified by an agent-apps:project tag on the App Runner service, so multiple projects can coexist in the same account/region.

Example: Agent-Generated Web App

A complete example — a web app where the agent generates a unique page on every request:

# main.skill.md
---
name: turkish-idioms
description: Agent-generated Turkish idiom page
metadata:
  role: main
  paths: [./skills]
  web:
    port: 8080
    routes:
      - method: GET
        path: /
        ref: page
  model:
    id: us.anthropic.claude-sonnet-4-6
    region: us-east-1
  deploy:
    profiles:
      turkish-idioms:
        provider: apprunner
        region: us-east-1
        port: 8080
        instanceRole: arn:aws:iam::123456789012:role/agent-apps-instance
---

# skills/page.skill.md
---
name: page
description: Generate a page featuring a random Turkish idiom
---

Pick one Turkish idiom at random. Return a beautiful HTML page with the idiom
in Turkish, a literal English translation, the actual meaning, and an example.
Inline all CSS. No JavaScript.

cd turkish-idioms
agent-apps deploy-app
# → { "url": "https://xxx.us-east-1.awsapprunner.com", "status": "RUNNING" }

Each request takes ~10–15 seconds (agent generation time) and returns a different idiom.