Skip to content

Installation Configuration

Installation ID

A required field, to allow quick disambiguation between alternative configurations.

id: "soliplex-example"

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).

meta:

See this page for documentation on the meta-configuration schema.

Secrets

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.

environment:

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 a secret: reference is rejected.
  • token, in the logfire: configuration (see Logfire). A value which is not a secret: reference is rejected.
  • client_secret, in an OIDC provider configuration (see OIDC providers). Unlike the two above, any other value -- including an env: marker, and including a secret: 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_policy
  • authorization_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, and environment
  • config_dir, data_dir, and min_level
  • base_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_dburi
  • thread_persistence_async_dburi
  • thread_persistence_migration_dburi
  • authorization_sync_dburi
  • authorization_async_dburi
  • authorization_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 in args, and each value in env
  • kind: "http" or kind: "sse": url, each value in headers, and each value in query_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 events
  • authorization_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:

thread_persistence_db:
  sync_dburi: "sqlite://"
  async_dburi: "sqlite+aiosqlite://"

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.

oidc_paths:
  - "/path/to/oidc/config/dir"

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:

oidc_paths:
  - "./oidc"

To disable authentication, list a single, "null" path, e.g.:

oidc_paths:
  -

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.md file: this directory will be mapped as a single skill.

  • a directory whose immediate subdirectories will be treated as skills if they contain a SKILL.md file.

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:

filesystem_skills_paths:
  - "./skills"

To disable filesystem skill discovery, list a single, "null" path, e.g.:

filesystem_skills_paths:
  -

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:

skill_configs:
  - skill_name: "bare-bones"
    kind: "filesystem"

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 a pyproject.toml and a .venv initialized 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 each run / run_python execution'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. Unlike workdirs_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 from workdirs_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 holds max_deltas deltas, or max_bytes bytes of UTF-8 text, or has been held for max_ms milliseconds, whichever comes first. All three are required, as positive integers. A single delta is never split, so one large delta can exceed max_bytes. (One difference: after a different message's delta, message sends the next delta on its own, while bounded starts 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.yaml file: 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.yaml file.

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:

room_paths:
  - "./rooms"

To disable all rooms, list a single, "null" path, e.g.:

room_paths:
   -

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:

reloaded = await the_installation.reload_room_configs()

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.yaml file: 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.yaml file.

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:

completion_paths:
  - "./completions"

To disable all completions, list a single, "null" path, e.g.:

completion_paths:
  -

Logfire Configuration

See the Soliplex logfire configuration page.

ASGI Middleware Stack

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.