DOCSEARCHbyAlgolia
Submit Docs

Quonfig Documentation

website·Indexed 31 days ago

https://docs.quonfig.com

A configuration and feature flag management platform. Quonfig provides SDKs for .NET, Go, Ruby, Python, Node.js, React, and React Native, as well as OpenFeature providers. Key features include dynamic configuration, targeting rules, segmentation, A/B testing, and a REST API for CI/CD automation. The platform includes a CLI for workspace management and a Context Playground and Debugger for testing targeting logic.

Tokens
77.4K
Snippets
365
Records
503
Agent score
49%

What's inside Quonfig

  1. Overview of Quonfig Zero-Knowledge Secret Management

    Quonfig provides zero-knowledge secret management, meaning Quonfig never sees unencrypted secret values. The system relies on a secret key (a series of random bytes) that the user owns and distributes.

    Workflow:

    1. Create a secret key using the CLI.
    2. Distribute this key to developer machines (for encryption) and deployed environments (for decryption) via environment variables.
    3. Encrypt strings using the Quonfig CLI.
    4. Quonfig stores and distributes the encrypted blobs.
    5. Applications decrypt the values using the SDK and the secret key.

  2. Understand Quonfig authorization basics

    Authorization in Quonfig is determined by the intersection of two properties: the protection status of an environment and the access level of a config. Roles are used to grant specific permissions within this matrix.

    • Environment Protection: Every environment is either 'protected' or not. Marking an environment (e.g., production) as protected restricts who can edit certain configs within that environment.
    • Config Access Levels: Every flag and config has an access field (defaults to standard).

  3. Use Quonfig in local-only mode without an account

    Quonfig can be used entirely offline without an account, API key, or network connection. In this mode, the system operates as a folder of JSON files in a git repository. The SDKs read this directory (datadir) directly from the filesystem to evaluate flags and configs in memory. This approach is specifically for server-side SDKs; browser or React Native SDKs require qfg serve to expose the directory over HTTP.

  4. Understand Quonfig backend SDK resiliency and failover

    Quonfig backend SDKs are designed to be robust against network outages using three primary mechanisms:

    1. Local Caching: SDKs store all configuration locally. If a connection is lost, services continue to function using the last known configuration, though they will not receive updates until the connection is restored.
    2. Automatic Failover: SDKs use a primary delivery network (on fly.io) and a secondary network on separate infrastructure. If the primary is unreachable or errors, the SDK automatically fails over to the secondary.
    3. Hedging: To prevent slow primary responses from stalling reads, the SDK asks the primary first. If no response is received within a hedge delay (default 2s), it requests the configuration from the secondary in parallel and uses the first valid response.

    Booting New Clients: New instances fetch configuration during boot. If the primary is down or slow, the SDK attempts to fetch from the secondary. Each attempt has a short timeout (default 3s) to ensure the secondary is reached quickly.

  5. Understand Quonfig Backend SDK Architecture

    Quonfig Backend SDKs are designed for high performance and resilience by ensuring configuration evaluation happens in-process. Key architectural features include:

    • Local Storage: Config and feature flags are stored in a local, thread-safe hashmap within the application process, allowing for lightning-fast lookups without remote API calls.
    • Initialization: The Quonfig Client singleton fetches the latest configuration from multiple sources upon startup before becoming available to the application.
    • Real-time Updates: The SDK maintains a long-lived Server-Sent Events (SSE) streaming connection to pull updates instantly (expected latency < 100ms).
    • Resiliency: The SDK implements polling as a fallback measure in case the streaming connection fails.
    • Automatic Routing: The SDK uses primary.quonfig.com for short-lived HTTP fetches and automatically derives the streaming host by prepending stream. to the configured API URL (e.g., stream.primary.quonfig.com).

  6. Use qfg run to inject Quonfig variables into a process

    qfg run resolves Quonfig configurations into environment variables and executes a child process. This is specifically intended for tools that read configuration from process.env before user code runs (e.g., build pipelines, migration tools, or boot-time secrets) and cannot call the SDK directly.
    # Example: Running a migration that requires DATABASE_URL
qfg run --env DATABASE_URL=db.url -- drizzle-kit migrate

  7. Understand Quonfig API versioning

    The Quonfig API is versioned in the URL path (e.g., /v1).

    • v1 Stability: Changes within v1 are additive only (new endpoints, optional fields, or new values in open string sets). Clients should ignore unrecognized fields.
    • Breaking Changes: Any breaking changes (renaming fields, changing types, or altering semantics) will result in the creation of a /v2 endpoint, while v1 remains operational.

  8. Resolve warnings about dropped override sections or invalid configs

    The migrator may issue warnings for data it cannot translate. These are listed in MIGRATION_REPORT.md.

    Dropped Override Sections: Occurs when a source rule points to an environment that was archived or deleted. If the environment is still needed, restore it in the source system; otherwise, the warning can be ignored.

    Skipped Invalid Configs: Occurs when a config is structurally invalid. Common causes include:

    • Type Mismatch: A variant's value.type does not match the config's valueType (e.g., double vs string).
    • Schema Conversion Failure: The Zod source uses unsupported expressions or exotic refine() predicates.
    • Unsupported Schema Payload: The schemaType is not ZOD (e.g., OPENAPI).

    Resolution: Fix the offending config in the source system (correct the type or convert the schema to Zod) and re-run the migrator.

  9. Understand frontend evaluation and security

    Quonfig frontend SDKs perform evaluation server-side. This ensures that sensitive rule data (such as lists of specific customer IDs used for targeting) is never exposed to the browser. The client receives only the final evaluated result for the given context.

    Example of the evaluated response received by the client:

    {
  "feature.exp12-big-button": "control",
  "feature.exp14-button-class": "very-blue",
  "feature.risky-business": true
}

  10. Understand Quonfig rule evaluation and segmentation

    Quonfig uses rules to target specific users for feature flags. Segments are reusable sets of these rules that can be applied across multiple flags. Rules are evaluated in sequential order; the first rule that matches determines the variant served. When a rule matches, the system can either return a specific variant (e.g., true, false) or a variant based on a percentage rollout. Percentage rollouts are 'sticky' to the provided lookup key, meaning the result remains consistent unless the key or the percentage values change.

  11. Use Quonfig tools within Claude Code

    Once connected, Claude can automatically use 20 available tools (14 read-only, 6 write). You can ask natural language questions about flag rollouts, audit trails, or request changes to flag states. If you belong to multiple workspaces, specify the workspace name in your prompt to avoid a follow-up question from Claude.
    "What's the rollout of checkout-redesign in production?"
"Who turned off the new pricing page, and when?"
"Which flags in this workspace are ready for cleanup?"
"Disable ai-summaries in staging."
"In the payments workspace, what's the rollout of..."

  12. Resolve dropped override sections during migration

    If you receive a warning about dropped override sections, review the MIGRATION_REPORT.md file to see what was lost. If the feature-flag side was the intended live version, delete the incorrect side in the source system and re-run the migration command. If the warning was caused by a benign issue, such as a renamed key where both versions lingered, no action is required.
    qfg migrate