Installing the server¶
You install Fadenstack on one Linux server with its command-line tool, faden. One command sets up the
containers, HTTPS, the first administrator and a nightly backup; you then sign in to the console in a browser.
Before you start¶
- A Linux server that meets the System requirements: x86_64, Docker Engine 24 or later with
Compose v2, Python 3.12 or later with
pipxoruv. - Your user can run Docker without
sudo(it is in thedockergroup). - Ports 80 and 443 are free, or you know which other ports to use.
- The server can reach the internet to pull its images.
- Optional: a DNS name for the server, such as
ai.example.internal, and a certificate for it if you want to use your own (see HTTPS and trust).
Run faden doctor after installing the tool to check the host first.
Install¶
-
Install the command-line tool:
-
Run the deployment:
-
Answer its questions (below). When it finishes, it prints the addresses the console is reached at and, for a certificate it made, the file to trust.
What faden deploy does
faden deploy checks Docker, writes the deployment into ~/fadenstack (or the directory you name:
faden deploy /opt/faden), generates .env with random passwords and keys, sizes the services for the host,
pulls the images for the tool's own release, starts everything, and creates the first administrator. Grafana,
RabbitMQ and Langfuse each keep a random password of their own in .env: none of them is the administrator's
console password. Langfuse's first user is the administrator's e-mail with LANGFUSE_INIT_USER_PASSWORD; an
install made before this release has the console password it was deployed with in those three places, and .env
holds what each runs on.
What it asks¶
| Question | What to answer |
|---|---|
| Continue with the Preview release? | Asked first, after a notice, while the release is a Preview. Yes goes on and records who accepted it, and when. No, the default, stops the install, and nothing is changed. See Preview releases. |
| HTTPS | generate (the default): a certificate made on this server for its names and addresses. own: your certificate and key as PEM files. off: plain HTTP. |
| Other names or addresses | With generate: names the console is reached by that the server does not know itself, such as ai.example.internal. Comma-separated, blank for none. |
| A port to use instead | Only when port 80 or 443 is taken by something else. |
| Check for new releases? | Yes (the default): once a day the server and faden read the public list of releases and tell the administrators when one is out. Nothing about the server is sent. See Upgrading. |
| Days to keep deleted chats | 30 (the default): a chat someone deletes disappears for them at once and is erased for good, with its files, after this many days. 0 erases it within the hour. Administrators change it later under Settings → Chat. |
| Admin email | The first administrator's sign-in. |
| Admin password | At least 8 characters, and not the e-mail address. Leave blank to have one generated. |
| Save to file? | Saves the credentials to ~/fadenstack/.bootstrap-credentials (readable by you only). |
| Back up every night? | Yes (the default) runs faden backup at 03:00 and keeps the last 7. See Backups. |
| Make the backup key now? | Yes (the default) shows the backup recovery key once; every backup is encrypted to it from then on. See Encrypted backups. |
| I have kept a copy of this key off this server | Asked under the key. Copy it off the server first (a password manager, a sheet in a safe), then answer yes: the screen is cleared and you type two groups of the key from your copy. No, the default, makes no key: backups stay unencrypted until you run faden backup key create. |
The credentials are shown once. Store them in a password manager.
Without questions¶
faden deploy -y asks nothing: it accepts the Preview release, and takes HTTPS with a certificate made here, the
administrator admin@localhost with a generated password, saved to ~/fadenstack/.bootstrap-credentials, deleted
chats kept 30 days, the nightly backup and the update check on. Store the
credentials somewhere safe, then delete that file. The backup recovery key is left in
~/fadenstack/backup-recovery-key.txt: copy it off the server, then run faden backup key confirm.
Choices can be given up front:
faden deploy --tls generate --tls-name ai.example.internal
faden deploy --tls own --tls-cert fullchain.pem --tls-key key.pem
faden deploy --tls off
faden deploy --http-port 8080 --https-port 8443
faden deploy --runtime-images x86_64
--runtime-images says which runtime images the server keeps for the machines: all (the default), none, or
x86_64, aarch64 (NVIDIA DGX Spark), comma-separated. The choice is remembered for upgrades.
The runtime images¶
At the end, faden deploy pulls the runtime images: the containers the GPU machines run models in. The machines
download them from this server, not from the internet, so the server keeps them for each kind of machine: about
29 GB for x86_64 machines and 68 GB for DGX Spark (see Disk). This is the largest download
of the install. If it fails, the services are already running; retry it with:
faden runtime-images # fetch what this release needs
faden runtime-images --check # what the server holds, and what is missing
Sign in for the first time¶
- Open the address
faden deployprinted, such ashttps://ai.example.internal. - With a certificate made on the server, the browser warns that it does not know the issuer. Import
~/fadenstack/tls/ca.crtinto the browser (or the operating system) as a trusted certificate authority, then reload. See HTTPS and trust. - On Sign in to Fadenstack, enter the administrator's Email and Password, and select Sign In.

