Configuration - Amazon Nova Act

Configuration Overview

The Nova Act CLI uses a multi-layered configuration system:

State Files: Per-region workflow tracking
User Config: Global CLI preferences
AWS Profiles: Credential management
Environment Variables: Runtime configuration

State Management

State File Structure

Workflows are stored in separate state files per AWS account and region:

~/.act_cli/
├── state/
│   ├── 123456789012/              # AWS Account ID
│   │   ├── us-east-1/
│   │   │   └── workflows.json     # Region-specific state
│   │   └── us-west-2/
│   │       └── workflows.json
│   └── 987654321098/
│       └── us-east-1/
│           └── workflows.json
├── builds/                        # Build artifacts
│   └── {workflow-name}/
└── config.yml                     # User preferences

State File Format

View workflows.json Schema

{
  "workflows": {
    "my-workflow": {
      "name": "my-workflow",
      "directory_path": "/path/to/build/dir/",
      "created_at": "2024-10-30T12:51:39.000Z",
      "workflow_definition_arn": "arn:aws:nova-act:us-east-1:123456789012:workflow-definition/my-workflow",
      "deployments": {
        "agentcore": {
          "deployment_arn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/my_workflow_abc123",
          "image_uri": "123456789012.dkr.ecr.us-east-1.amazonaws.com/nova-act-cli-default:my-workflow-20241030-125139",
          "image_tag": "my-workflow-20241030-125139"
        }
      },
      "metadata": null,
      "last_image_tag": "my-workflow-20241030-125139"
    }
  },
  "last_updated": "2024-10-30T12:51:39.000Z",
  "version": "1.0"
}

State Schema Fields

WorkflowInfo Fields

Field	Type	Description
`name`	string	Workflow identifier
`directory_path`	string	Path to source/build directory (updated on each deployment)
`created_at`	timestamp	Workflow creation timestamp
`workflow_definition_arn`	string	ARN of associated WorkflowDefinition (optional)
`deployments.agentcore`	object	AgentCore deployment information
`metadata`	object	Custom metadata dictionary (optional)
`last_image_tag`	string	Most recent image tag used

AgentCore Deployment Fields

Field	Type	Description
`deployment_arn`	string	ARN of AgentCore runtime
`image_uri`	string	Full ECR image URI
`image_tag`	string	Image tag used for deployment

File Locking

The CLI uses file locking to protect concurrent operations:

# Lock files are automatically created
~/.act_cli/state/123456789012-us-east-1.lock

Lock Timeout: 30 secondsIf a CLI operation is already in progress, subsequent commands wait up to 30 seconds for the lock to be released.

State Isolation

State is isolated by:

AWS Account ID: Each account has its own directory
Region: Each region has its own state file

# Operations in us-east-1
act workflow create --name workflow-a --region us-east-1

# Operations in us-west-2 (completely isolated)
act workflow create --name workflow-a --region us-west-2

# Same workflow name, different regions, no conflicts

User Configuration

Config File Location

User preferences are stored in:

~/.act_cli/config.yml

Config File Format

View config.yml Schema

theme:
  name: default  # Options: default, minimal, none
  enabled: true

default_region: us-east-1

# Future configuration options will be added here

Theme Configuration

Customize CLI output styling:

Default Theme
Minimal Theme
No Theme

Full color output with emojis and styling:

config.yml

theme:
  name: default
  enabled: true

Best for:

Interactive terminal usage
Development environments
Colorful, rich output

Reduced colors for readability:

config.yml

theme:
  name: minimal
  enabled: true

Best for:

Terminals with limited color support
Accessibility needs
Simplified output

Plain text output without styling:

config.yml

theme:
  name: none
  enabled: true

Best for:

CI/CD pipelines
Log parsing and automation
Scripting

Theme via Environment Variable

Override theme configuration:

# Set for current session
export ACT_CLI_THEME=none
act workflow deploy --source-dir /path/to/code

# Set for single command
ACT_CLI_THEME=minimal act workflow list

Default Region

Set a default region for all commands:

config.yml

default_region: us-east-1

Override with --region flag:

act workflow deploy --name my-workflow --region us-west-2

AWS Profiles

The CLI supports AWS credential profiles from ~/.aws/credentials.

Configure Profiles

Create multiple profiles:

~/.aws/credentials

[default]
aws_access_key_id = DEFAULT_ACCESS_KEY
aws_secret_access_key = DEFAULT_SECRET_KEY

[development]
aws_access_key_id = DEV_ACCESS_KEY
aws_secret_access_key = DEV_SECRET_KEY

[production]
aws_access_key_id = PROD_ACCESS_KEY
aws_secret_access_key = PROD_SECRET_KEY
role_arn = arn:aws:iam::123456789012:role/ProductionRole

Use Profiles

Important: The --profile option must come before the subcommand.

# ✅ Correct: Profile before subcommand
act workflow --profile development deploy --name my-workflow --source-dir ./code

# ❌ Incorrect: Profile after subcommand
act workflow deploy --profile development --name my-workflow --source-dir ./code

Profile Examples

Deploy with Profile
Run with Profile
List with Profile
Multiple Operations

