Sandbox Environment

The Amplify sandbox provides a personal cloud environment for development and testing. Learn how to effectively use and manage your sandbox.

What is Sandbox?

The sandbox is a personal development environment that deploys real AWS resources for testing. Each developer gets their own isolated sandbox, preventing conflicts during development.

Starting the Sandbox

# Start sandbox with default profile
npx ampx sandbox

# Use a specific AWS profile
npx ampx sandbox --profile your-profile-name

# Specify a custom identifier (useful for multiple sandboxes)
npx ampx sandbox --identifier my-feature

When you start the sandbox, Amplify:

1. Synthesizes CDK templates from your backend code
2. Deploys CloudFormation stacks to AWS
3. Generates amplify_outputs.json for your frontend
4. Watches for file changes and redeploys automatically

Understanding Sandbox Output

$ npx ampx sandbox

ampx sandbox

  Amplify Sandbox

  ✔ Synthesized backend definition successfully.
  
  Watching for file changes...
  
  CloudFormation deployment completed.
  
  ✔ Deployed data/resource.ts
    Table: Todo-abc123xyz
    GraphQL API: https://xxxxx.appsync-api.us-east-1.amazonaws.com/graphql
  
  ✔ Deployed auth/resource.ts
    User Pool: us-east-1_XXXXXXX
    Identity Pool: us-east-1:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  
  ✔ Generated amplify_outputs.json

Hot Reload

The sandbox watches your files and automatically redeploys when you make changes. This works for:

• Data model changes (amplify/data/resource.ts)
• Auth configuration changes (amplify/auth/resource.ts)
• Lambda function code (amplify/functions/**)
• Backend configuration (amplify/backend.ts)

Sandbox Commands

Command	Description
npx ampx sandbox	Start/update sandbox
npx ampx sandbox delete	Delete sandbox resources
npx ampx sandbox secret	Manage sandbox secrets
npx ampx generate outputs	Regenerate amplify_outputs.json
npx ampx generate graphql-client-code	Regenerate TypeScript types

Managing Secrets

For sensitive values like API keys, use sandbox secrets instead of environment variables:

# Set a secret
npx ampx sandbox secret set MY_API_KEY

# List secrets
npx ampx sandbox secret list

# Remove a secret
npx ampx sandbox secret remove MY_API_KEY

Access secrets in your Lambda functions:

// amplify/functions/my-function/handler.ts
import { env } from '$amplify/env/my-function';

export const handler = async () => {
  const apiKey = env.MY_API_KEY;
  // Use the secret...
};

Multiple Sandboxes

Work on multiple features simultaneously with different sandbox identifiers:

# Feature A sandbox
npx ampx sandbox --identifier feature-a

# Feature B sandbox (different terminal)
npx ampx sandbox --identifier feature-b

Each identifier creates a separate set of AWS resources. Remember to delete them when done!

Viewing Resources in AWS Console

Sandbox resources are visible in the AWS Console:

1. Go to CloudFormation
2. Look for stacks starting with amplify-
3. Click on a stack to see its resources

You can also navigate directly to:

• DynamoDB: View tables and data
• Cognito: View users and settings
• AppSync: Test GraphQL queries
• Lambda: View and test functions

Deleting the Sandbox

Always delete your sandbox when you're done working to avoid unnecessary AWS charges:

# Delete the default sandbox
npx ampx sandbox delete

# Delete a specific sandbox
npx ampx sandbox delete --identifier feature-a

# Delete without confirmation prompt
npx ampx sandbox delete --yes

Troubleshooting

Sandbox Won't Start

# Check AWS credentials
aws sts get-caller-identity

# Check if CDK is bootstrapped
npx cdk bootstrap

# Try with verbose output
npx ampx sandbox --debug

Changes Not Deploying

# Stop sandbox (Ctrl+C) and restart
npx ampx sandbox

# Force regenerate outputs
npx ampx generate outputs --force

Type Errors After Schema Changes

# Regenerate types
npx ampx generate graphql-client-code

# Restart TypeScript server in VS Code
# Ctrl+Shift+P → TypeScript: Restart TS Server

Best Practices

• ✅ Delete sandbox at end of each day/session
• ✅ Use secrets for sensitive configuration
• ✅ Use sandbox identifiers for feature branches
• ✅ Watch terminal output for deployment errors
• ❌ Don't commit amplify_outputs.json to git
• ❌ Don't store production data in sandbox
• ❌ Don't share sandbox resources between developers

Summary

• Sandbox provides personal cloud environments for development
• Start with npx ampx sandbox
• Changes hot-reload automatically
• Delete with npx ampx sandbox delete when done
• Use identifiers for multiple sandboxes
• Store secrets with npx ampx sandbox secret