The console opens on the Dashboard, with a Getting started list: add a machine, create a cluster, host a model, try it in the chat, add people. Each step ticks itself when it is done.
Next: add the GPU machines.
Where things are¶
| Path | What it is |
|---|---|
~/fadenstack/ |
The deployment: compose file, .env, service configuration |
~/fadenstack/.env |
Every password, key and setting, readable by you only. Keep it private, and keep a copy with your backups |
~/fadenstack/tls/, ~/fadenstack/tls-ca/ |
The served certificate, and the server's own certificate authority with its key |
~/fadenstack/backups/ |
Backups |
~/fadenstack/backup-key.pub |
The public half of the backup key: backups are encrypted to it. It opens nothing |
~/fadenstack/backup-recovery-key.txt |
After faden deploy -y only: the recovery key, until faden backup key confirm deletes it |
~/fadenstack/logs/ |
The log of the daily certificate renewal (the nightly backup logs to ~/fadenstack/backups/backup.log) |
~/.config/faden/faden.yaml |
The tool's own settings: where the install is, which modules are on |
The data lives in Docker volumes named fadenstack_*, such as fadenstack_pg_data.
Where the company data is kept¶
| Data | Where | In a backup |
|---|---|---|
| Databases (users, chats, settings) | fadenstack_pg_data |
As dumps |
| Files attached to chats | fadenstack_faden_chat_files |
With --include-volumes |
| Files uploaded to the knowledge base | fadenstack_faden_rag_lite |
With --include-volumes |
| Models | fadenstack_faden_models |
No |
Before release 0.4.4, chat attachments had no volume: they lived inside the gateway container and were lost when
an upgrade or restore replaced it. faden upgrade copies the files the old container holds into the volume before it
replaces the container, so nothing is lost on that first upgrade.
To keep the company's files in a directory of your own, for example on storage your company manages, set it in
.env:
or give it at install time: faden deploy --data-dir /srv/fadenstack. Use an absolute path in POSIX form (on
Windows, /c/data). Empty, the default, keeps the Docker volumes.
What it covers is fixed, and will not grow in a later release:
| Folder | Holds |
|---|---|
/srv/fadenstack/chat-files |
The files attached to chats |
/srv/fadenstack/knowledge |
The files uploaded to the knowledge base |
It never covers the databases (fadenstack_pg_data), the models (fadenstack_faden_models) or the observability
data (logs, metrics, traces, Grafana). Those stay in Docker volumes, and get settings of their own if they ever move.
Switching it on copies your files. When faden deploy, faden upgrade, faden rebuild or faden up finds
FADEN_DATA_DIR set and a named volume that still holds files the folder lacks, it copies them into the folder before
it recreates any container, then compares every file by its SHA-256 hash. Nothing is overwritten: a file that exists
in both places with different content stops the command, naming the files, with nothing replaced. If a copy or a
comparison fails, the command stops the same way and the old services keep running. Run it again after you have fixed
the cause. The named volume is left as it was; once you are satisfied that the folder has everything, you can remove it
with docker volume rm. Running the command again copies nothing that is already there.
Switching it off again does not copy the files back. The folder keeps them, and the containers go back to the (old or empty) named volumes. To go back, copy the files into the volumes yourself first.
Docker logs¶
Each container's Docker log rotates: at most 5 files of 50 MB per container, the oldest dropped. Without a limit
the logs fill the disk. Change it in .env, or with faden deploy --log-max-size 100m --log-max-file 10:
Then run faden upgrade or faden rebuild so the containers are recreated with it. The logs you read in Grafana
are kept in Loki and are not rotated away: Alloy reads each container's log through Docker, which carries on across
a rotation. Keep the limits generous, as Docker keeps only what fits in them and Alloy has to be running to collect a line.
Redis memory¶
Redis holds short-lived data: the live events of chat replies, rate-limit counters, device presence, and
Langfuse's job queues when tracing is on. It is capped at 1 GB so a fault cannot fill the server's memory. At the cap
Redis does not drop data, it refuses new writes: the gateway then goes on without the shared copy of a reply's events
(a page that comes back mid-reply may not find them), and a request with a rate limit set may fail until memory is
free. Change the cap in .env, then run faden upgrade or faden rebuild:
Settings you change belong in .env. The other deployment files, such as nginx/nginx.conf, are replaced by the
next upgrade.
Secrets in .env¶
faden deploy writes every password, key and token the services need into ~/fadenstack/.env, each one random
and this install's own; faden upgrade adds the ones a new release needs. The compose file has no fallback for
any of them: started without one, docker compose stops and names it ("required variable ... is missing a
value").
Started by hand with docker compose instead, set them yourself, each to a long random value of its own
(openssl rand -base64 48):
| Variable | What it protects |
|---|---|
POSTGRES_PASSWORD |
The database login every service uses |
FADEN_BACKEND_SETTINGS_MASTER_KEY |
The secrets the console stores |
FADEN_BACKEND_CREDENTIAL_PEPPER |
The machines' credentials. A value of its own, which faden secrets rotate never changes, so the machines stay connected |
FADEN_MCP_ENCRYPTION_KEY |
The credentials of MCP servers |
FADEN_GATEWAY_ENCRYPTION_KEY |
The chats: messages, titles, memory, attachment notes. Required: the gateway does not start without it. Keep it with the backups, since chats sealed with it open with no other key |
FADEN_GATEWAY_MCP_SERVICE_TOKEN, FADEN_BACKEND_MCP_SERVICE_TOKEN, FADEN_MCP_SERVICE_TOKEN |
Calls to the MCP service. One value for all three |
FADEN_GATEWAY_SKILLS_SERVICE_TOKEN, FADEN_BACKEND_SKILLS_SERVICE_TOKEN, FADEN_SKILLS_SERVICE_TOKEN |
Calls to the skills service. One value for all three |
FADEN_GATEWAY_PII_SERVICE_TOKEN, FADEN_BACKEND_PII_SERVICE_TOKEN, FADEN_MCP_PII_SERVICE_TOKEN, FADEN_PII_SERVICE_TOKEN |
Calls to the PII service, which refuses every call without it (only its health check is open). One value for all four |
LANGFUSE_SALT, LANGFUSE_ENCRYPTION_KEY (64 hex characters: openssl rand -hex 32), LANGFUSE_NEXTAUTH_SECRET |
Langfuse's API keys, stored keys and sign-ins |
REDIS_AUTH, MINIO_ROOT_PASSWORD, CLICKHOUSE_PASSWORD, GRAFANA_ADMIN_PASSWORD |
The stores and Grafana. Grafana reads its password when it first starts, so changing it later in .env does not change it in Grafana |
LANGFUSE_INIT_USER_PASSWORD |
The password of Langfuse's first user (the administrator's e-mail). Langfuse reads it once, when it creates the user: change it in Langfuse after that, and note the new one in .env |
RABBITMQ_ADMIN_PASS, RABBITMQ_BACKEND_PASS, RABBITMQ_API_PASS, RABBITMQ_PII_PASS |
The message broker. Its users come from rabbitmq/definitions.json, which faden deploy writes from these |
Outside development, the backend, the gateway and the MCP and skills services do not start on the development values that are published with the source code, and say what to set.
The keys that open content are files, not environment
The settings master key, the pepper, the MCP key and the chat key (and their _PREVIOUS values during a
rotation) are not in any container's environment, where docker inspect and the console's container pages
would show them. Before every compose command it runs, faden writes them from .env into
~/fadenstack/secrets/ (readable by you only), and compose mounts each into the service that reads it, under
/run/secrets. Keep changing them in .env as before: after a change by hand, run faden up so the
services get the new value. Started with docker compose directly, write those files yourself, one per
variable, named like it.
An install started by hand before release 0.4.2¶
Until then the compose file fell back to fixed values when .env had none, the same for every install and
published with the source code. Most of them you can simply set to new random values. These seal stored data,
which is readable only with the value it was stored under: set them to the old value.
| Variable | The old value |
|---|---|
POSTGRES_PASSWORD |
postgres, or a new value that you also set in Postgres: docker exec -i faden-postgres psql -U postgres -c "ALTER USER postgres PASSWORD '<new value>'" |
FADEN_BACKEND_SETTINGS_MASTER_KEY |
dev-settings-master-key-change-me |
FADEN_BACKEND_CREDENTIAL_PEPPER |
The value FADEN_BACKEND_SETTINGS_MASTER_KEY has, so the machines' credentials stay valid (faden upgrade does this by itself) |
FADEN_MCP_ENCRYPTION_KEY |
dev-mcp-encryption-key-change-me-32b, if MCP was on; otherwise a new random value |
LANGFUSE_SALT |
mysalt |
LANGFUSE_ENCRYPTION_KEY |
64 zeros |
With the old settings master key or MCP key, also set FADEN_ALLOW_PUBLISHED_KEYS=true. The backend, the gateway
and MCP then start on it and warn at every start; without it they refuse. faden upgrade does the same by itself
for an install whose .env lacks one of these keys.
To replace such a key, run faden secrets rotate (see Rotating the keys): it encrypts what is
stored under the old key again with a new one, so nothing has to be entered again, and the machines stay connected.
Optional modules¶
Three modules can be added to the core services: pii (finds and masks personal data), mcp (tool servers for
chats and agents) and skills (saved instructions). They need more memory (see
System requirements).
faden up returns once every service is running and healthy, so the modules are ready for chats when it is done.
PII loads its model first: on a server without a GPU that takes about half a minute.
faden module disable pii, then faden up, takes one away again. faden up stops and removes the module's containers. Its data is kept.
One module is on from the start: provenance marks the content Fadenstack generates as AI-generated and checks such
marks, as the EU AI Act requires (Art. 50(2)). faden deploy switches it on in a new installation and faden upgrade
in an existing one. faden module disable provenance explains what stops being marked, asks you to confirm, and
records who switched it off and when; faden upgrade then leaves it off. Its records are kept as long as they are
needed and go into every backup. What it marks is on Content marking.
Local PII on CPU or GPU¶
PII detection runs on your server. Setup downloads the selected model files; chat text is processed locally. CPU processing is slower, especially with concurrent requests or long documents.
A long text on a server without a GPU
The check gives each request at most 8 seconds. On a server without a GPU, a request with a long text (a few
thousand characters, such as a document an agent includes) can take longer. Where the PII policy blocks what it
cannot check (by default for requests to cloud providers, and for requests to local models when Protect
requests to local models is on), such a request is then refused, and the message says "PII service
unavailable". What an administrator can do: run the check on a GPU (gliner2-multi-v1 with gpu-shared or
gpu-dedicated, below); for requests to local models, leave Protect requests to local models off in the
personal data policy, as it is by default; keep texts shorter.

