Setting up the concierge
Adding the concierge to an installation means creating the about-room,
wiring in the soliplex-concierge-room and soliplex-docs skills,
registering the create_gitea_issue, request_room and check_room_request
tools, and declaring the Gitea connection. This page covers:
- installing it with the
soliplex-concierge-installerskill, which does all of this for you on asoliplex-template-generated stack - installing it by hand, on any other installation
- configuring the about-room, however it was installed: what it needs to create rooms on request, bringing an older about-room up to date, and what it answers questions from
Either way you install it, you will need a Gitea repository to file requests against, and an
access token whose account has Write access to it — not just Read. Gitea
lets a Read-only account open issues but silently drops their labels, so
requests would be filed untagged and slip past triage (issue #59).
A fine-grained token additionally needs the write:issue and read:repository
scopes.
The installer skill (recommended)
Run the soliplex-concierge-installer skill from an external coding agent (e.g.
Claude Code). It runs its bundled scripts/install_concierge.py with
uv run — a thin shim that provisions soliplex-concierge from its
PEP 723 header (so no install step is
needed) and delegates to the soliplex_concierge.installer module — applying
every change idempotently.
Preview first with --dry-run, then apply:
# dry run — report changes without writing
uv run scripts/install_concierge.py --stack-dir /path/to/stack \
--owner <gitea-owner> --repo <gitea-repo> --dry-run
# apply, pinning the dependency version
uv run scripts/install_concierge.py --stack-dir /path/to/stack \
--owner <gitea-owner> --repo <gitea-repo> --version <X.Y>
What it changes
It applies these idempotent edits to the stack:
- Adds
soliplex-conciergetobackend/pyproject.toml, and to the list of packages the backend image installs:backend/requirements.txtin a stack built on a soliplex release image, or thebackend/Dockerfileuv addblock in an older stack (whose Dockerfile ignores thepyproject.tomldeps). - Merges its entries into
backend/environment/installation.yaml:meta.tool_configs(the three tool-config classes),environment,secrets, androom_paths. On a stack with an explicit filesystemskill_configsallow-list, it also adds the two skills there, but only with--confirm-skill-whitelist; otherwise it stops with an error. - Copies the about-room into
backend/environment/rooms/<room-id>/(about_<compose-project-name>by default; override with--room-id). - Downloads and installs the
soliplex-concierge-roomandsoliplex-docsfilesystem skills intobackend/environment/skills/. - Appends the
GITEA_HOST/GITEA_ACCESS_TOKENplaceholders to.env— unless the stack ships a local Gitea service (see below), in which case.envis left for that service's ownscripts/init_gitea.pyto populate. - Writes the admin
scripts/gitea_issues.pyCLI (see Admin).
Useful flags
--version <X.Y>— pin the dependency added to the stack; omitting it warns about version skew,--version latestopts into the newest release.--room-id— room id to create (defaultabout_<compose-project-name>).--gitea-host/--gitea-token— fill real.envvalues instead of placeholders.--no-local-gitea— skip local-Gitea auto-detection (see below) and keep the external-Gitea defaults (placeholder.envvalues and roomowner/repo).--with-truststore— install thesoliplex-concierge[truststore]extra so the tool verifies TLS against the OS trust store rather thancertifi's bundle; use when the Gitea host's certificate chains to an enterprise / internal CA (issue #46).--room-skill-dir/--docs-skill-dir(or--room-skill-version/--docs-skill-version) — install the skills from a local copy or a pinned tag instead of downloading the latest.--force— overwrite an existing room/skill.
Afterwards, set the real Gitea values in .env and rebuild:
docker compose build backend && docker compose up -d. Confirm both skills are
present under backend/environment/skills/ and that
uv run scripts/gitea_issues.py --help works.
Local Gitea service
When the target stack was generated by soliplex-template with include_gitea,
its docker-compose.yml defines a gitea service (backed by Postgres) and the
stack ships a scripts/init_gitea.py shim that provisions it. The installer
detects that service and, instead of emitting dead placeholders:
- wires the room's
create_gitea_issuetool tosoliplex-admin/soliplex-requests— the service account and repositoryinit_gitea.pycreates, and - leaves
.envuntouched, sinceinit_gitea.pywritesGITEA_HOST/GITEA_ACCESS_TOKENitself.
The order is then: run the installer → docker compose up -d → uv run
scripts/init_gitea.py (mints the token, creates the repo, populates .env) →
docker compose up -d backend to pick up the new .env. Pass --owner /
--repo to override the defaults, or --no-local-gitea to opt out of detection
entirely (for an external Gitea).
Manual wiring
For a non-generated installation, do the same steps by hand.
- Install the package into the environment that runs Soliplex (it depends
on
soliplex). In a containerized stack, addsoliplex-conciergeto whatever the backend image installs from —backend/requirements.txt, or theuv addblock in an older stack'sbackend/Dockerfile— and rebuild the image. For an environment managed directly:
# a uv-managed project
uv add soliplex-concierge
# an existing virtual environment
uv pip install soliplex-concierge
For an enterprise / internal CA, install soliplex-concierge[truststore]
instead so the tool verifies TLS against the OS trust store (issue #46).
- Merge the
installation.yamlentries from the bundledinstallation-snippet.yaml. They: - register the tool-config classes via
meta.tool_configs(Soliplex resolves each tool by its dottedtool_name; no core edit is needed), - add the directories of the two filesystem skills the about-room uses
(
soliplex-concierge-roomandsoliplex-docs) tofilesystem_skills_paths, and enable both underskill_configs, and -
declare the
GITEA_HOSTenvironment variable andGITEA_ACCESS_TOKENsecret the tool reads to call the Gitea REST API (no MCP server or external binary is required). -
Copy the about-room template from
rooms/about_soliplex/into your installation'srooms/directory, editing theowner/repoon thecreate_gitea_issuetool to point at your tracking repository. (Either may be a literal value or a Soliplex interpolation string such asenv:GITEA_OWNER.) -
Set the Gitea connection —
GITEA_HOSTand theGITEA_ACCESS_TOKENsecret (see the.envlines at the bottom of the snippet), using a token with Write access as noted above.
Configuring the about-room
The request_room and check_room_request tools (see
New rooms on request) need:
- the address of the stack's room provisioner service: each tool's
service_url, which defaults tohttp://soliplex-provisioner:8090, asoliplex-templatestack's service - the installation's
URL_SAFE_TOKEN_SECRETsecret, to sign their requests (asoliplex-templatestack declares it)
Whether a user may create rooms is the provisioner's call: it admits admins,
and users granted WRITE on the reserved room id __provision__ (the
provisioner's docs show how to write that policy).
An about-room installed before these tools existed lacks them: re-run the
installer with --force to replace the room (which also replaces any edits
made to it), or add the two tool entries from the bundled
room_config.yaml
and the new prompt.txt by hand.
The about-room answers questions from the bundled soliplex-docs skill, so no
RAG database is required. To also answer from this installation's own
ingested content, uncomment the skill_configs block in the room's
room_config.yaml, pointing rag_lancedb_stem at a database under rag/db/.
The soliplex-template skill
can generate and ingest one (see the
RAG DB docs).