Configuring Installation Secrets
The secrets section of an installation configuration contains a list
of secret names, and optionally their configured sources.
The default configuration knows of four types of sources:
- Environment variables
- File paths
- Subprocess commands
- Randomly-generated strings
A deployment can add a fifth -- fetching secrets from a cloud secret store, for instance -- or replace the built-ins entirely. See Registering Secret Source Configurations and Registering Secret Getter Functions.
Secret Source: Environment Variable
A secret source which uses an environment variable can be configured so:
Secret Source: Filesystem Path
A secret source which uses a file system path can be configured so:
Secret Source: Subprocess Command
A secret source which uses a subprocess command can be configured so:
secrets:
- secret_name: MY_SECRET
sources:
- kind: "subprocess"
command: "/usr/bin/fetch_secret"
args:
- "--secret-name=MY_SECRET"
Secret Source: Randomly-Generated String
A secret source which uses generates a random string at process startup can be configured so:
Layering Secret Sources
Sources are resolved in the order they are listed, with the first one returning a value winning. This example layers an environment variable source with a random string source:
secrets:
- secret_name: MY_SECRET
sources:
- kind: "env_var"
env_var_name: "MY_SECRET_ENV_VAR_NAME"
- kind: "random_chars"
n_chars: 32
A secret resolved from a random_chars source gets a new value whenever
the server restarts, and a different one in each server process.
soliplex-cli audit secrets reports
such a secret as OK (random_chars), followed by a warning.
Secrets without Sources
Secrets which list no sources are treated as though they were configured using an environment variable source with the same name.
This configuration:
is equivalent to:
Secrets as Bare Strings
An even shorter way to spell the previous configuration:
Required Secrets
In addition to secrets configured to manage access to external APIs, the Soliplex server itself depends on two secrets:
SESSION_MIDDLEWARE_TOKEN
This secret is used to encrypt a client's session data (see the Starlette session middleware docs).
Its value must be an ASCII hex digest of a random bytes object with length
32. To generate such a value:
If generated this way, the value can be passed into Soliplex via either
an env_var source, e.g.:
secrets:
...
- name: "SESSION_MIDDLEWARE_TOKEN"
sources:
- kind: "env_var"
env_var_name: "SOLIPLEX_SESSION_MIDDLEWARE_TOKEN"
or a file_path source, e.g.:
secrets:
...
- name: "SESSION_MIDDLEWARE_TOKEN"
sources:
- kind: "file_path"
file_path: "/run/secret/session_middleware_token"
The installation configurations in the example/ directory provider a
fallback random_chars source:
- secret_name: "SESSION_MIDDLEWARE_TOKEN"
sources:
- kind: "env_var"
env_var_name: "SOLIPLEX_SESSION_MIDDLEWARE_TOKEN"
- kind: "random_chars"
but this configuration should not be used where sessions must survive a server restart (the session token will be regenerated), nor when running behind a load balancer.
URL_SAFE_TOKEN_SECRET
This secret is used to sign bearer tokens:
- the tokens which allow MCP clients to access a room's MCP-enabled tools;
- service tokens, minted by
soliplex-cli service-token mint, which allow a client (e.g.,curl, or an operator's script) to call the Soliplex API without an OIDC login.
Changing the secret invalidates every token signed with the old value.
This value must be an ASCII hex digest of a random bytes object with length
32. To generate such a value:
If generated this way, the value can be passed into Soliplex via either
an env_var source, e.g.:
secrets:
...
- name: "URL_SAFE_TOKEN_SECRET"
sources:
- kind: "env_var"
env_var_name: "SOLIPLEX_URL_SAFE_TOKEN_SECRET"
or a file_path source, e.g.:
secrets:
...
- name: "URL_SAFE_TOKEN_SECRET"
sources:
- kind: "file_path"
file_path: "/run/secret/url_safe_token"
The installation configurations in the example/ directory provider a
fallback random_chars source:
- secret_name: "URL_SAFE_TOKEN_SECRET"
sources:
- kind: "env_var"
env_var_name: "SOLIPLEX_URL_SAFE_TOKEN_SECRET"
- kind: "random_chars"
but this configuration should not be used where MCP tokens must survive a server restart (the secret will be regenerated), nor when running behind a load balancer.
Nor can service tokens be used with it: soliplex-cli service-token mint
resolves the secret in its own process, so when the fallback applies, the
CLI would sign the token with one random value and the server would check
it against another. The CLI therefore refuses to mint a token unless one
of the sources ahead of the random_chars source resolves the secret.
Configure an env_var or file_path source, and make sure it resolves to
the same value for the CLI and for the server.
Checking Configured Secrets
The soliplex-cli application has a sub-command, audit secrets.
It loads the configuration, attempts to resolve all the secrets, and
reports those not found. E.g.: