Installation Configuration
Installation ID
A required field, to allow quick disambiguation between alternative configurations.
Installation Metaconfiguration
The meta section allows you to register custom "kinds" of entities (tool
configurations, MCP client toolset configurations, etc.), such that you
can use them within your own configurations (e.g., to register a configuration
class for use with a custom tool in a given room).
See this page for documentation on the meta-configuration schema.
Secrets
Secrets are values used to authenticate access to different resources or APIs.
The may be kept in an external store, such as:
- ASW secret store
- GitHub secrets
- Docker Compose secrets files
- The user keyring
See this page for documentation on configuring installation secrets.
Environment
The environment section configures non-secret values used by various
portions of the Soliplex application. Application code should use the
Installation.get_environment API to fetch configured values, rather than
using os.environ.
See this page for documentation on configuring the installation environment.
Note: this configuration is distinct from adding variables to the operating system environment: see this page for that topic.
Installation Secret / Environment Interpolation
Certain configuration elements can interpolate values resolved by the installation configuration. Two marker styles are used:
"secret:SOME_SECRET_NAME"resolves an installation secret."env:SOME_INSTALLATION_ENVIRONMENT_NAME"resolves an installation environment value.
Which markers a given field honors depends on the field, as enumerated below. So does how much of the value is examined: some fields substitute markers found anywhere in the value, while others require the whole value to be a single marker.
Which markers a field honors is declared on the field itself, so the
runtime and soliplex-cli audit read the same statement. A configuration
class defined outside Soliplex can declare the same contracts, and is then
audited alongside these: see
Environment / Secret Interpolation.
Several of the fields below belong to an agent configuration, which appears in three places:
- the
agent_configs:stanza of the main installation configuration - the
agent:stanza of a room or a completion configuration - the
judge_agent:stanza of a quiz configuration (see Quizzes)
Fields which interpolate only secrets
The entire value must be a single secret: reference, resolved from the
installation secrets. A marker embedded in a longer string is not
substituted:
provider_key, in any agent configuration. A value which is not asecret:reference is rejected.token, in thelogfire:configuration (see Logfire). A value which is not asecret:reference is rejected.client_secret, in an OIDC provider configuration (see OIDC providers). Unlike the two above, any other value -- including anenv:marker, and including asecret:name which cannot be resolved -- is used literally rather than rejected.
Fields which interpolate only environment variables
Two groups, differing in how much of the value is examined.
The value may embed one or more env: markers, resolved from the
installation environment:
model_name, in any agent configuration.provider_base_url, in any agent configuration.
The entire value must be a single env: marker; any other value is used
literally.
In the main installation configuration:
thread_persistence_migration_policyauthorization_migration_policy
Both are further constrained by their own value domain: a literal has to name one of the migration policies, and anything else is an error rather than a value used literally. See Migrations.
In the logfire: configuration (see Logfire):
service_name,service_version, andenvironmentconfig_dir,data_dir, andmin_levelbase_url
All but base_url default to an env: marker naming the corresponding
LOGFIRE_* entry, so they are interpolated even when the logfire: stanza
does not mention them. For all seven, a name which the installation does not
declare resolves to no value, rather than being reported as an error.
Fields which interpolate both secrets and environment variables
The value may embed one or more secret: and/or env: markers; the two
marker styles may be mixed within a single value.
In the main installation configuration:
thread_persistence_sync_dburithread_persistence_async_dburithread_persistence_migration_dburiauthorization_sync_dburiauthorization_async_dburiauthorization_migration_dburi
Through Soliplex v0.81 the four runtime URLs named the flavor first, as
thread_persistence_dburi_sync and so on. Those names were deprecated
from v0.82 through v0.90, and have since been removed. The two migration
URLs (see Migrations) never had that spelling.
In the mcp_client_toolsets: stanza of a room or completion configuration,
for each configured MCP client toolset:
kind: "stdio":command, each entry inargs, and each value inenvkind: "http"orkind: "sse":url, each value inheaders, and each value inquery_params
haiku.rag Configuration File
The haiku_rag_config_file entry points to a YAML file containing
configuration values for the haiku.rag client
If not configured explicitly, the installation configuration expects to
find this file in the same directory, with the default name haiku.rag.yaml.
Please see the haiku.rag configuration
docs for details
on how to configure the haiku.rag client used by Soliplex.
Agent Configurations
An installation can declare agent configurations (which are normally bound
to rooms / completions) at the top-level, such that they can be
looked up by ID from Python code using the_installation.get_agent_by_id.
agent_configs:
- id: "ollama_gpt_oss"
model_name: "gpt-oss:20b"
system_prompt: |
You are an expert AI assistant specializing in information retrieval.
...
Please see this page for details on configuring agents.
In addition to the values described there, note that the id element is
required here.
Databases
Two stanzas configure the installation's databases, each as a pair of
SQLAlchemy URLs (sync_dburi and async_dburi):
thread_persistence_db: AG-UI threads, runs, and eventsauthorization_db: administrative users, and room authorization policies with their ACL entries
If a stanza is omitted, that database is an in-memory SQLite database, equivalent to:
A password in a DBURI can come from a secret, e.g.
postgresql+psycopg://user:secret:MY_DBURI_SECRET@dbhost/dbname.
See SQLAlchemy DBURIs for the full reference: supported dialects, on-disk SQLite and PostgreSQL examples, installing the PostgreSQL driver, and migrations.
OIDC Auth Provider Paths
The oidc_paths element specifies one or more filesystem paths to be
searched for OIDC provider configs.
Please see this page for details on how to configure these providers.
Non-absolute paths will be evaluated relative to the installation directory.
By default, Soliplex loads provider configurations found under the path './oidc', just as though we had configured:
To disable authentication, list a single, "null" path, e.g.:
Or else run 'soliplex-cli serve --no-auth-mode'
Filesystem Skill Paths
The filesystem_skills_paths stanza specifies one or more filesystem paths to
search for AI Skill configurations.
Please see this page for documentation on AI skills.
Each path can be either:
-
a directory containing its own
SKILL.mdfile: this directory will be mapped as a single skill. -
a directory whose immediate subdirectories will be treated as skills if they contain a
SKILL.mdfile.
Non-absolute paths will be evaluated relative to the installation directory.
The order of entries in the filesystem_skills_paths list controls which
skill configuration is used for any conflict on skill name: filesystem
skills found earlier in the list "win" over later ones with the same name.
By default, Soliplex loads skill configurations found under the path './skills', just as though we had configured:
To disable filesystem skill discovery, list a single, "null" path, e.g.:
Selecting Skill Configurations
All discovered filesystem skills are enabled by default. If skill_configs
contains any entries, it acts as an allow-list. For example:
With this configuration, discovered skills other than bare-bones cannot
be referenced by other parts of the configuration, such as rooms.
Sandbox Configuration
The sandbox_config stanza configures the bubblewrap sandbox that backs the
bubble-sandbox skill (shell / Python execution). Non-absolute paths are
evaluated relative to the installation directory.
The sandbox needs a host where bwrap (bubblewrap) can run: Linux, with
bwrap on the PATH, and with unprivileged user namespaces allowed.
Ubuntu 24.04's AppArmor policy
(kernel.apparmor_restrict_unprivileged_userns) and a container's default
seccomp profile can each block those namespaces; in a Docker deployment,
run the backend with a seccomp profile that permits them.
Soliplex checks once per process by running bwrap with the sandbox's own
flags. Where that check fails, a configuration naming the skill still
loads and passes soliplex-cli audit, but a room using it fails to build
its agent with a BwrapSandboxUnavailable error giving the reason, and
the sandbox_workdirs endpoints are not mounted.
sandbox_config:
environments_path: ../sandbox/environments
workdirs_path: ../sandbox/workdirs
transcripts_path: ../sandbox/transcripts
-
environments_path(required) -- directory whose subdirectories are selectable sandbox environments. To qualify, a subdirectory must contain both apyproject.tomland a.venvinitialized from it. -
workdirs_path(optional) -- root for each thread's sandbox workspace, named<room_id>/<thread_id>. This directory is mounted read-write into the sandbox as the execution working directory, and persists across the thread's turns, so a later turn can build on what an earlier one wrote. Soliplex never deletes it. If unset, each sandbox command gets a temporary directory of its own, discarded when that command ends, so commands in one run share nothing and the workdirs endpoint has nothing to serve. -
transcripts_path(optional) -- root under which eachrun/run_pythonexecution's command line or Python script is saved (under<room_id>/<thread_id>/<run_id>, with a UUID-based filename), so that a reviewer can recover exactly what was executed. Unlikeworkdirs_path, this directory is never mounted into the sandbox, so executed code can neither read nor tamper with the saved transcripts. The saved files hold the raw (possibly sensitive) command / script content, so treat them as audit artifacts: protect them at least as strongly as uploaded files, and retain or prune them per your audit policy -- separately fromworkdirs_path. If unset, transcripts are not saved.
Uploaded files in the sandbox
When the top-level rooms_upload_path / threads_upload_path options are
configured (these are installation-level options, not part of sandbox_config),
the skill mounts the corresponding uploaded files into the sandbox
read-only, as the room and thread volumes. The agent discovers their
names by listing those directories with the run tool, which records a
transcript. By design these are
non-protected, availability-intended material: room uploads are
admin-provided reference / context meant to be available to every room member
(by download or via the sandbox), and thread uploads are provided by the
thread's own user. Reading one with a sandbox command is therefore not
separately audited -- the command's own record covers it. The read_image
tool is the exception: it returns bytes to the model with no execution
behind them, so each read is recorded on its own.
Nothing technically prevents an administrator from uploading information that
should be protected. An installation that wants to remove that risk
entirely can disable room uploads by leaving rooms_upload_path unset: the
room-upload endpoint then returns 405 for POST, and no room volume
is mounted into the sandbox.
AG-UI SSE Delivery
The optional sse_delivery stanza declares named delivery profiles: how
the AG-UI run endpoint groups the model's streamed deltas (text, thinking,
reasoning and tool-call arguments) into SSE events. Each profile shares the
shape of the strategies below, plus a short description for delivery
to clients (the name is the mapping key): clients may name one profile in
the run request's forwarded_props (see
Room Configuration); a room without its own
choice uses the stanza's default profile. Unknown profile names, at either level, fall
back to the next level's default; with no stanza at all, runs use
strategy: "message".
-
strategy: "message"merges adjacent deltas of one message, or of one tool call's arguments, and sends them when any other event arrives -- normally the message's end. This keeps bytes, events and stored rows low, but text generally reaches the client only when the message ends. -
strategy: "bounded"merges adjacent deltas of one message or tool call in the same way, and also sends the merged event as soon as it holdsmax_deltasdeltas, ormax_bytesbytes of UTF-8 text, or has been held formax_msmilliseconds, whichever comes first. All three are required, as positive integers. A single delta is never split, so one large delta can exceedmax_bytes. (One difference: after a different message's delta,messagesends the next delta on its own, whileboundedstarts merging again.)
sse_delivery:
default: "fine-grained"
configs:
"whole-message":
strategy: "message"
description: "Text arrives with each assistant message"
"fine-grained":
strategy: "bounded"
description: "Text streams a few deltas at a time"
max_deltas: 16
max_bytes: 1024
max_ms: 100
With a model producing about 25 deltas a second, these bounds send about
eight updates a second, each holding about three deltas: on loopback, an
80-delta answer took 27 events and about 3.8 times the bytes of
message.
bounded sends text sooner, at the cost of more SSE events, more bytes
(each event carries its own envelope), and one stored row, saved in its
own transaction, per event. max_ms is a target for how long merged text
is held, not a guarantee: it is checked when the server's event loop gets
to it, and time spent before the text is held, saving each event to the
database, and the network all add to the delay a client sees. No default
bounds are provided: suitable values depend on the pace at which the
room's model produces deltas.
Unknown keys, unknown strategies, bounds given with message, and
missing or non-positive bounds with bounded are rejected when the
configuration loads. A room naming a profile the installation does not
declare is also rejected at load time.
Room Configuration Paths
The room_paths element specify one or more filesystem paths to
search for room configs.
Please see this page for details on how to configure these providers.
Each path can be either:
-
a directory containing its own
room_config.yamlfile: this directory will be mapped as a single room. -
a directory whose immediate subdirectories will be treated as rooms IFF they contain a
room_config.yamlfile.
Non-absolute paths are evaluated relative to the installation directory.
The order of room_paths in this list controls which room configuration
is used for any conflict on room ID: rooms found earlier in the list
"win" over later ones with the same ID.
soliplex-cli audit installation reports such shadowed room configurations,
but does not treat them as findings: the search path mechanism is the
documented way to override one or more of a shared set of configured rooms.
By default, Soliplex loads room configurations found under the path './rooms', just as though we had configured:
To disable all rooms, list a single, "null" path, e.g.:
Reloading room configurations
Soliplex loads room configurations when the server starts. Python code
running inside the server, e.g. an app router which writes a new room
directory under one of the room_paths, can reload them without a
restart:
The reload:
-
re-reads only the room configurations:
installation.yaml, the environment and secrets, completions, OIDC, and the rest of the installation stay as they were at startup. -
is all or nothing: the new set of rooms replaces the old one only once every room configuration has loaded. If one fails to load, the error propagates to the caller, and the rooms already loaded stay in place.
-
reads and parses the files in a worker thread, off the event loop.
-
takes effect on the next request: room lookups read the current set each time.
-
affects only the server process which runs it. Under
soliplex-cli serve --workers N, each worker holds its own copy of the rooms.
It returns the IDs of the rooms it added, removed, and changed
(a room is "changed" when its reloaded configuration differs from the one
it replaced), each as a sorted tuple.
MCP endpoints are not reloaded: Soliplex builds the /mcp/<room_id>
endpoints once, at startup, from the rooms configured then. So a room
which a reload adds with allow_mcp: true has no MCP endpoint until the
server restarts. Likewise, a room which a reload removes, or whose
allow_mcp it turns off, keeps its MCP endpoint until then, and an MCP
endpoint keeps serving the tools its room had at startup.
Completion Configuration Paths
The completion_paths stanza specifies one or more filesystem paths to
search for completion configs.
Please see this page for details on how to configure these providers.
Each path can be either:
-
a directory containing its own
completion_config.yamlfile: this directory will be mapped as a single completion. -
a directory whose immediate subdirectories will be treated as completions IFF they contain a
completion_config.yamlfile.
Non-absolute paths will be evaluated relative to the installation directory.
The order of entries in the completion_paths list controls which completion
configuration is used for any conflict on completion ID: completions
found earlier in the list "win" over later ones with the same ID.
By default, Soliplex loads completion configurations found under the path './completions', just as though we had configured:
To disable all completions, list a single, "null" path, e.g.:
Logfire Configuration
See the Soliplex logfire configuration page.
ASGI Middleware Stack
The optional middleware_stack section declares the ASGI middleware wrapping
the application (outermost first). Omit it to use the built-in default stack
(session + CORS).
See the Soliplex middleware configuration page.