Skip to content

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 via filesystem_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 — the auth_systems entries. With none, the backend runs without authentication; the first turns it on. Written by the skill's scripts/oidc_providers.py and scripts/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 registered soliplex client.

Two sources of truth to remember

  • room_paths in installation.yaml lists the directories rooms load from. It points at ./rooms, so every rooms/<name>/room_config.yaml is loaded; to leave a room out, remove its directory or replace ./rooms with 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_paths directory and declared in skill_configs to be enabled.

Sandbox (code execution for agents)

  • backend/sandbox/environments/<name>/pyproject.toml — each subdirectory is a uv project. The backend Dockerfile runs uv sync --frozen on each at build time, so adding or changing one requires docker 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.