Fadenstack

The single entry point to deploy, configure, and manage the fadenstack platform — an open-source LLM gateway that routes, secures, and observes traffic across local runtimes and remote providers.

pipx install fadenstack       # or: uv tool install fadenstack
faden deploy                 # installs Fadenstack into ~/fadenstack and starts it

The CLI carries the deployment files of its release and runs that release's published images: fadenstack 0.4.3 deploys Fadenstack 0.4.3. To upgrade, upgrade the CLI and run faden upgrade. See Installing Fadenstack.

Features

• One-command production deploy — pre-flight checks, .env generation, the release's images, database migrations, and service startup.
• Upgrade, backup and restore — faden upgrade backs up every database, moves the install to the CLI's release and keeps your settings.
• Auto-tuning — detects host CPU / RAM and computes optimal worker counts, DB pool sizes, and queue channel pools.
• Module management — enable / disable optional services (PII redaction, MCP tools, skills) via Docker Compose profiles.
• GPU detection — faden doctor lists the host's GPUs; faden deploy adds the NVIDIA GPU overlay when the host has an NVIDIA runtime.
• Developer workflow — clone all repos, install deps, run infra + migrations, and generate a VS Code workspace in one command.
• Rich terminal UI — tables, progress bars, and themed output powered by Rich.
• Command abbreviation — type faden st instead of faden status.

Requirements

Git is only needed to deploy from a source checkout (--build) or for the developer workflow.

Installation

From PyPI

pip install fadenstack

# or with uv
uv tool install fadenstack

From source

git clone https://github.com/fadenstack/fadenstack.git
cd fadenstack/cli
uv sync                   # install deps + editable entry point
uv run faden --help

Verify

faden version
faden doctor

Quick start

Production deployment

# Full deploy — pre-flight, env gen, pull this release's images, migrate, start
faden deploy                      # into ~/fadenstack
faden deploy /opt/faden         # into a directory of your choice

# Enable optional modules
faden deploy --modules pii,mcp

# From a source checkout: build the images instead of pulling them
faden deploy --build

# Upgrade to the CLI's release (backs up first), back up, restore
faden upgrade
faden backup
faden restore ~/fadenstack/backups/<time>

# Provision node-agent on this host during deploy
faden deploy /opt/faden --local-node

# Provision node-agent on remote host over SSH
faden deploy /opt/faden --local-node --local-node-host ubuntu@10.0.0.12

Day-to-day operations

faden up                          # start all services
faden up --build faden-gateway     # rebuild a single service
faden down                        # stop all services
faden down --volumes              # stop + remove volumes
faden status                      # service table
faden logs -f                     # tail all logs
faden logs -f faden-backend    # tail one service

Modules

faden module list                 # show available modules
faden module enable pii skills    # enable modules
faden module disable mcp          # disable a module

Configuration

faden config show                 # print current config
faden config set dev.branch main  # update a value (dot-notation)
faden config edit                 # open in $EDITOR
faden config path                 # print config file location

Auto-tuning

faden tune                        # detect resources, write .env
faden tune --profile prod         # production-grade sizing
faden tune --dry-run              # preview without writing

Admin utilities

faden admin reset-password --email admin@localhost

Developer workflow

# Bootstrap everything — clone repos, install deps, start infra,
# run migrations, generate VS Code workspace
faden dev init ~/projects/fadenstack
faden dev init ~/projects/fadenstack --ssh        # SSH cloning
faden dev init ~/projects/fadenstack --overwrite   # re-clone existing repos

# Start / stop / status
faden dev up                            # on this machine only (127.0.0.1)
faden dev up --lan                      # on every interface, for one run
faden dev up --backend-only
faden dev up --modules pii,mcp,skills   # also run the optional modules
faden dev up --local-node
faden dev up --local-node --local-node-host ubuntu@10.0.0.12
faden dev down
faden dev status

# Check dev prerequisites (optionally auto-install missing tools)
faden dev doctor
faden dev doctor --install --yes

--modules runs PII (8003), MCP (8007) and skills (8008) on the host beside the backend, and points the gateway and backend at them. Without it, the modules switched on with faden module enable run; the others are switched off in the gateway and backend. See What happens to a request.

--local-node installs a systemd unit by default and requires sudo on Linux. Use --local-node-no-sudo to skip privileged systemd setup.

Command reference

Project structure

cli/
├── pyproject.toml
├── src/
│   └── faden_cli/
│       ├── cli.py                 # Click root group + AliasedGroup
│       ├── commands/
│       │   ├── version.py         # version
│       │   ├── doctor.py          # doctor
│       │   ├── deploy.py          # deploy
│       │   ├── up.py              # up
│       │   ├── down.py            # down
│       │   ├── status.py          # status
│       │   ├── logs_cmd.py        # logs
│       │   ├── config.py          # config group
│       │   ├── module.py          # module group
│       │   ├── tune.py            # tune
│       │   ├── admin.py           # admin group
│       │   └── dev/               # developer workflow
│       │       ├── dev_init.py
│       │       ├── dev_up.py
│       │       ├── dev_status.py
│       │       └── dev_doctor.py
│       ├── core/                  # shared utilities
│       │   ├── compose.py         # Docker Compose wrapper
│       │   ├── detect.py          # OS / GPU / port detection
│       │   ├── settings.py        # YAML config (~/.config/faden/)
│       │   ├── api_client.py      # Backend REST client (httpx)
│       │   ├── bootstrap.py       # First-admin bootstrap
│       │   ├── env_gen.py         # .env generation (Jinja2)
│       │   ├── git.py             # Git clone / checkout helpers
│       │   ├── install.py         # Cross-platform tool installer
│       │   ├── registry.py        # Central metadata registry
│       │   ├── sysinfo.py         # Resource detection + tuning
│       │   └── console.py         # Rich themed output
│       ├── tui/                   # Textual TUI wizard
│       └── templates/             # Jinja2 .env templates
└── tests/

License

Apache License 2.0 — see LICENSE for details.

Part of the fadenstack project.