Documentation: .env.local only works for agentcore dev, not agentcore deploy

[xinghaohuang91]

Title:

Documentation: .env.local only works for agentcore dev, not agentcore deploy

Labels:

documentation, enhancement

Description:

Problem

The documentation doesn't clearly explain that .env.local only provides environment variables for local development (agentcore dev), and is not deployed to AWS when running agentcore deploy. This leads to confusion when agents work locally but fail in production due to missing environment variables.

Expected Behavior

Documentation should clearly state:

1. .env.local is loaded during agentcore dev only
2. .env.local is gitignored and NOT uploaded during deployment
3. For production deployments, users must use either:
   • envVars array in agentcore.json (not recommended for secrets)
   • AWS Secrets Manager (recommended for sensitive data)

Actual Behavior

Current documentation mentions .env.local but doesn't clarify its scope. Users naturally assume that if .env.local works locally, it will also work when deployed.

Current project structure documentation:

agentcore/
├── .env.local          # Secrets — API keys (gitignored)

This suggests .env.local is for secrets, but doesn't explain it's local-only.

User Impact

1. Confusion: Agent works with agentcore dev, fails after agentcore deploy
2. Debugging time: Users spend time troubleshooting why environment variables are missing in production
3. Security risk: Some users might add credentials to envVars in agentcore.json and accidentally commit to git

Real-World Example

Use case: Deploying an agent that needs external API credentials

Local (works):

# .env.local
API_KEY=xxx
API_SECRET=yyy

# Agent code
api_key = os.getenv("API_KEY")  # ✅ Works with agentcore dev

Deployed (fails):

agentcore deploy  # .env.local not uploaded
# Runtime error: Missing API_KEY

Suggested Documentation Improvements

1. Add clear section in README:

## Environment Variables

### Local Development
Use `.env.local` for local development with `agentcore dev`:
- Automatically loaded by the CLI
- Gitignored (never committed)
- **NOT deployed to AWS**

### Production Deployment
For deployed agents, choose one:

**Option A: envVars in agentcore.json** (not recommended for secrets)
```json
{
  "runtimes": [{
    "envVars": [
      {"name": "API_KEY", "value": "xxx"}
    ]
  }]
}

⚠️ Warning: This file is typically committed to git. Do not store secrets here.

Option B: AWS Secrets Manager (recommended)

import boto3
client = boto3.client("secretsmanager")
secrets = json.loads(client.get_secret_value(SecretId="my-secret")["SecretString"])

2. **Add warning in CLI output:**

$ agentcore deploy
⚠️ Note: .env.local is not deployed. Use envVars in agentcore.json or AWS Secrets Manager for production credentials.

### Additional Context
- This is a common pattern confusion in serverless deployments
- Similar tools (Vercel, Netlify) clearly document local vs production env behavior
- AgentCore CDK constructs don't have built-in Secrets Manager integration

### Related Issues
- Missing: Built-in pattern for AWS Secrets Manager integration
- Missing: Example templates showing production credential management