Deployment Guide

Deployment Overview

The Nova Act CLI provides two deployment workflows:

Quick Deploy: Deploy any Python script immediately without configuration
Named Workflow: Create a persistent workflow for repeated deployments

Quick Deploy Workflow

The fastest way to deploy a workflow to AWS AgentCore.

Prepare Your Code

Create a Python file with a main(payload) function:

main.py

def main(payload):
    """Entry point for Nova Act workflow."""
    print(f"Received payload: {payload}")
    
    # Your workflow logic here
    input_data = payload.get("input")
    
    return {"result": f"Processed: {input_data}"}

Deploy to AWS

Deploy with a single command:

act workflow deploy --source-dir /path/to/your/project

The CLI will:

Auto-generate a workflow name (e.g., workflow-20251130-120945)
Detect main.py as the entry point
Build a Docker container
Push to ECR
Create IAM role
Deploy to AgentCore Runtime

Output:

🚀 Deployment successful!

Deployment Details:
  Name:       workflow-20251130-120945
  Agent ARN:  arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/abc123
  Region:     us-east-1
  Workflow Console: https://console.aws.amazon.com/nova-act/...
  Agent Console:    https://console.aws.amazon.com/bedrock/agentcore/...

Next Steps:
  Run workflow:
    act workflow run --name workflow-20251130-120945 --payload "{}"

Execute the Workflow

Run your deployed workflow:

act workflow run --name workflow-20251130-120945 --payload '{"input": "test data"}'

Quick deploy creates a persistent workflow. The workflow remains in your configuration and can be managed with list, show, update, and delete commands.

Named Workflow Deployment

Recommended for workflows you’ll deploy repeatedly.

Create Workflow Configuration

act workflow create --name my-workflow

This creates:

WorkflowDefinition in AWS Nova Act service
S3 bucket for artifacts (unless --skip-s3-creation)
Local configuration entry

Deploy Your Code

Deploy to the named workflow:

act workflow deploy --name my-workflow --source-dir /path/to/code

Benefits of named workflows:

Easier to remember and reference
Visible in AWS Console with your chosen name
Better for team collaboration
Simpler re-deployment

Run and Iterate

Execute the workflow:

act workflow run --name my-workflow --payload '{"input": "data"}'

Update code and redeploy:

act workflow deploy --name my-workflow --source-dir /path/to/updated/code

Entry Point Detection

The CLI uses intelligent entry point resolution:

Default Entry Point

If no --entry-point is specified, the CLI looks for main.py:

act workflow deploy --source-dir ./my-project
# Looks for: ./my-project/main.py

Custom Entry Point

Specify a different entry point file:

act workflow deploy --source-dir ./my-project --entry-point app.py
# Uses: ./my-project/app.py

Entry Point Requirements

Required Function Signature

Your entry point file must contain a main() function with at least one parameter:

# ✅ Valid entry points
def main(payload):
    pass

def main(payload, context):
    pass

def main(payload, *args, **kwargs):
    pass

# ❌ Invalid entry points
def main():  # No parameters
    pass

def execute(payload):  # Wrong function name
    pass

Skip Validation

For advanced use cases, bypass entry point validation:

act workflow deploy --source-dir /path/to/code --skip-entrypoint-validation

When to Use --skip-entrypoint-validation:

Entry point uses dynamic function loading
Custom parameter signatures beyond def main(payload):
Testing experimental workflow patterns

Risks:

Runtime errors if entry point doesn’t match AgentCore expectations
Harder to debug deployment issues

IAM Role Management

Automatic Role Creation (Default)

The CLI automatically creates an execution role:

act workflow deploy --source-dir /path/to/code
# Creates: nova-act-my-workflow-role

Auto-created roles include permissions for:

Bedrock AgentCore operations
ECR image access
CloudWatch Logs
X-Ray tracing
S3 access (nova-act-* buckets)

Using Existing Role

Provide a pre-existing IAM role:

act workflow deploy --source-dir /path/to/code \
  --execution-role-arn arn:aws:iam::123456789012:role/MyCustomRole

Required Permissions for Custom Role

Your custom execution role must have:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:InvokeAgentRuntime",
        "ecr:GetAuthorizationToken",
        "ecr:BatchCheckLayerAvailability",
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject"
      ],
      "Resource": "arn:aws:s3:::nova-act-*/*"
    }
  ]
}

ECR Repository Management

Default Repository

The CLI uses a shared repository across workflows:

act workflow deploy --source-dir /path/to/code
# Uses: nova-act-cli-default

