Free for now while in alpha pre-release-candidate phase

Configuration

Sirr is configured entirely through environment variables. No config files, no CLI flags for server settings. Set the variables, start the binary.

Server environment variables

These variables control the Sirr server process.

  • Name
    SIRR_MASTER_API_KEY
    Type
    string
    Description

    Bearer token used for API authentication (constant-time comparison against the Authorization: Bearer header). Use openssl rand -hex 32 to generate a strong key. If not set, sirrd auto-generates a random key on each startup and prints it in a security notice.

  • Name
    SIRR_MASTER_ENCRYPTION_KEY
    Type
    string
    Description

    The master encryption key used to derive per-secret encryption keys. Must be set before the server starts. Use openssl rand -hex 32 to generate a strong key. See also: SIRR_MASTER_ENCRYPTION_KEY_FILE for file-based delivery.

  • Name
    SIRR_MASTER_ENCRYPTION_KEY_FILE
    Type
    string
    Description

    Path to a file containing the master encryption key. Takes precedence over SIRR_MASTER_ENCRYPTION_KEY when both are set. Preferred for production deployments — env vars are visible via docker inspect and /proc. Example: /run/secrets/encryption.key.

  • Name
    SIRR_LICENSE_KEY
    Type
    string
    Description

    License key for running more than 100 secrets per instance. Format: sirr_lic_<40-hex-chars>. Validated against sirrlock.com on startup. Without a valid license, the server returns 402 Payment Required when the 101st secret is pushed. Free for up to 100 secrets.

  • Name
    SIRR_PORT
    Type
    integer
    Description

    TCP port the server listens on.

  • Name
    SIRR_HOST
    Type
    string
    Description

    Network interface to bind to. Use 127.0.0.1 to restrict to localhost only.

  • Name
    SIRR_DATA_DIR
    Type
    string
    Description

    Directory for the sirr.db database and sirr.salt file. Defaults to the platform-specific data directory (see Data directories below).

  • Name
    SIRR_LOG_LEVEL
    Type
    string
    Description

    Log verbosity. One of: trace, debug, info, warn, error.

  • Name
    SIRR_WEBHOOK_SECRET
    Type
    string
    Description

    HMAC secret for signing webhook payloads. When set, every webhook delivery includes an X-Sirr-Signature header. See Webhooks.

  • Name
    SIRR_INSTANCE_ID
    Type
    string
    Description

    Unique identifier for this Sirr instance. Used for multi-instance deployments and license validation heartbeats. Auto-generated if not set.

  • Name
    SIRR_HEARTBEAT
    Type
    boolean
    Description

    Whether to send periodic heartbeats to the license validation server. Set to false to disable.

  • Name
    SIRR_AUDIT_RETENTION_DAYS
    Type
    integer
    Description

    Number of days to retain audit log entries. Entries older than this are purged during prune operations. Set to 0 to retain indefinitely.

  • Name
    SIRR_VALIDATION_URL
    Type
    string
    Description

    URL of the license validation endpoint. Override for on-premise SirrLock deployments.

  • Name
    SIRR_VALIDATION_CACHE_SECS
    Type
    integer
    Description

    How long to cache a successful license validation response, in seconds. Reduces calls to the validation endpoint.

  • Name
    ENABLE_PUBLIC_BUCKET
    Type
    boolean
    Description

    Whether to enable the legacy public /secrets routes. Set to false to disable the public bucket entirely and require all secret operations to go through org-scoped endpoints. Useful for multi-tenant deployments where all secrets must belong to an organization.

  • Name
    SIRR_AUTOINIT
    Type
    boolean
    Description

    When true (or when the --init flag is passed to sirrd serve), the server automatically creates a default organization, an admin principal, and two temporary bootstrap keys on first boot. The bootstrap keys are printed to stdout and are intended for initial setup only.

  • Name
    SIRR_CORS_ORIGINS
    Type
    string
    Description

    Comma-separated list of origins allowed in CORS responses. When unset, CORS headers are not sent. Example: https://app.example.com,https://dashboard.example.com.

  • Name
    SIRR_CORS_METHODS
    Type
    string
    Description

    Comma-separated HTTP methods to allow in CORS responses. Only meaningful when SIRR_CORS_ORIGINS is set. Defaults to all methods when unset. Example: GET,HEAD,POST.

  • Name
    SIRR_TRUSTED_PROXIES
    Type
    string
    Description

    Comma-separated CIDR ranges of trusted reverse-proxy IPs. X-Forwarded-For and X-Real-IP headers are only trusted when the socket peer matches this list. Empty string (default) means proxy headers are never trusted. Example: 10.0.0.0/8,172.16.0.0/12.

  • Name
    SIRR_AUDIT_REDACT_KEYS
    Type
    boolean
    Description

    When true (or 1), key names in /audit responses are hashed with SHA-256 instead of returned verbatim. Useful for compliance environments where key names themselves may be sensitive.

  • Name
    SIRR_WEBHOOK_ALLOWED_ORIGINS
    Type
    string
    Description

    Comma-separated URL prefixes allowed as per-secret webhook targets (the webhook_url field on a pushed secret). Empty string (default) disables per-secret webhooks entirely. Example: https://hooks.example.com.

  • Name
    SIRR_RATE_LIMIT_PER_SECOND
    Type
    integer
    Description

    Steady-state per-IP request rate limit in requests per second. Applies globally across all endpoints.

  • Name
    SIRR_RATE_LIMIT_BURST
    Type
    integer
    Description

    Per-IP burst token allowance. Allows short bursts above the steady-state rate before throttling begins.

  • Name
    NO_BANNER
    Type
    boolean
    Description

    Set to 1 or true to suppress the startup ASCII banner. Useful in log aggregation environments where the banner adds noise.

  • Name
    NO_SECURITY_BANNER
    Type
    boolean
    Description

    Set to 1 or true to suppress the security notice printed when SIRR_API_KEY was auto-generated. Has no effect when SIRR_API_KEY is explicitly configured.

