Skip to content

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 tool, and declaring the Gitea connection. The soliplex-concierge-installer skill does all of this for you on a soliplex-template-generated stack; the manual steps below are for any other installation.

Either way 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.

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-concierge to backend/pyproject.toml and the backend/Dockerfile uv add block (the generated Dockerfile ignores the pyproject.toml deps, so both are needed).
  • Merges six entries into backend/environment/installation.yaml: meta.tool_configs, environment, secrets, two skill_configs — for soliplex-concierge-room and soliplex-docs — and room_paths.
  • 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-room and soliplex-docs filesystem skills into backend/environment/skills/.
  • Appends the GITEA_HOST / GITEA_ACCESS_TOKEN placeholders to .env — unless the stack ships a local Gitea service (see below), in which case .env is left for that service's own scripts/init_gitea.py to populate.
  • Writes the admin scripts/gitea_issues.py CLI (see Admin).

Useful flags

  • --version <X.Y> — pin the dependency added to the stack; omitting it warns about version skew, --version latest opts into the newest release.
  • --room-id — room id to create (default about_<compose-project-name>).
  • --gitea-host / --gitea-token — fill real .env values instead of placeholders.
  • --no-local-gitea — skip local-Gitea auto-detection (see below) and keep the external-Gitea defaults (placeholder .env values and room owner/repo).
  • --with-truststore — install the soliplex-concierge[truststore] extra so the tool verifies TLS against the OS trust store rather than certifi'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_issue tool to soliplex-admin/soliplex-requests — the service account and repository init_gitea.py creates, and
  • leaves .env untouched, since init_gitea.py writes GITEA_HOST / GITEA_ACCESS_TOKEN itself.

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.

  1. Install the package into the environment that runs Soliplex (it depends on soliplex):
pip install -e .

For an enterprise / internal CA, install soliplex-concierge[truststore] instead so the tool verifies TLS against the OS trust store (issue #46).

  1. Merge the installation.yaml entries from the bundled installation-snippet.yaml. They:
  2. register the tool-config class via meta.tool_configs (Soliplex resolves the tool by its dotted tool_name; no core edit is needed),
  3. add the directories of the two filesystem skills the about-room uses (soliplex-concierge-room and soliplex-docs) to filesystem_skills_paths, and enable both under skill_configs, and

  4. declare the GITEA_HOST environment variable and GITEA_ACCESS_TOKEN secret the tool reads to call the Gitea REST API (no MCP server or external binary is required).

  5. Copy the about-room template from rooms/about_soliplex/ into your installation's rooms/ directory, editing the owner / repo on the create_gitea_issue tool to point at your tracking repository. (Either may be a literal value or a Soliplex interpolation string such as env:GITEA_OWNER.)

  6. Set the Gitea connection — GITEA_HOST and the GITEA_ACCESS_TOKEN secret (see the .env lines at the bottom of the snippet), using a token with Write access as noted above.

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