-
Run
faden doctor. Local PII reports GPU compatibility, the installed detector, its content languages, the execution mode and the CPU thread budget.
-
Enable PII during deployment:
Choose the content locale, detector and execution mode. The default content pack is
europe-west-v1(English, German, French and Spanish).autoselects the recommended local detector, currentlypatronus-onnx-v1, with CPU execution. A compatible GPU allows GPU execution forgliner2-multi-v1. Without a compatible GPU, execution falls back to CPU while preserving the selected detector. -
Open the personal data policy in the console. Review the installed profile, select its language and adopt it when changing the detector or locale pack. Existing policy choices are retained. An unlisted language is refused; it is never silently treated as English.
Choose the content languages and detector
| Locale pack | Accepted policy languages |
|---|---|
europe-west-v1 |
en, de, fr, es |
english-v1 |
en |
german-v1 |
de |
french-v1 |
fr |
spanish-v1 |
es |
Select languages for the content you process. A pack does not infer a person's nationality. Other languages are not currently offered. A single-language pack also requires matching languages in your saved policies.
faden deploy --modules pii --pii-locale german-v1 --pii-model auto --pii-profile cpu -y
faden deploy --modules pii --pii-model gliner2-multi-v1 --pii-profile gpu-shared -y
faden deploy --modules pii --pii-model gliner2-multi-v1 --pii-profile gpu-dedicated --pii-gpu-id 0 -y
patronus-onnx-v1 supports CPU execution. gliner2-multi-v1 supports CPU and compatible NVIDIA GPUs.
Choosing a GPU does not change the detector automatically. legacy retains the older English-only option.
For an existing installation, faden module enable pii accepts the same options. Run faden up afterward.
Use --pii-model-dir /opt/faden/pii-models/cpu for a previously provisioned directory containing its manifest,
including offline setup. The directory must match the selected detector. Only that detector is downloaded;
previous model directories remain available for rollback.
CPU threads and GPU memory
gpu-shared is for a GPU used by other software too. gpu-dedicated is for a GPU kept available for PII;
selecting it does not stop other software from using that GPU.
Automatic CPU threads use a quarter of the available threads, capped at eight for CPU execution and two for
GPU execution. --pii-cpu-threads 2 sets an explicit count. Container CPU limits also apply at startup.
--pii-gpu-memory-mib 4096 sets the allocator budget; it does not reserve memory from other software.
The PII container also has a 4 GiB host RAM limit. FADEN_PII_MEMORY_LIMIT in .env changes that limit;
run faden up afterward. Host RAM and GPU memory are separate budgets.
Extended PII fields¶
The installed detector and the policy are separate choices. CPU/GPU mode chooses where detection runs;
FADEN_PII_ENTITY_PROFILE chooses the available filter set. The console policy chooses which categories to apply.
- Enable a local multilingual PII mode as described above.
-
Set this line in the installation's
.env: -
Run
faden up, thenfaden doctor. Doctor reports the configured entity filter set. Check that the PII service is healthy withfaden status. - Open the personal data policy, adopt the installed profile and select the added categories. Review tenant overrides too. Run representative checks before relying on the wider policy.
standard retains the original filter set. extended requires a local multilingual detector; it cannot be combined
with legacy. Returning to standard also requires reviewing policies that request extended categories.
An upgrade keeps your chosen filter set. It does not automatically add categories to existing policies.
Keep the model directory selected by the installer: --pii-model-dir must point directly to the directory containing
manifest.json, not its parent. Do not copy one detector's calibration file to another detector.
Everyday commands¶
| Command | What it does |
|---|---|
faden status |
Every service, running or not, and healthy where it has a check |
faden logs -f faden-backend |
Follow one service's log (all services without a name) |
faden up / faden down |
Start the services and wait until they are healthy (--no-wait returns at once), or stop them; the data stays |
faden doctor |
Check the host, the ports and the certificate |
faden config show |
Where the install is and how the tool is set up |
faden admin reset-password --email [email protected] |
Set a new password for a user who cannot sign in. It changes the console sign-in only, not Grafana, Langfuse or RabbitMQ |
faden --help |
Every command; faden <command> --help for its options |
Removing Fadenstack¶
faden down stops and removes the containers and keeps the data volumes, so faden up brings everything back.
Warning
faden down --volumes also deletes the data volumes: the database, every chat, the model store. It cannot be
undone. Take a backup first and copy it off the server.
When it does not work¶
| You see | What to do |
|---|---|
Docker is not available or Docker daemon is not running |
Install Docker Engine with the Compose plugin, start it, and make sure your user is in the docker group (log out and in again after adding it). |
HTTP port 80 is in use by something else. |
Another program holds the port. Free it, or run faden deploy --http-port 8080 --https-port 8443. faden doctor lists every port the install publishes and whether something else holds it. |
Backend did not become healthy in time — skipping admin setup. |
The services started but the console API did not answer in time. Check faden status and faden logs faden-backend, fix what they show, then run faden deploy again: it keeps the .env and creates the administrator. |
The backend refused to create the administrator |
The backend creates the first administrator only for whoever sends the install's bootstrap token, FADEN_BACKEND_BOOTSTRAP_TOKEN in ~/fadenstack/.env. faden deploy writes one when .env has none. An install started some other way may lack it, and a backend started before it was set does not know it yet: run faden up, then faden deploy again. |
Some images failed to pull. |
The server could not reach a registry. Check its internet access and proxy, then run faden deploy again. |
| The browser refuses the certificate | The server's certificate authority is not trusted on that computer yet. Import ~/fadenstack/tls/ca.crt, or use a certificate from your own issuer (see HTTPS and trust). |
required variable ... is missing a value from docker compose |
.env lacks a password, key or token the compose file requires. faden upgrade adds them; for an install started by hand, see Secrets in .env. |
A service stops at start with ... is the development default published with Fadenstack's source code |
The backend, the gateway, MCP or the skills service found a published development value. The message says what to set; Secrets in .env has the details, also for an install that has stored data under it. |
| The console says "This server still uses the default settings master key" | The install runs on the published development key, kept with FADEN_ALLOW_PUBLISHED_KEYS=true because its stored secrets are sealed with it. See Secrets in .env for what changing it means. |