Each workflow gets a unique image tag:

123456789012.dkr.ecr.us-east-1.amazonaws.com/nova-act-cli-default:my-workflow-20241130-125139

Custom Repository

Use a pre-existing ECR repository:

act workflow deploy --source-dir /path/to/code \
  --ecr-repo 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-custom-repo

The custom repository must exist before deployment. The CLI will not create it.

Build Configuration

Build Directory

Control where build artifacts are stored:

# Default location: ~/.act_cli/builds/{workflow-name}/
act workflow deploy --source-dir /path/to/code

# Custom location
act workflow deploy --source-dir /path/to/code --build-dir /tmp/my-build

# Overwrite without prompting
act workflow deploy --source-dir /path/to/code \
  --build-dir /tmp/my-build \
  --overwrite-build-dir

Build Artifact Structure

The build directory contains:

build-dir/
├── Dockerfile          # Auto-generated container definition
├── handler.py          # AgentCore handler wrapper
├── requirements.txt    # Python dependencies
└── app/               # Your source code
    ├── main.py
    └── ...

Skip Building

Reuse an existing Docker image:

act workflow deploy --name my-workflow --no-build

This assumes a Docker image already exists in ECR with the expected tag. Use only when:

You’ve manually built and pushed an image
You’re redeploying with the same image

Build Cleanup

Build artifacts are persistent by default:

# Remove specific workflow build
rm -rf ~/.act_cli/builds/my-workflow

# Remove all builds
rm -rf ~/.act_cli/builds/

S3 Bucket Configuration

Nova Act workflows use S3 for artifact storage.

Default Behavior

The CLI auto-creates a bucket:

act workflow deploy --source-dir /path/to/code
# Creates: nova-act-{account-id}-{region}

Example: nova-act-123456789012-us-east-1

Custom Bucket

Use an existing S3 bucket:

act workflow deploy --source-dir /path/to/code --s3-bucket-name my-custom-bucket

The custom bucket must:

Exist before deployment
Be in the same region as the workflow
Have appropriate permissions for the execution role

Skip S3 Creation

Deploy without S3 bucket:

act workflow deploy --source-dir /path/to/code --skip-s3-creation

Multi-Region Deployment

Deploy workflows to different AWS regions:

# Deploy to us-east-1 (default)
act workflow create --name my-workflow
act workflow deploy --name my-workflow --source-dir ./code

# Deploy to us-west-2
act workflow create --name my-workflow --region us-west-2
act workflow deploy --name my-workflow --source-dir ./code --region us-west-2

Important: The AWS Nova Act service is currently only available in us-east-1.Multi-region deployment support exists in the CLI, but workflows must be deployed to us-east-1 for now.

Region Isolation

Workflows are isolated per region:

~/.act_cli/state/
└── 123456789012/
    ├── us-east-1/
    │   └── workflows.json    # us-east-1 workflows
    └── us-west-2/
        └── workflows.json    # us-west-2 workflows

AWS Console Integration

After deployment, the CLI provides direct console links:

🚀 Deployment successful!

Deployment Details:
  Name:       my-workflow
  Agent ARN:  arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/abc123
  Region:     us-east-1
  Workflow Console: https://console.aws.amazon.com/nova-act/...
  Agent Console:    https://console.aws.amazon.com/bedrock/agentcore/...

Console links provide access to:

Workflow Console: Nova Act WorkflowDefinition details
Agent Console: Bedrock AgentCore Runtime configuration
CloudWatch Logs: Execution logs and traces
ECR: Container images

Deployment Best Practices

Use Named Workflows for Production

Create named workflows for anything beyond quick testing:

# ✅ Good: Named workflow
act workflow create --name customer-onboarding
act workflow deploy --name customer-onboarding --source-dir ./code

# ⚠️ Less ideal: Auto-generated name
act workflow deploy --source-dir ./code
# Creates: workflow-20251130-120945

Version Your Dependencies

Use a requirements.txt file to pin dependencies:

requirements.txt

nova-act==1.0.0
requests==2.31.0
beautifulsoup4==4.12.0

The CLI automatically includes this in the container build.

Test Locally First

Test your workflow locally before deploying:

# test_workflow.py
from main import main

def test_workflow():
    payload = {"input": "test data"}
    result = main(payload)
    assert result is not None

Use Environment Variables

Pass configuration via environment variables instead of hardcoding:

main.py

import os

def main(payload):
    api_key = os.environ.get("NOVA_ACT_API_KEY")
    debug = os.environ.get("DEBUG", "false") == "true"
    
    # Your workflow logic

