Local Provider

The local provider is a special built-in provider for storing secrets directly on the local filesystem. Unlike other providers that connect to external systems, the local provider operates entirely on your local machine, making it ideal for development, testing, and scenarios where secrets need to be stored as files.

Overview

Property	Value
Provider Kind	local
Authentication	None required
Target Types	file, template
Use Cases	Local development, .env files, configuration files, template rendering

Features

• ✅ No external dependencies - Works immediately without configuration
• ✅ Multiple file formats - Supports dotenv, JSON, YAML, and TOML
• ✅ Template rendering - Generate configuration files from Jinja2 templates
• ✅ File merging - Optionally merge secrets with existing files
• ✅ Always available - Built into SecretZero, no installation needed

Configuration

The local provider does not require any configuration or authentication. Simply specify provider: local in your target configuration.

providers:
  local:
    kind: local  # Optional - local provider doesn't need explicit configuration

In most cases, you can use provider: local directly in targets without defining it in the providers section.

Target Types

File Target

Store secrets in local files with various formats.

Configuration Options:

Option	Type	Required	Default	Description
path	string	Yes	-	File path (relative or absolute)
format	string	Yes	-	File format: dotenv, json, yaml, toml
merge	boolean	No	true	Merge with existing file content

Example - .env file:

secrets:
  - name: database_password
    kind: random_password
    config:
      length: 32
    targets:
      - provider: local
        kind: file
        config:
          path: .env
          format: dotenv
          merge: true

Generated .env file:

DATABASE_PASSWORD=Xy9k2...random...

Example - JSON Configuration:

secrets:
  - name: api_credentials
    kind: static
    config:
      default: '{"key": "abc123", "secret": "xyz789"}'
    targets:
      - provider: local
        kind: file
        config:
          path: config/credentials.json
          format: json
          merge: false

Example - YAML Configuration:

secrets:
  - name: app_config
    kind: static
    config:
      default: |
        database:
          host: localhost
          port: 5432
        api:
          timeout: 30
    targets:
      - provider: local
        kind: file
        config:
          path: config.yaml
          format: yaml

Template Target

Render Jinja2 templates with secret values to generate configuration files.

Configuration Options:

Option	Type	Required	Default	Description
template_path	string	Yes	-	Path to Jinja2 template file
output_path	string	Yes	-	Path for rendered output file

Example Template (config.yaml.j2):

database:
  host: {{ db_host }}
  port: {{ db_port }}
  password: {{ db_password }}

api:
  key: {{ api_key }}
  endpoint: {{ api_endpoint }}

Secretfile configuration:

secrets:
  - name: app_config
    kind: templates.server_config
    config:
      db_host: localhost
      db_port: 5432
      db_password:
        generator: random_password
        length: 32
      api_key:
        generator: random_string
        length: 64
      api_endpoint: https://api.example.com
    targets:
      - provider: local
        kind: template
        config:
          template_path: config.yaml.j2
          output_path: config.yaml

File Formats

Dotenv Format

Standard .env file format for environment variables:

# Generated by SecretZero
DATABASE_URL=postgresql://localhost/mydb
API_KEY=abc123xyz789
SECRET_KEY=random_secret_value

Characteristics: - Key-value pairs: KEY=value - Comments start with # - No nested structures - Ideal for environment variables

JSON Format

Structured JSON for complex configurations:

{
  "database": {
    "password": "secret123",
    "url": "postgresql://localhost/mydb"
  },
  "api": {
    "key": "abc123",
    "secret": "xyz789"
  }
}

Characteristics: - Supports nested objects - Strict syntax - Good for structured data

YAML Format

Human-readable YAML configuration:

database:
  password: secret123
  url: postgresql://localhost/mydb

api:
  key: abc123
  secret: xyz789

Characteristics: - Indentation-based structure - Supports comments - Most readable format

TOML Format

Configuration file format popular in Rust/Python:

[database]
password = "secret123"
url = "postgresql://localhost/mydb"

[api]
key = "abc123"
secret = "xyz789"

Characteristics: - Section-based structure - Type-safe values - Good for configuration files

Common Use Cases

