Agent Configuration

Each agent service is configured via environment variables. Shared variables are used by all agents; agent-specific variables are prefixed or scoped to that service.

Shared (all agents)

Variable	Default	Description
`NATS_URL`	—	NATS JetStream URL (required)
`DATABASE_HOST`	—	PostgreSQL host (omit for in-memory sessions)
`DATABASE_PASSWORD`	—	PostgreSQL password
`AWS_REGION`	`us-east-1`	AWS region for Bedrock
`LOG_LEVEL`	`info`	Structured log level
`ENVIRONMENT`	—	`local` or production identifier
`POSTHOG_PROJECT_API_KEY`	—	Enables LLM analytics and error tracking
`POSTHOG_PROJECT_ID`	—	Enables `/debug` command trace URLs
`JIRA_BASE_URL`	—	Jira instance URL (e.g., `https://fetchrewards.atlassian.net`)
`JIRA_EMAIL`	—	Jira account email for API authentication
`JIRA_API_TOKEN`	—	Jira API token (paired with email for basic auth)
`JIRA_PROJECT`	—	Default Jira project key for ticket creation

Buck

Variable	Default	Description
`PORT`	`8080`	HTTP server port
`SLACK_BOT_TOKEN`	—	Slack bot OAuth token (`xoxb-...`)
`SLACK_SIGNING_SECRET`	—	Slack app signing secret for webhook verification
`SLACK_FEED_CHANNEL_ID`	—	Channel for `post_to_feed` tool
`GITHUB_APP_ID`	—	GitHub App ID
`GITHUB_APP_INSTALLATION_ID`	—	GitHub App installation ID
`GITHUB_APP_PRIVATE_KEY`	—	GitHub App private key (PEM format)
`SOURCEGRAPH_TOKEN`	—	Sourcegraph API token for code search MCP
`BEDROCK_MODEL_ID`	`us.anthropic.claude-sonnet-4-20250514-v1:0`	AWS Bedrock model ID
`S3_BUCKET`	—	S3 bucket for session state persistence (pause/resume)
`CLOUDFRONT_DOMAIN`	—	CloudFront domain for permanent image URLs
`SESSION_POD_IMAGE`	—	Container image URI for session pods (enables EKS execution)
`EKS_NAMESPACE`	`bucky-sessions`	Kubernetes namespace for session pods
`SESSION_SERVICE_ACCOUNT`	`session-runner`	Kubernetes ServiceAccount for session pods
`POD_TOKEN_SECRET`	—	HMAC secret for signing pod-bound JWTs
`OKTA_ISSUER`	—	Okta OIDC issuer URL for dashboard JWT auth
`JIRA_ACCOUNT_ID`	—	Jira account ID for ticket assignment
`AGENT_BASE_URL`	—	Public URL of the agent service (for callbacks)
`PROMETHEUS_URL`	—	Prometheus query endpoint for metrics dashboard
`CELESTIALS_BASE_URL`	—	Base URL for celestials service (team/Pack lookups)

Dolly

Variable	Default	Description
`DOLLY_PORT`	`8081`	HTTP server port
`DOLLY_SLACK_BOT_TOKEN`	—	Slack bot OAuth token for Dolly
`DOLLY_SLACK_SIGNING_SECRET`	—	Slack app signing secret for Dolly webhooks
`DOLLY_JIRA_WEBHOOK_SECRET`	—	Secret for verifying Dolly’s Jira webhook payloads
`DOLLY_JIRA_ACCOUNT_ID`	—	Jira account ID for Dolly’s ticket assignment
`DOLLY_BEDROCK_MODEL_ID`	`us.anthropic.claude-opus-4-20250514-v1:0`	AWS Bedrock model ID
`GOOGLE_SERVICE_ACCOUNT_JSON`	—	Google service account credentials (JSON) for Drive access
`BUCK_SLACK_USER_ID`	—	Buck’s Slack user ID (for @mentions in handoffs)
`PEARL_SLACK_USER_ID`	—	Pearl’s Slack user ID (for @mentions in handoffs)

Pearl

Variable	Default	Description
`PEARL_PORT`	`8082`	HTTP server port
`PEARL_SLACK_BOT_TOKEN`	—	Slack bot OAuth token for Pearl
`PEARL_SLACK_SIGNING_SECRET`	—	Slack app signing secret for Pearl webhooks
`PEARL_JIRA_WEBHOOK_SECRET`	—	Secret for verifying Pearl’s Jira webhook payloads
`FIGMA_ACCESS_TOKEN`	—	Figma personal access token
`FIGMA_TEAM_ID`	—	Figma team ID for project browsing
`PEARL_BEDROCK_MODEL_ID`	`us.anthropic.claude-opus-4-20250514-v1:0`	AWS Bedrock model ID
`DOLLY_SLACK_USER_ID`	—	Dolly’s Slack user ID (for @mentions)
`BUCK_SLACK_USER_ID`	—	Buck’s Slack user ID (for @mentions)
`DASHBOARD_ORIGIN`	—	Allowed CORS origin for dashboard frontend

Local development

cd agent
cp .env.example .env  # fill in values
make run

For database sessions locally, start PostgreSQL and NATS with Docker:

cd agent
docker compose up -d

When DATABASE_HOST is unset, the agent falls back to InMemorySessionService — sessions are lost on restart but no database is needed. NATS is always required (NATS_URL=nats://localhost:4222).

For local Kubernetes (EKS session pods), use k3d:

cd agent
make k8s-setup  # bootstrap k3d cluster with namespace and secrets

Set KUBECONFIG_PATH to the k3d kubeconfig and SESSION_POD_IMAGE to a locally built image (make docker-build-base).

Deployment

Each agent is deployed to ECS via FSD. The deployment configs define:

ECR repositories: ad-tools-agent (Buck), ad-tools-dolly (Dolly), ad-tools-pearl (Pearl)
Environment variables: Plain values in environment_variables
Secrets: Sensitive values from AWS Secrets Manager in secrets
IAM policy: bedrock:InvokeModel on Claude models
Dependencies: Aurora PostgreSQL database, S3 buckets, CloudFront distribution, NATS JetStream cluster

Stage/prod-specific values are configured in the variables section of each FSD config.