act workflow --profile production deploy \
  --name customer-workflow \
  --source-dir ./code

act workflow --profile development run \
  --name test-workflow \
  --payload '{}'

act workflow --profile production list

# Create in development
act workflow --profile development create --name dev-workflow

# Deploy to production
act workflow --profile production deploy \
  --name prod-workflow \
  --source-dir ./code

# Run in both environments
act workflow --profile development run --name dev-workflow --payload '{}'
act workflow --profile production run --name prod-workflow --payload '{}'

Environment Variables

CLI Environment Variables

Configure CLI behavior:

Variable	Description	Values
`ACT_CLI_THEME`	Output styling theme	`default`, `minimal`, `none`
`AWS_PROFILE`	Default AWS profile	Profile name from `~/.aws/credentials`
`AWS_DEFAULT_REGION`	Default AWS region	AWS region code (e.g., `us-east-1`)
`AWS_ACCESS_KEY_ID`	AWS access key	AWS access key
`AWS_SECRET_ACCESS_KEY`	AWS secret key	AWS secret key

Set CLI Environment Variables

# Output theme
export ACT_CLI_THEME=minimal

# AWS configuration
export AWS_PROFILE=production
export AWS_DEFAULT_REGION=us-east-1

# Or set credentials directly
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"

Workflow Environment Variables

Pass environment variables to your workflow at runtime using AC_HANDLER_ENV:

act workflow run --name my-workflow --payload '{
  "AC_HANDLER_ENV": {
    "NOVA_ACT_API_KEY": "your-api-key-here",
    "DEBUG": "true",
    "LOG_LEVEL": "info"
  },
  "input": "data"
}'

How It Works

Include AC_HANDLER_ENV in Payload

Add environment variables to the payload:

{
  "AC_HANDLER_ENV": {
    "NOVA_ACT_API_KEY": "your-key",
    "CUSTOM_VAR": "value"
  },
  "input": "your workflow input"
}

AgentCore Extracts Variables

The AgentCore handler automatically:

Extracts AC_HANDLER_ENV from payload
Sets variables in os.environ
Removes AC_HANDLER_ENV from payload before passing to your workflow

Access in Workflow Code

Use os.environ in your workflow:

main.py

import os

def main(payload):
    # Access environment variables
    api_key = os.environ.get("NOVA_ACT_API_KEY")
    debug = os.environ.get("DEBUG", "false") == "true"
    
    if debug:
        print(f"API Key: {api_key[:4]}...")
    
    # Your workflow logic
    input_data = payload.get("input")
    return {"result": f"Processed: {input_data}"}

Common Use Cases

API Keys and Credentials

Pass sensitive credentials without hardcoding:

act workflow run --name my-workflow --payload '{
  "AC_HANDLER_ENV": {
    "NOVA_ACT_API_KEY": "prod-key-12345",
    "DATABASE_URL": "postgresql://...",
    "STRIPE_API_KEY": "sk_live_..."
  },
  "order_id": "12345"
}'

Feature Flags

Enable/disable features dynamically:

act workflow run --name my-workflow --payload '{
  "AC_HANDLER_ENV": {
    "ENABLE_CACHING": "true",
    "ENABLE_RETRY": "false",
    "MAX_RETRIES": "3"
  },
  "input": "data"
}'

Debug Configuration

Control logging and debugging:

act workflow run --name my-workflow --payload '{
  "AC_HANDLER_ENV": {
    "DEBUG": "true",
    "LOG_LEVEL": "debug",
    "TRACE_ENABLED": "true"
  },
  "input": "test"
}'

Environment-Specific Settings

Test with different configurations:

# Development
act workflow run --name my-workflow --payload '{
  "AC_HANDLER_ENV": {
    "ENVIRONMENT": "development",
    "API_ENDPOINT": "https://dev.api.example.com"
  },
  "input": "test"
}'

# Production
act workflow run --name my-workflow --payload '{
  "AC_HANDLER_ENV": {
    "ENVIRONMENT": "production",
    "API_ENDPOINT": "https://api.example.com"
  },
  "input": "real-data"
}'

Benefits of AC_HANDLER_ENV

No Redeployment

Change configuration without rebuilding containers

Per-Execution Config

Pass different credentials for each run

Security

Keep secrets out of code and containers

Testing

Test with different settings instantly

Region Configuration

Set Default Region

Configure a default region:

~/.act_cli/config.yml

default_region: us-east-1

Or via environment variable:

export AWS_DEFAULT_REGION=us-east-1

Override Region

Specify region per command:

# Create in specific region
act workflow create --name my-workflow --region us-west-2

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

# Run in specific region
act workflow run --name my-workflow --payload '{}' --region us-west-2

Region Precedence

Region resolution order:

--region command flag (highest priority)
AWS_DEFAULT_REGION environment variable
default_region in ~/.act_cli/config.yml
AWS CLI default region from ~/.aws/config

Important: The AWS Nova Act service is currently only available in us-east-1.

File Locations Reference

User Data

Path	Description
`~/.act_cli/state/{account_id}/{region}/workflows.json`	Region-specific workflow state
`~/.act_cli/config.yml`	User configuration
`~/.act_cli/builds/{workflow-name}/`	Build artifacts (persistent)