SIRR_MASTER_ENCRYPTION_KEY (or SIRR_MASTER_ENCRYPTION_KEY_FILE) is the only required variable. All others have sensible defaults. Never commit your keys to version control.

Client environment variables

The Sirr CLI and official SDKs read these variables to connect to a Sirr server.

  • Name
    SIRR_SERVER
    Type
    string
    Description

    The base URL of the Sirr server to connect to. Defaults to the managed cloud service at https://sirr.sirrlock.com for zero-config operation. Set to http://localhost:39999 for local self-hosted instances.

  • Name
    SIRR_TOKEN
    Type
    string
    Description

    The bearer token for authenticating API requests. For Cloud users, this is your principal key from sirrlock.com. For self-hosted, this is the value of SIRR_MASTER_API_KEY on the server.

  • Name
    SIRR_ORG
    Type
    string
    Description

    Default organization ID for multi-tenant mode. When set, CLI commands (push, get, list, etc.) and the MCP integration automatically target this org's scope instead of the public bucket. Equivalent to passing --org on every command.

You can set these in your shell profile or pass them inline:

Client configuration

export SIRR_SERVER="https://sirr.internal.example.com"
export SIRR_TOKEN="your-master-key"
export SIRR_ORG="your-org-id"

# Now all CLI commands authenticate automatically
sirr set API_KEY="sk-..." --org $SIRR_ORG --ttl 1h
sirr get API_KEY --org $SIRR_ORG

Data directories

Sirr stores two files in its data directory: sirr.db (the encrypted database) and sirr.salt (the 32-byte salt for key derivation). The default location depends on your platform:

PlatformDefault path
Linux~/.local/share/sirr/
macOS~/Library/Application Support/sirr/
Windows%APPDATA%\sirr\

Override the default by setting SIRR_DATA_DIR:

Custom data directory

export SIRR_DATA_DIR=/opt/sirr/data
sirrd serve

Both sirr.db and sirr.salt must be preserved together. Losing sirr.salt makes existing secrets permanently unrecoverable, even with the correct master key. Back up both files.

Docker configuration

When running Sirr in Docker, mount a volume for the data directory to persist secrets across container restarts. Set SIRR_DATA_DIR=/data to point at your mounted volume.

Docker with persistent storage

docker run -d \
  --name sirrd \
  -p 39999:39999 \
  -v ./sirrd-data:/data \
  -e SIRR_MASTER_ENCRYPTION_KEY="$(openssl rand -hex 32)" \
  -e SIRR_DATA_DIR=/data \
  ghcr.io/sirrlock/sirrd

Docker Compose

docker-compose.yml

services:
  sirr:
    image: ghcr.io/sirrlock/sirrd
    ports:
      - "39999:39999"
    volumes:
      - sirr-data:/data
    environment:
      SIRR_MASTER_ENCRYPTION_KEY: "${SIRR_MASTER_ENCRYPTION_KEY}"
      SIRR_DATA_DIR: /data
      SIRR_LOG_LEVEL: warn

volumes:
  sirr-data:

Production recommendations

  • Always mount a persistent volume for /data. Without it, secrets are lost when the container restarts.
  • Set SIRR_MASTER_ENCRYPTION_KEY and SIRR_MASTER_API_KEY via Docker secrets or your orchestrator's secret management, not in plain text in a compose file.
  • Use SIRR_HOST=0.0.0.0 (the default) inside the container and restrict access at the network level with a reverse proxy.
  • Set SIRR_LOG_LEVEL=warn in production to reduce log noise.

Was this page helpful?