Docs › Reference › Security

Security Guide

**Version:** 1.1 **Last Updated:** 2026-06-22

Comprehensive security guidelines for using Babysitter in development and production environments. This guide covers best practices for handling code, credentials, and network security.

---

On this page

- Best Practices - .gitignore Configuration

- Environment Variables - Breakpoints for Sensitive Operations - Journal File Review - Secrets in the Adapters CLI and CI Triggers

- Reviewing Generated Code - Security Test Coverage - Security Scanning

• Overview
• General Security
• Credential Management
• Tamper-Evident Approvals
• Code Review Security
• Network Security
• Compliance Considerations
• Related Documentation

---

Overview

Babysitter handles code generation, execution, and may interact with credentials during workflows. Following proper security practices ensures that:

• Sensitive data is not exposed in logs or version control
• Production systems are protected through approval gates
• Network services are properly secured
• Audit trails are maintained for compliance

---

General Security

Best Practices

**DO:**

• Review all code changes before final approval
• Use breakpoints before deploying to production
• Keep .a5c/ directories out of version control (add to .gitignore)
• Regularly update to latest versions
• Run with least privilege necessary

**DON'T:**

• Commit .a5c/ directories with sensitive data
• Run untrusted process definitions without review
• Store credentials in journal files

.gitignore Configuration

Ensure your .gitignore includes:

# Babysitter run data
.a5c/

# Environment files with secrets
.env
.env.local
.env.*.local

# Credentials
*.pem
*.key
credentials.json

---

Credential Management

Environment Variables

Use environment variables for secrets (recommended):

// In process definition
const apiKey = process.env.API_KEY;
await ctx.task(deployTask, { apiKey });

**Never hardcode credentials:**

// BAD - Don't do this!
const apiKey = "sk-1234567890abcdef";

// GOOD - Use environment variables
const apiKey = process.env.API_KEY;

Breakpoints for Sensitive Operations

Use breakpoints to require human approval for sensitive operations:

await ctx.breakpoint({
  question: 'Deploy with production credentials?',
  title: 'Production Deployment',
  context: { environment: 'production', critical: true }
});

Journal File Review

Review journal files before sharing to ensure no secrets were leaked:

# Check for leaked secrets
grep -i "password\|secret\|key\|token" .a5c/runs/*/journal/*.json

**Security tip:** Always set BABYSITTER_ALLOW_SECRET_LOGS=false in production to prevent sensitive data from appearing in logs.

Secrets in the Adapters CLI and CI Triggers

The host-side adapters CLI (package @a5c-ai/adapters-cli) launches and authenticates harnesses on your machine, so it can touch provider credentials. Keep secrets out of arguments and shell history:

• **Prefer ambient credentials.** Use adapters auth check and adapters auth setup <agent> to verify and configure provider auth rather than passing keys inline. See the Adapters CLI Reference.
• **Avoid keys on the command line.** When launching a provider, prefer the provider's own credential chain over --api-key; for token-based providers use --auth-command to emit a short-lived bearer token instead of a static key. Anything passed as an argument may be captured in shell history and process listings.
• **Scope environment injection.** When passing variables into a run with adapters run --env KEY=VALUE, pass secret *names* sourced from your environment, never literal secret values.

For CI, Babysitter v6 **Triggers** normalize inbound webhooks from GitHub, GitLab, and Bitbucket (via the adapters-triggers action). Treat trigger pipelines like any other secret-bearing CI job:

• Store provider keys and tokens as CI secrets and reference them by name (e.g. repository/organization secrets), never inline in workflow files.
• Grant the workflow only the token scopes it needs.
• Be cautious with triggers that run on untrusted input (such as PRs from forks), which can expose secrets to attacker-controlled code.

See GitHub Actions Setup for end-to-end CI configuration.

---

Tamper-Evident Approvals

The **Breakpoints Adapter** (v6) records human-in-the-loop approvals to a durable backend and **cryptographically signs** each approval - the "proven" approval model. This makes the approval trail *verifiable* rather than merely *trusted*: you can confirm who approved what, and detect after-the-fact tampering, instead of relying on an unsigned log that could be edited.

This complements the journal audit trail: the journal records that an approval happened, while signed approvals let you cryptographically verify the record is authentic and unaltered.

The Breakpoints Adapter replaces the legacy breakpoints-pro package (now deprecated). For the approval workflow and how to route breakpoints to a durable backend, see Breakpoints.

---

Code Review Security

Reviewing Generated Code

Before approving breakpoints, review generated code for security issues:

• **SQL injection vulnerabilities** - Ensure parameterized queries are used
• **XSS vulnerabilities** - Check for proper output encoding
• **Insecure dependencies** - Review any new package additions
• **Hardcoded secrets** - Scan for API keys, passwords, tokens

Security Test Coverage

Check test coverage for security-related tests:

• Authentication tests
• Authorization tests
• Input validation tests
• Error handling tests

Security Scanning

Run security scans before approval:

const security = await ctx.task(securityScanTask, {
  tools: ['npm audit', 'eslint-plugin-security']
});

**Recommended security tools:**

---

Network Security

For Distributed Teams

1. **Use VPN** for secure access 2. **Implement authentication** on all services 3. **Use HTTPS** for all external connections 4. **Audit access logs** regularly

Network Configuration Checklist

---

Compliance Considerations

For Regulated Environments

Babysitter provides several features that support compliance requirements:

Audit Trail

Every action in Babysitter is logged in the journal:

# View complete event history for a run
cat .a5c/runs/<runId>/journal/*.json | jq .

# Filter for approval events (breakpoints resolve via EFFECT_RESOLVED)
jq 'select(.type=="EFFECT_RESOLVED")' .a5c/runs/*/journal/*.json

Data Retention Policy

Implement a cleanup policy for old runs:

# Example: Remove runs older than 30 days
find .a5c/runs -maxdepth 1 -type d -mtime +30 -exec rm -rf {} \;

Encryption at Rest

For sensitive environments, encrypt the .a5c/ directory:

# Using encrypted filesystem
# Mount encrypted volume at .a5c/

# Or use encryption tools
gpg --symmetric --cipher-algo AES256 .a5c/runs/sensitive-run/journal/000001.*.json

---

Related Documentation

• Breakpoints - Approval workflow and the Breakpoints Adapter ("proven" signed approvals)
• GitHub Actions Setup - CI configuration, Triggers, and secret handling
• Adapters CLI Reference - The host-side adapters CLI and its auth commands
• Configuration Reference - Environment variables and settings
• CLI Reference - Command-line options
• Troubleshooting - Common issues and solutions
• Glossary - Term definitions

---

Next steps

• **Next:** Configuration
• **Related:** Breakpoints, Troubleshooting