Lock Files

Path	Description
`~/.act_cli/state/{account_id}-{region}.lock`	Temporary lock for concurrent access

AWS Configuration

Path	Description
`~/.aws/credentials`	AWS access keys and profiles
`~/.aws/config`	AWS CLI configuration

Configuration Best Practices

Use Profiles for Multiple Accounts

Separate development and production:

~/.aws/credentials

[dev]
aws_access_key_id = DEV_KEY
aws_secret_access_key = DEV_SECRET

[prod]
aws_access_key_id = PROD_KEY
aws_secret_access_key = PROD_SECRET

# Development workflow
act workflow --profile dev create --name test-feature
act workflow --profile dev deploy --name test-feature --source-dir ./code

# Production workflow
act workflow --profile prod deploy --name stable-feature --source-dir ./code

Set Default Region

Configure your primary region to avoid repetitive --region flags:

~/.act_cli/config.yml

default_region: us-east-1

Use Environment Variables for CI/CD

In CI/CD pipelines, use environment variables:

.github/workflows/deploy.yml

env:
  AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
  AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
  AWS_DEFAULT_REGION: us-east-1
  ACT_CLI_THEME: none

steps:
  - run: act workflow deploy --name production-workflow --source-dir ./code

Pass Secrets via AC_HANDLER_ENV

Never hardcode secrets in code:

# ❌ Bad: Secrets in code
# main.py
API_KEY = "hardcoded-key"  # Don't do this!

# ✅ Good: Secrets in payload
act workflow run --name my-workflow --payload '{
  "AC_HANDLER_ENV": {
    "API_KEY": "your-key"
  }
}'

# main.py
import os

def main(payload):
    api_key = os.environ.get("API_KEY")  # ✅ Read from environment

Clean Up Build Artifacts

Periodically remove old builds:

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

# Remove builds older than 30 days
find ~/.act_cli/builds -type d -mtime +30 -exec rm -rf {} +

Troubleshooting Configuration

State File Corruption

Symptom: CLI fails to read workflow stateSolution:

# Backup corrupted state
cp ~/.act_cli/state/123456789012/us-east-1/workflows.json \
   ~/.act_cli/state/123456789012/us-east-1/workflows.json.backup

# Reset state (WARNING: Loses local configuration)
rm ~/.act_cli/state/123456789012/us-east-1/workflows.json

# Recreate workflows
act workflow create --name my-workflow

Profile Not Found

Error:

Profile 'production' not found in ~/.aws/credentials

Solution:

# List available profiles
cat ~/.aws/credentials | grep '\['

# Configure missing profile
aws configure --profile production

Region Mismatch

Issue: Workflow not found in specified regionSolution:

# Check all regions
ls ~/.act_cli/state/123456789012/

# View workflows in specific region
act workflow list --region us-east-1
act workflow list --region us-west-2

Lock File Stuck

Symptom: CLI hangs waiting for lockSolution:

# Remove stale lock file
rm ~/.act_cli/state/123456789012-us-east-1.lock

# Retry operation
act workflow deploy --name my-workflow --source-dir ./code

Only remove lock files if you’re certain no other CLI operations are running.

Next Steps

Commands Reference

Explore all CLI commands

Deployment Guide

Deploy your workflows

CLI Overview

Learn about CLI features

Installation

Install and configure prerequisites

CLI Reference

​Configuration Overview

​State Management

​State File Structure

​State File Format

​State Schema Fields

​WorkflowInfo Fields

​AgentCore Deployment Fields

​File Locking

​State Isolation

​User Configuration

​Config File Location

​Config File Format

​Theme Configuration

​Theme via Environment Variable

​Default Region

​AWS Profiles

​Configure Profiles

​Use Profiles

​Profile Examples

​Environment Variables

​CLI Environment Variables

​Set CLI Environment Variables

​Workflow Environment Variables

​How It Works

​Common Use Cases

​Benefits of AC_HANDLER_ENV

No Redeployment

Per-Execution Config

Security

Testing

​Region Configuration

​Set Default Region

​Override Region

​Region Precedence

​File Locations Reference

​User Data

​Lock Files

​AWS Configuration

​Configuration Best Practices

​Troubleshooting Configuration

​Next Steps

Commands Reference

Deployment Guide

CLI Overview

Installation

Build docs developers (and LLMs) love

Configuration Overview

State Management

State File Structure

State File Format

State Schema Fields

WorkflowInfo Fields

AgentCore Deployment Fields

File Locking

State Isolation

User Configuration

Config File Location

Config File Format

Theme Configuration

Theme via Environment Variable

Default Region

AWS Profiles

Configure Profiles

Use Profiles

Profile Examples

Environment Variables

CLI Environment Variables

Set CLI Environment Variables

Workflow Environment Variables

How It Works

Common Use Cases

Benefits of AC_HANDLER_ENV

Region Configuration

Set Default Region

Override Region

Region Precedence

File Locations Reference

User Data

Lock Files

AWS Configuration

Configuration Best Practices

Troubleshooting Configuration

Next Steps