Secrets and config

Via has two kinds of runtime settings. Plain config is for values that can appear in command output, deploy logs, or support bundles. Secrets are for values that should never travel through argv, shell history, generated manifests, or diagnostic JSON.

The config server delivers both kinds of values to running apps, but secret access has a narrower path: the app must declare the secret name, the runner must mint a workload token for that instance, and the config server must authorize the request before it reads the stored value.

Tracked components

After install, via status prints one line per component with the unit's state and bound endpoint.

Config server endpoint

Runtime containers use the config server to fetch declared configuration and secrets with workload identity. By default it binds on 0.0.0.0:8181 so runtime containers can reach it through the Docker host-gateway alias. The bind address comes from the [config_server] section of /etc/via/server.toml:

[config_server]
host = "0.0.0.0"
port = 8181

Workload identity JWT verification is the security boundary. Firewall port 8181 externally on production hosts; it is for host-to-container traffic, not a public API.

The secret endpoint maps response codes to typed runtime-client errors:

Successful 200 responses set Cache-Control: no-store so intermediaries do not retain the value past the request.

Workload identity flow

When the runner promotes an ARTIFACT_READY deploy to RUNNING, it issues a per-instance signed JWT and bind-mounts it into the container. No secret value or long-lived credential is shared with the container.

Token bounds:

Verification at the config server

Every /config/<env>/<name> request runs through a single authorization choke point:

Every outcome (allowed, denied, missing, error) writes one audit_events row with action = config_secret_access, target_id = <secret name>, and flat JSON metadata carrying token id, app id, deploy id, instance id, environment, secret name, and (for denials) the typed code. Plaintext values are never serialized.

Declaring secrets in the app manifest

A runtime container is only allowed to fetch a secret whose name appears in [capabilities] secrets = [...]:

[capabilities]
secrets = ["DATABASE_URL", "STRIPE_KEY"]

Names not declared produce denied undeclared_secret regardless of what is stored. This gate is enforced at issuance (the secrets claim) and at the config server (membership check before the value lookup).

App env and config CLI

Use the HTTP target flow for app runtime configuration:

vary target add prod https://vary.example.com
vary login --target prod --name alice --token-stdin

vary app env list api --target prod
vary app env set api DATABASE_URL --target prod --secret
vary app env rotate api DATABASE_URL --target prod
vary app env history api DATABASE_URL --target prod
vary app env set api LOG_LEVEL --target prod --value info
vary app config patch api --target prod --replicas 2 --memory-mb 512
vary app config diff api --target prod
vary app config redeploy api --target prod

For one secret, prefer the masked prompt shown above. It keeps the value out of shell history, ps, terminal scrollback, and copied runbooks. In automation, redirect stdin from an existing secret file or use your CI secret store's masked-stdin facility:

vary app env set api DATABASE_URL --target prod --secret < /run/secrets/api-database-url

For several values, render a template, fill it in outside your shell history, apply it once, then delete the local copy:

vary app config template api --target prod --workdir . > api.prod.env
chmod 600 api.prod.env
$EDITOR api.prod.env
vary app config apply api --target prod --file api.prod.env
rm api.prod.env

The template uses KEY=value for plain config and secret:KEY=value for secrets. Treat a filled template like a password file. Do not commit it, paste it into tickets, or keep it in a shared shell transcript.

Avoid any command that places the secret value directly in the command text. Even if the CLI rejects argv secrets, the shell may have already recorded the line.

Secret env writes read from stdin or a masked TTY prompt. Secret values are not accepted in argv. Default output renders them as <redacted>; --json responses are also redacted. Rotate and history responses show generation, status, timestamps, source, and provider metadata only.

Secret provider metadata is provider-neutral:

Rotation and runtime cache

vary app env rotate <app> <name> --target <target> creates a new generation for a secret-backed env value. Previous generations remain in the control plane for audit, but the config server returns the current generation by default.

Host operators can also use via app secret rotate <name> --app <app> for the local app-secret store. That command runs on the Via host, not through a workstation target.

Each running app's runtime config client memoizes a successful config.secret(...) response for 30 seconds. The cache is per-process, keyed by the full request URL (base + environment + name), and is bypassed for any non-200 response.

After a rotation, every running app sees the new value within the cache TTL. For an immediate rollout, restart the affected runtime containers; a fresh process starts with an empty cache. Errors are never cached, so a transient denial or upstream failure does not pin a stale outcome.

Runtime refresh requests include the app, release, deploy, config profile version, key scope, key name, and generation. The server accepts the currently running profile for authorization, then materializes the newest active app profile so env rotation and add-on credential rotation can reach running workloads without changing the release that was originally deployed.

Calling config from Vary

import config

def main() {
    let url = config.secret("DATABASE_URL")
    let debug = config.bool("DEBUG", False)
    print(url)
    print(debug)
}

config.secret(name) returns the declared secret as a string or raises one of five typed errors (ConfigMissingError, ConfigUndeclaredError, ConfigPermissionDeniedError, ConfigServerUnavailableError, ConfigBadTypeError). Catch them individually with except ConfigMissingError as e or fall back to the family with except ConfigError as e.

config.bool(name, default) returns a typed public config value with a default. Both call the same wire shape and use the same cache policy.

Avoid these patterns

Continue to Operations for status, doctor, history, and key rotation.