Configuration & Secrets Management

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• deploy/cloudformation.yml
• entrypoint.sh
• src/main.ts
• src/agent/setup.ts
• src/config.ts

The configuration and secrets management system for pi-digby provides a secure, multi-layered approach to handling environment variables, API credentials, and application settings. The system leverages AWS-native services for secret storage and identity-based access, while using a persistent Elastic File System (EFS) to maintain configuration state across container restarts.

At a high level, the system distinguishes between infrastructure-level secrets (e.g., Slack tokens), runtime environment variables, and application-specific configurations (e.g., MCP server settings). Integration with AWS Secrets Manager ensures that sensitive data is never hardcoded or stored in the repository, while the entrypoint.sh script handles the injection and substitution of these secrets into the application's configuration files during boot.

Sources: CLAUDE.md:1-40, deploy/cloudformation.yml:143-157

Secret Management Architecture

The project utilizes AWS Secrets Manager as the primary source of truth for sensitive credentials. The CloudFormation template defines a single secret resource named pi-digby/env, which contains a JSON object of key-value pairs.

Secrets Lifecycle and Injection

The deployment process decouples the creation of the secret resource from the management of its values. Values are populated via the AWS CLI, ensuring they remain outside the CloudFormation stack's state. During the ECS Task execution, the TaskExecutionRole retrieves these values and injects them as environment variables into the container.

This diagram shows the flow of secrets from manual entry via CLI to the running container components.
Sources: deploy/cloudformation.yml:143-157, deploy/cloudformation.yml:400-435

Managed Secrets

The following table lists the primary secrets managed via AWS Secrets Manager and their purpose in the application:

Secret Key	Purpose	Derived Usage
MOM_SLACK_APP_TOKEN	Slack App-level token	Socket Mode connection
MOM_SLACK_BOT_TOKEN	Slack Bot OAuth token	Web API calls and downloads
BROWSER_USE_API_KEY	Browser-use CLI key	Cloud-based web browsing
EXA_API_KEY	Exa search API key	MCP server search functionality
GH_TOKEN	GitHub Personal Access Token	Repo management and Claude Code
LINEAR_API_KEY	Linear API credential	Linear agent integration
CLOUDFLARE_TUNNEL_TOKEN	Cloudflare Tunnel token	Exposing internal webhooks

Sources: CLAUDE.md:52-60, deploy/cloudformation.yml:410-435

Runtime Configuration Handling

Runtime configuration is managed through a combination of environment variables and configuration files stored on persistent storage.

Environment Variable Validation

The application's entry point validates essential environment variables before initialization. If required Slack tokens are missing, the process exits immediately to prevent invalid state.

const MOM_SLACK_APP_TOKEN = process.env.MOM_SLACK_APP_TOKEN;
const MOM_SLACK_BOT_TOKEN = process.env.MOM_SLACK_BOT_TOKEN;

if (!MOM_SLACK_APP_TOKEN || !MOM_SLACK_BOT_TOKEN) {
	console.error("Missing env: MOM_SLACK_APP_TOKEN, MOM_SLACK_BOT_TOKEN");
	process.exit(1);
}

Sources: src/main.ts:32-45

Configuration Persistence via EFS

To ensure that configurations like MCP (Model Context Protocol) server lists and authentication tokens survive container restarts, pi-digby mounts an EFS volume at /data. The entrypoint.sh script performs several symlinking and seeding operations:

1. MCP Config Seeding: If /data/.pi/mcp.json does not exist, it is seeded from the repository default at /app/.pi/mcp.json.
2. Environment Substitution: The script uses sed to replace placeholders in the configuration file (e.g., EXA_API_KEY_PLACEHOLDER) with actual environment variable values.
3. Symlinking: Configuration directories like .pi, .gitconfig, and .cache are symlinked from the ephemeral /root directory to the persistent /data mount.

# entrypoint.sh: Substitute env vars into MCP config URLs
if [ -n "$EXA_API_KEY" ]; then
  sed -i "s|EXA_API_KEY_PLACEHOLDER|$EXA_API_KEY|g" /data/.pi/mcp.json
fi

Sources: entrypoint.sh:1-35, CLAUDE.md:10-15

IAM-Based Authentication

For AWS-native services like Amazon Bedrock, the system eschews static credentials (Access Keys) in favor of IAM Roles for Tasks.

Bedrock Authorization Logic

The application checks for several environment indicators to determine if it is running in an authenticated AWS environment (like ECS) before attempting to call the LLM.

This flow demonstrates the fallback logic for identifying available AWS authentication methods.
Sources: src/agent/setup.ts:47-62

The TaskRole (defined in CloudFormation) provides the necessary permissions to invoke Bedrock models and interact with CloudWatch logs without requiring secret injection for these specific operations.
Sources: deploy/cloudformation.yml:195-210

External Service Integrations

Certain features require specific configuration patterns. For instance, the Linear agent integration is conditionally enabled only if its specific environment variables are present in the system.

Service	Condition for Activation	Configuration Source
Linear	LINEAR_API_KEY && LINEAR_WEBHOOK_SECRET	Environment Variables
Cloudflare	CLOUDFLARE_TUNNEL_TOKEN	Environment Variable
Datadog	DD_API_KEY, DD_APP_KEY, DD_SITE	Environment Variables

Sources: src/main.ts:221-230, deploy/cloudformation.yml:405-430, entrypoint.sh:53-57

Conclusion

The Configuration & Secrets Management system in pi-digby balances security and portability. By utilizing AWS Secrets Manager for sensitive tokens, IAM roles for service-to-service communication, and persistent EFS storage for application-level state, the project ensures that the bot remains resilient to container replacement while maintaining a minimal security surface area. Management of these values is simplified through automated injection and placeholder substitution during the container boot process.