Run with environment variables:

act workflow run --name my-workflow --payload '{
  "AC_HANDLER_ENV": {
    "NOVA_ACT_API_KEY": "your-key",
    "DEBUG": "true"
  }
}'

Monitor CloudWatch Logs

Always check logs after deployment:

act workflow run --name my-workflow --payload '{}' --tail-logs

Or view in AWS Console via the provided links.

Troubleshooting Deployment Issues

Docker Not Running

Error:

Error: Docker daemon not accessible
→ Start Docker Desktop or Docker service
→ Verify: docker ps

Solution:

# macOS/Windows
# Start Docker Desktop application

# Linux
sudo systemctl start docker

# Verify
docker ps

AWS Credentials Not Configured

Error:

Error: AWS credentials not configured
→ Run: aws configure
→ Or set: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY

Solution:

aws configure

Or set environment variables:

export AWS_ACCESS_KEY_ID="your-key"
export AWS_SECRET_ACCESS_KEY="your-secret"
export AWS_DEFAULT_REGION="us-east-1"

ECR Permission Denied

Error:

Error: Missing IAM permission: ecr:CreateRepository
→ Required for: Creating ECR repository for workflow images
→ Add policy: AmazonEC2ContainerRegistryFullAccess
→ Or create repository manually with --ecr-repo

Solution 1: Add ECR permissions to your IAM user/roleSolution 2: Use existing ECR repository:

act workflow deploy --source-dir ./code \
  --ecr-repo 123456789012.dkr.ecr.us-east-1.amazonaws.com/existing-repo

Entry Point Validation Failed

Error:

Error: Entry point missing main() function
→ Add: def main(payload): ...
→ Or use: --skip-entrypoint-validation

Solution 1: Add required function:

def main(payload):
    # Your workflow logic
    pass

Solution 2: Skip validation (advanced):

act workflow deploy --source-dir ./code --skip-entrypoint-validation

ECR Login Timeout

Issue: ECR authentication fails or times outSolution:

# Manually refresh ECR authentication
aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin \
  123456789012.dkr.ecr.us-east-1.amazonaws.com

Next Steps

Run Workflows

Execute your deployed workflows

Configuration

Configure profiles and environment variables

Commands Reference

Explore all CLI commands

Troubleshooting

Solve common issues

CLI Reference

Deployment Overview

Quick Deploy Workflow

Named Workflow Deployment

Entry Point Detection

Default Entry Point

Custom Entry Point

Entry Point Requirements

Skip Validation

IAM Role Management

Automatic Role Creation (Default)

Using Existing Role

ECR Repository Management

Default Repository

Custom Repository

Build Configuration

Build Directory

Skip Building

Build Cleanup

S3 Bucket Configuration

Default Behavior

Custom Bucket

Skip S3 Creation

Multi-Region Deployment

Region Isolation

AWS Console Integration

Deployment Best Practices

Troubleshooting Deployment Issues

Next Steps

Run Workflows

Configuration

Commands Reference

Troubleshooting

Build docs developers (and LLMs) love

CLI Reference

​Deployment Overview

​Quick Deploy Workflow

​Named Workflow Deployment

​Entry Point Detection

​Default Entry Point

​Custom Entry Point

​Entry Point Requirements

​Skip Validation

​IAM Role Management

​Automatic Role Creation (Default)

​Using Existing Role

​ECR Repository Management

​Default Repository

​Custom Repository

​Build Configuration

​Build Directory

​Skip Building

​Build Cleanup

​S3 Bucket Configuration

​Default Behavior

​Custom Bucket

​Skip S3 Creation

​Multi-Region Deployment

​Region Isolation

​AWS Console Integration

​Deployment Best Practices

​Troubleshooting Deployment Issues

​Next Steps

Run Workflows

Configuration

Commands Reference

Troubleshooting

Build docs developers (and LLMs) love

Deployment Overview

Quick Deploy Workflow

Named Workflow Deployment

Entry Point Detection

Default Entry Point

Custom Entry Point

Entry Point Requirements

Skip Validation

IAM Role Management

Automatic Role Creation (Default)

Using Existing Role

ECR Repository Management

Default Repository

Custom Repository

Build Configuration

Build Directory

Skip Building

Build Cleanup

S3 Bucket Configuration

Default Behavior

Custom Bucket

Skip S3 Creation

Multi-Region Deployment

Region Isolation

AWS Console Integration

Deployment Best Practices

Troubleshooting Deployment Issues

Next Steps