Backend configuration
About this page
This documents a stack generated from soliplex-template. A generated
project ships its own copy of this page without this note.
The backend's behavior is driven by the files under backend/environment/,
bind-mounted into the container at /environment. Because the backend runs
with --reload=config, edits here take effect without a rebuild.
Layout
installation.yaml— the top-level install config: agents, secrets, env vars, room list, skills, DB URIs, paths. Start here.rooms/<name>/room_config.yaml— per-room agent prompts, tools, and skills.skills/<name>/— filesystem skills discovered viafilesystem_skills_paths.logging.yaml,haiku.rag.yaml— logging and RAG configuration.
installation.yaml is heavily commented with pointers to the
Soliplex config docs. Those
comments describe defaults — so a section being empty or absent is not the
same as being unconfigured.
Sign-in configuration
Authentication lives off installation.yaml, in its own files:
oidc/config.yaml— theauth_systemsentries. With none, the backend runs without authentication; the first turns it on. Written by the skill'sscripts/oidc_providers.pyandscripts/install_authelia.py(see Sign-in: choosing and running an identity provider); the backend reloads it by itself.oidc/cacert.pem— the backend's extra trust list for issuer certificates it would not otherwise trust (the in-stack Authelia's self-signed certificate); scripts append to it.nginx/conf.d/— nginx fragments, read at start only: one names the provider the/ingester/gate signs in with, and an Authelia-installed stack gains a route for/authelia/.authelia/configuration.yml(in Authelia stacks) — the provider-side configuration: server, storage, notifier, and the registeredsoliplexclient.
Two sources of truth to remember
room_pathsininstallation.yamllists the directories rooms load from. It points at./rooms, so everyrooms/<name>/room_config.yamlis loaded; to leave a room out, remove its directory or replace./roomswith an explicit list. It also lists/app/src/rooms-provisioned(src/rooms-provisioned/on the host): rooms created on request by the provisioner, a git clone of its own that the provisioner alone writes.- A filesystem skill must be both present under a
filesystem_skills_pathsdirectory and declared inskill_configsto be enabled.
Sandbox (code execution for agents)
backend/sandbox/environments/<name>/pyproject.toml— each subdirectory is auvproject. The backend Dockerfile runsuv sync --frozenon each at build time, so adding or changing one requiresdocker compose build backend.backend/sandbox/workdirs/— per-run working directories created by agents at runtime (gitignored).
Dependencies needed by agent-executed sandbox code belong in the relevant sandbox environment, not in the backend image's top-level dependency list (see Backend image & dependencies).
Running sandbox code is opt-in, chosen when the stack is generated
(enable_sandbox). The backend image includes bwrap (bubblewrap), but
inside a container bwrap needs user namespaces and a fresh /proc.
Docker's default seccomp profile, AppArmor profile and /proc masking each
block one of those, so all three have to be lifted. A stack generated with
enable_sandbox: true carries this security_opt block on the backend
service in docker-compose.yml (and the matching line on soliplex-dev);
one generated without it carries the same lines commented out. To opt in
later, uncomment both and recreate the containers:
security_opt: &sandbox_security_opt
- seccomp=unconfined
- apparmor=unconfined
- systempaths=unconfined
That relaxes the backend container's own hardening, in exchange for bwrap
isolating each execution inside it. Without it, a room that configures the
bubble-sandbox skill fails when used, with "Sandbox unavailable": soliplex
checks that bwrap can run before it hands the room the skill. The skill's
add_room.py checks the same security_opt block, and refuses to add such
a room (the sandbox template) to a stack without it.