Local Development Environment

Create a complete .env file for local development:

version: '1.0'

secrets:
  - name: db_password
    kind: random_password
    config:
      length: 16
      special: false
    targets:
      - provider: local
        kind: file
        config:
          path: .env
          format: dotenv
          merge: true

  - name: jwt_secret
    kind: random_string
    config:
      length: 32
      charset: hex
    targets:
      - provider: local
        kind: file
        config:
          path: .env
          format: dotenv
          merge: true

  - name: api_key
    kind: static
    config:
      default: ${API_KEY}
    targets:
      - provider: local
        kind: file
        config:
          path: .env
          format: dotenv
          merge: true

Docker Compose Configuration

Generate secrets for Docker Compose:

secrets:
  - name: postgres_password
    kind: random_password
    config:
      length: 24
    targets:
      - provider: local
        kind: file
        config:
          path: docker/secrets/postgres_password.txt
          format: json

  - name: redis_password
    kind: random_password
    config:
      length: 24
    targets:
      - provider: local
        kind: file
        config:
          path: docker/secrets/redis_password.txt
          format: json

Application Configuration Files

Generate complete app configuration from templates:

templates:
  app_config:
    description: Application configuration
    fields:
      - name: database_url
        description: Database connection URL
        generator: static
        config:
          default: postgresql://localhost:5432/myapp
      - name: database_password
        description: Database password
        generator: random_password
        config:
          length: 32
      - name: redis_url
        description: Redis connection URL
        generator: static
        config:
          default: redis://localhost:6379

secrets:
  - name: app_config
    kind: templates.app_config
    targets:
      - provider: local
        kind: template
        config:
          template_path: templates/config.yaml.j2
          output_path: config/production.yaml

File Merging Behavior

When merge: true (default), SecretZero will:

1. Read existing file if it exists
2. Parse the content according to the format
3. Update matching keys with new secret values
4. Preserve other keys that aren't in the secret definition
5. Write back the merged content

Example:

Existing .env:

# User-defined settings
APP_NAME=MyApp
DEBUG=true
DATABASE_PASSWORD=old_password

After sync with merge: true:

# User-defined settings
APP_NAME=MyApp
DEBUG=true
DATABASE_PASSWORD=new_generated_password

When merge: false, the file is completely replaced:

DATABASE_PASSWORD=new_generated_password

Security Considerations

⚠️ Important

• Do not commit secrets to version control - Add secret files to .gitignore
• Restrict file permissions - Use chmod 600 for sensitive files
• Be careful with templates - Template outputs may contain sensitive data
• Local files are unencrypted - For production, use external providers

Recommended .gitignore

# SecretZero generated files
.env
.env.local
*.secret.json
*.secret.yaml
config/secrets/
secrets/

# Lockfile may contain hashed values (optional)
.gitsecrets.lock

File Permissions

SecretZero attempts to set restrictive permissions on secret files:

# Automatically set by SecretZero
-rw------- 1 user user  256 Jan 1 12:00 .env
-rw------- 1 user user  512 Jan 1 12:00 secrets.json

Best Practices

✅ Do

• Use local provider for development and testing
• Combine with cloud providers for multi-stage deployments
• Store templates in version control, not rendered outputs
• Use .env files for environment variables
• Set merge: true to preserve manual configurations

❌ Don't

• Use local provider for production deployments (prefer cloud providers)
• Commit generated secret files to version control
• Store production secrets in local files
• Use absolute paths (prefer relative paths for portability)

Limitations

• No encryption at rest - Files are stored in plain text
• No access control - Relies on filesystem permissions
• No audit logging - No record of who accessed secrets
• No versioning - No built-in secret rotation history
• No high availability - Files are local to one machine

For production environments, consider using cloud providers like AWS, Azure, or Vault which provide encryption, access control, and audit logging.

Related Documentation

• File Targets - Detailed file target configuration
• Template Targets - Template rendering guide
• Local Development Use Case - Complete local dev example
• Secretfile Configuration - Secretfile reference

Next Steps

• Learn about cloud providers →
• Configure AWS provider →
• Set up Vault provider →
• View local development examples →