Skip to content

System requirements

What the server and the GPU machines need before you install anything. The server is sized by the services it runs and the people using them; a GPU machine is sized by the models it runs.

The server

Minimum Recommended
Operating system Linux, x86_64
CPU cores 4 8
Memory, core services 8 GB 12 GB
Memory, with the multilingual PII, MCP and skills modules 12 GB 16 GB
Disk, with the runtime images for both kinds of machine (the default) 150 GB 250 GB, plus the size of the models you intend to host
Disk, with the runtime images for x86_64 machines only 70 GB 120 GB, plus the size of the models you intend to host
GPU none none

faden doctor fails a server with less than 7 GB of memory, which is what a server with 8 GB reports once the kernel has its share, and one with less than 20 GB of free disk. Those are its floor for the services alone; the disk figures above add the runtime images that faden deploy pulls (see Disk).

The server also needs
Docker Engine 24 or later with Compose v2 The user who runs faden must be able to use Docker (be in the docker group).
Python 3.12 or later With pipx or uv, to install the faden command-line tool.
Ports 80 and 443 free On the server. Other ports can be chosen; see Network and ports.
Internet access while installing and upgrading To pull the service images and the runtime images. See What needs the internet.

Add memory for anything else you run on the server. The server needs no GPU: the models run on the machines you add. A server that has an NVIDIA GPU can also be added as a machine.

faden doctor checks a host before you install: memory, free disk, Docker, Compose, and whether the ports the install publishes are free.

What grows with what

When you add What grows on the server
People chatting at the same time CPU of the gateway and the console API first, then database connections
The PII module Additional memory for its selected model and more CPU per chat turn; allow at least 4 GB for the multilingual PII container, plus the other services
MCP tools, skills A few hundred MB of memory
Models Disk: every model is downloaded to the server and copied to the machines from there
GPU machines The runtime images for each kind of machine on disk; nothing measurable in CPU or memory
Tracing Disk for the trace store

To size the services again after changing the hardware, run faden tune and then faden up.

PII can use a compatible local NVIDIA GPU, or run on CPU without one. CPU handling is slower for concurrent requests and long documents. faden doctor reports compatibility and CPU availability. See Local PII on CPU or GPU for selection and fallback behavior.

More about sizing the services

faden deploy and faden upgrade size the services for the host they run on: how many worker processes each service gets, and how many database connections Postgres accepts.

Disk

What Size Needed when
Service images about 17 GB always
Runtime images, x86_64 machines about 29 GB (two images of about 14.5 GB) you add x86_64 GPU machines
Runtime images, NVIDIA DGX Spark machines about 68 GB (two images of 35 and 33 GB) you add DGX Spark machines
Model store the models you host always
Database grows with chat history always
Trace store grows with traces tracing is on

The server keeps the runtime images for each kind of machine, because the machines download them from the server, not from the internet. A release pins two per kind of machine: the current one and the one before it, for clusters not switched yet. faden deploy pulls them for both kinds unless you say otherwise, about 97 GB on top of the service images. If you only have x86_64 machines, install with faden deploy --runtime-images x86_64 to skip the DGX Spark ones; faden runtime-images --check shows what the server holds.

Ubuntu Server's default disk layout

On a large disk, Ubuntu Server's installer gives the root file system a logical volume of about 100 GB and leaves the rest of the disk unused. That fills up while the runtime images are pulled. Grow it before you install, for example with sudo lvextend -r -l +100%FREE /dev/ubuntu-vg/ubuntu-lv, or install with --runtime-images for the machines you have.

Backups land on the same disk by default; leave room for them, or send them elsewhere (see Backups).

GPU machines

Operating system Linux: x86_64, or aarch64 on NVIDIA DGX Spark only
GPU NVIDIA only, with a working driver: nvidia-smi must print your card
Containers Docker or Podman, running, and usable by the user the agent runs as, with access to the GPU (for Docker, the NVIDIA Container Toolkit)
Service manager systemd: the agent runs as a system service, or as a user service when installed without sudo
Disk about 15 GB for the runtime image, plus room for the models it runs; a runtime switch needs room for a second image while it runs
Network Reach the server's HTTPS port. The server must reach the machine's model port. Machines in one cluster must reach each other. See Network and ports

Two kinds of machine are supported, each with its own runtime image:

  • x86_64 machines with NVIDIA GPUs, from the Turing generation to Blackwell. Their runtime image is not certified yet: the cluster's Runtime card says Not certified.
  • NVIDIA DGX Spark (GB10, aarch64).

Other machines are not supported.

What happens with other machines

One without an NVIDIA GPU, or with another processor architecture, joins but cannot be put in a cluster: the cluster wizard says that no certified runtime image runs on it. Another aarch64 machine with an NVIDIA GPU is offered the DGX Spark image, which is not made for it.

Note

A model runs on one kind of GPU at a time. Mixed machines can share a cluster, but each copy of a model lands on machines of one kind. Machines that should run one model together need the same GPUs.

GPU memory decides which models fit. The model marketplace shows, for each model and cluster, whether it fits on a share of one accelerator, on one, across several, or not at all (see Models).

What needs the internet

Who Reaches When
Server Container registries (ghcr.io, Docker Hub and the others the images come from) installing and upgrading
Server Hugging Face downloading models
Server Remote model providers, remote MCP servers if the administrator connects any
Server GitHub to check its own copy of the agent builds, if it holds one
GPU machines GitHub (the project's releases) installing or updating the agent, unless the server holds the agent builds
GPU machines Hugging Face only on a cluster set to let its machines download models themselves

Everything else a machine needs, the runtime image and the models, comes from the server. A machine without internet access works as long as the server holds the agent builds; see Machines without internet access.