Claude Code Headless Container

This container allows you to run Claude Code in a headless fashion. It can:

1. Clone a Git repository
2. Download instructions from S3
3. Process the instructions using Claude Code
4. Commit and push changes back to the repository

Architecture Overview

The following diagram illustrates the architecture and workflow of the Claude Code Headless Container:

The diagram shows how the container interacts with AWS services and Git repositories to automate code implementation using Claude Code.

Environment Variables

Variable	Description	Default
PROCESS_REQUIREMENTS	Set to 'true' to process requirements	-
REPO_URL	URL of the Git repository to clone	Required
INSTRUCTIONS_S3_URI	S3 URI of the instructions file	Required
BRANCH_NAME	Git branch name for implementation	feature/claude-implementation-{timestamp}
COMMIT_MESSAGE	Git commit message	"Implement requirements using Claude Code"
GIT_CREDENTIALS_SECRET_ID	Secret ID for Git credentials in AWS Secrets Manager	claude-headless/git-credentials
CLAUDE_MODEL_ID	Claude model ID to use	us.anthropic.claude-sonnet-4-20250514-v1:0
DISABLE_PROMPT_CACHE	Set to 'true' to disable prompt caching	false
AWS_REGION	AWS region for API calls	us-east-1
CLAUDE_SETTINGS	JSON string for Claude Code settings (will be written to .claude/settings.json)	{"permissions": {"allow": ["Bash(*)"]}}

Git and API Credentials

The container expects credentials to be stored in AWS Secrets Manager with the following format:

{
  "token": "your-git-personal-access-token",
  "email": "your-git-email@example.com"
}

Important Note on Secret Names:

• When creating secrets with step1-setup-secrets.sh, you can use any name (e.g., my-secret-name)
• When setting up IAM roles with step2-setup-iam-roles.sh, use the same name (e.g., my-secret-name)
• When setting up ECS task definition with step4-setup-ecs.sh and running tasks with step5-run-fargate-task.sh, use the exact same name as in step1
• AWS Secrets Manager adds a random suffix to the actual ARN, but our scripts will handle this automatically

Note on IAM Permissions:

• The ECS execution role needs permission to access the secret from AWS Secrets Manager
• The task role needs permission to access AWS services from within the container
• Both roles are set up by step2-setup-iam-roles.sh

Instructions Format

The instructions should be stored in S3 and can be a single file or a directory of files. The container will download the instructions and pass them to Claude Code for processing.

Single File Instructions

For simple tasks, you can use a single Markdown file with instructions:

s3://your-bucket/instructions.md

The file should contain clear, detailed instructions for Claude Code to follow. For example:

# Task Instructions

1. Implement a REST API for a todo list application using Express.js
2. Create the following endpoints:
   - GET /todos - List all todos
   - POST /todos - Create a new todo
   - GET /todos/:id - Get a specific todo
   - PUT /todos/:id - Update a todo
   - DELETE /todos/:id - Delete a todo
3. Include proper error handling and validation
4. Write unit tests for all endpoints

Multiple Files Instructions

For more complex tasks, you can use a directory structure with multiple files:

s3://your-bucket/instructions/
├── main.md
├── api-spec.yaml
├── database-schema.sql
└── examples/
    ├── example1.json
    └── example2.json

Use a wildcard pattern in the S3 URI to download all files:

s3://your-bucket/instructions/*

The container will download all files and maintain the directory structure. In your main instruction file, you can reference other files:

# Implementation Instructions

1. Review the API specification in `api-spec.yaml`
2. Implement the database schema defined in `database-schema.sql`
3. Ensure the API responses match the examples in the `examples` directory

Best Practices for Instructions

1. Be specific and detailed - Provide clear requirements and acceptance criteria
2. Include examples - Show expected inputs and outputs
3. Reference existing code - If modifying an existing codebase, explain the current structure
4. Specify technologies - Clearly state which frameworks, libraries, or tools to use
5. Define constraints - Mention any limitations or requirements (e.g., performance, compatibility)
6. Prioritize tasks - Indicate which features are most important if time is limited

Usage

Local Testing

docker build -t claude-code-headless .

docker run -e PROCESS_REQUIREMENTS=true \
  -e REPO_URL=https://github.com/your-org/your-repo.git \
  -e INSTRUCTIONS_S3_URI=s3://your-bucket/instructions.md \
  -e CLAUDE_MODEL_ID=us.anthropic.claude-sonnet-4-20250514-v1:0 \
  -e DISABLE_PROMPT_CACHE=true \
  -e AWS_REGION=us-east-1 \
  -e AWS_ACCESS_KEY_ID=your-access-key \
  -e AWS_SECRET_ACCESS_KEY=your-secret-key \
  -e GIT_CREDENTIALS_SECRET_ID=your-secret-name \
  -e CLAUDE_SETTINGS='{"permissions": {"allow": ["Bash(*)","Read(*)","Edit(*)","MultiEdit(*)","Write(*)"]}}' \
  claude-code-headless

AWS ECS/Fargate Deployment

You can deploy this container to AWS ECS or Fargate for serverless execution. Use the accompanying setup scripts:

# 1. Set up secrets in AWS Secrets Manager
./step1-setup-secrets.sh --token your-git-token --email your-git-email --secret-name your-secret-name

# 2. Set up IAM roles with access to your secret
./step2-setup-iam-roles.sh --secret-name "your-secret-name"

# 3. Set up ECR repository
./step3-setup-ecr.sh

# 4. Set up ECS task definition
./step4-setup-ecs.sh --execution-role role-arn --task-role role-arn --secret-name your-secret-name

# 5. Run Fargate task
./step5-run-fargate-task.sh --subnet subnet-id --security-group sg-id --repo-url repo-url --instructions s3-uri --secret-name your-secret-name

Security Considerations

Credentials and Secrets Management

• Never hardcode credentials in any files, scripts, or environment variables
• Always use AWS Secrets Manager for storing sensitive information such as:
  • Git personal access tokens
  • Git credentials (username/email)
  • Any API keys or tokens needed by your application
• The container requires AWS credentials with permissions to:
  • Access the S3 bucket containing instructions
  • Access AWS Secrets Manager for Git credentials
  • Call the Amazon Bedrock API for Claude

IAM Best Practices

• Use IAM roles with least privilege when deploying to AWS services
• The provided setup scripts create roles with appropriate permissions
• Review and customize IAM policies based on your specific security requirements
• For production use, consider further restricting permissions to specific resources

Container Security

• The container runs with minimal dependencies to reduce attack surface
• Git credentials are only stored temporarily within the container during execution
• No sensitive information is persisted after the container completes its task
• Consider using private ECR repositories for storing the container image

Network Security

• When running in AWS Fargate, use private subnets when possible
• Configure security groups to restrict network access
• Consider using VPC endpoints for AWS services to avoid traffic over the public internet

Monitoring and Auditing

• Enable AWS CloudTrail to audit API calls made by the container
• Set up logging for the container to capture execution details
• Monitor for unusual activity or unauthorized access attempts