Agent-Guided Secret Synchronisation

SecretZero's agent sync feature enables AI agents and automation tools to autonomously manage secrets while gracefully handling scenarios that require manual intervention.

Overview

When an AI agent clones a project with a Secretfile, it can run:

secretzero agent sync

This intelligently:

• ✅ Auto-generates secrets that require no external input (random passwords, UUIDs, etc.)
• 📋 Provides step-by-step instructions for secrets that require manual acquisition
• 🔄 Handles mixed automation scenarios gracefully

Quick Start

# Human-readable output (default)
secretzero agent sync

# Machine-readable JSON for further processing
secretzero agent sync --json

# Preview changes without applying them
secretzero agent sync --dry-run

# Interactively supply values for pending secrets
secretzero agent sync --interactive

Use Cases

1. Autonomous Project Bootstrapping

An AI agent clones a new project and sets up all secrets automatically:

# Agent runs this and processes the structured output
secretzero agent sync --json

The agent receives:

• Auto-synced secrets (database passwords, encryption keys)
• Structured instructions for manual secrets (OAuth tokens, API keys)

2. CI/CD Pipeline Integration

# .github/workflows/setup.yml
- name: Sync auto-generated secrets
  run: secretzero agent sync --json > sync_result.json

- name: Process results
  run: |
    python - <<'EOF'
    import json
    result = json.load(open("sync_result.json"))
    for name, instructions in result["pending_secrets"].items():
        print(f"Manual action required for: {name}")
        print(f"  {instructions['summary']}")
    EOF

3. Interactive Setup

For user-assisted setup with agent guidance:

secretzero agent sync --interactive

The agent provides instructions, the user follows the steps, and the agent records the value.

Defining Agent Instructions

Add agent_instructions to any secret in your Secretfile:

secrets:
  - name: stripe_api_key
    kind: static
    config: {}
    agent_instructions:
      summary: "Sign up for Stripe and generate API key"
      steps:
        - action: "Visit https://dashboard.stripe.com/register"
          description: "Create a Stripe account"
        - action: "Navigate to Developers > API Keys"
          description: "Access API key management"
        - action: "Click 'Create secret key'"
          description: "Generate a new secret key"
        - action: "Copy the key (starts with sk_)"
          description: "Save securely – shown only once"
      automation_hint: "Manual only – requires email verification and business info"
      estimated_time: "5-10 minutes"
      fallback: "Request user assistance for Stripe account creation"
      documentation_url: "https://stripe.com/docs/keys"

Field Reference

Field	Required	Description
summary	✅	Brief overview of the acquisition process
steps	✅	Ordered list of steps to follow
prerequisites	❌	Requirements before starting
automation_hint	❌	Guidance on automation feasibility
estimated_time	❌	Expected time to complete
fallback	❌	What to do if automation fails
required_tools	❌	CLI tools or dependencies needed
documentation_url	❌	Link to official documentation

Each step has the following fields:

Field	Required	Description
action	✅	CLI command, URL, or description of what to do
description	✅	Human-readable context explaining why
params	❌	Optional key-value parameters for API calls
required	❌	Whether the step is mandatory (default: true)

Automation Levels

SecretZero classifies secrets by automation feasibility using the automation_hint field and the generator type:

Fully Automated

Can be completed without any human intervention:

• random_password and random_string generators
• Secrets sourced from authenticated CLIs when automation_hint contains "fully automat"

Semi-Automated

The agent can automate parts, but user input is needed:

• OAuth Device Flows (agent polls, user approves in browser)
• When automation_hint does not match fully-automated or manual-only patterns

Manual Only

Requires full manual intervention:

• Third-party service sign-ups
• Email verification flows
• automation_hint contains "manual only" or "manual"

Requires Approval

Technically automatable but blocked by policy:

• automation_hint contains "approval"

Output Formats

Human-Readable (default)

✅ Successfully synced 2 secret(s):
  • database_password
  • jwt_secret

⏳ 1 secret(s) require manual intervention:

──────────────── stripe_api_key ────────────────
  Summary: Sign up for Stripe and generate API key

  Steps:
    1. Visit https://dashboard.stripe.com/register
       Create a Stripe account
    2. Navigate to Developers > API Keys
       Access API key management
    ...

  💡 Automation: Manual only – requires email verification
  ⏱️  Estimated time: 5-10 minutes
  📚 Docs: https://stripe.com/docs/keys

📊 Summary:
  Synced:   2
  Pending:  1
  Failed:   0

JSON Output

secretzero agent sync --json

{
  "synced_secrets": ["database_password", "jwt_secret"],
  "pending_secrets": {
    "stripe_api_key": {
      "summary": "Sign up for Stripe and generate API key",
      "steps": [
        {
          "action": "Visit https://dashboard.stripe.com/register",
          "description": "Create a Stripe account",
          "required": true
        }
      ],
      "automation_hint": "Manual only – requires email verification",
      "estimated_time": "5-10 minutes"
    }
  },
  "failed_secrets": {},
  "automation_summary": {
    "fully_synced": 2,
    "requires_intervention": 1,
    "failed": 0
  }
}

Integrating with AI Agent Workflows

import subprocess
import json

result = subprocess.run(
    ["secretzero", "agent", "sync", "--json"],
    capture_output=True,
    text=True,
)
sync_data = json.loads(result.stdout)

# Auto-synced secrets are ready to use
for secret in sync_data["synced_secrets"]:
    print(f"✅ {secret} is ready")

# Decide how to handle pending secrets
for name, instructions in sync_data["pending_secrets"].items():
    hint = instructions.get("automation_hint", "")
    if "fully automat" in hint.lower():
        follow_instructions(instructions["steps"])
    else:
        delegate_to_user(name, instructions)

Best Practices

Writing Effective Agent Instructions

1. Be specific: Provide exact URLs, commands, and parameters.
2. Provide context: Explain why each step is needed, not just what to do.
3. Set realistic expectations: Include estimated_time and complexity hints.
4. Provide fallbacks: Specify what the agent should do if automation fails.
5. Link to documentation: Include documentation_url for official references.

For Fully Automatable Secrets

If a secret can be created via an API, provide the exact commands:

agent_instructions:
  steps:
    - action: "curl -X POST https://api.example.com/v1/keys -H 'Authorization: Bearer $TOKEN'"
      description: "Generate API key via REST API"
      params:
        name: "terraform-key"
        scopes: ["read", "write"]
  automation_hint: "Fully automated if TOKEN is set"

For Manual Secrets

Provide detailed, step-by-step browser guidance:

agent_instructions:
  steps:
    - action: "Open browser to https://console.example.com"
      description: "Access the service web interface"
    - action: "Click Settings → API Keys → Generate New Key"
      description: "Navigate to the key generation interface"
  automation_hint: "Manual only – requires browser interaction"

Keeping Secrets Safe

Never include actual credentials in agent_instructions. Reference environment variables or placeholder names instead:

# ✅ Correct
prerequisites:
  - "AWS CLI must be authenticated (run 'aws configure')"

# ❌ Wrong – exposes credentials
prerequisites:
  - "Set AWS_SECRET_ACCESS_KEY=AKIAIOSFODNN7EXAMPLE"

See Also

• Configuration Reference
• Generator Types
• Target Types
• CLI Reference