Installation

The minimal setup for DeepFellow Architecture is one DeepFellow Server and one instance of DeepFellow Infra. DeepFellow Server and DeepFellow Infra can be installed on the same machine. For efficiency at scale, we recommend installing them on different server machines. Note that you can install more DeepFellow Infras and connect them together into so called Mesh to gain efficiency via load-balancing.

See Architecture for an example layout.

To perform administrative tasks via CLI, see Logging In.

Requirements

Make sure you have the following programs in your system before installing DeepFellow:

• Git - version 2.30.0 or newer
• Python 3 – version 3.10 or newer
• Docker engine - version 28.0.0 or newer
• Python package manager – one of the following: uv, pipx, pip3 / pip

DeepFellow CLI

To install DeepFellow CLI on every machine dedicated to be DeepFellow Server or DeepFellow Infra:

curl https://deepfellow.ai/install.sh | bash

To verify successful installation of DeepFellow CLI, type deepfellow:

$ deepfellow
`deepfellow --help` for help with commands.

Quick Install

For a single-command setup with recommended defaults, run:

deepfellow suite install

This command provisions DeepFellow Infra, DeepFellow Server, an admin account, and a ready-to-use workspace consisting of an organization, a project, and an API key, in one pass. It prompts for the admin account's name, email, and password. Pass --admin-name, --admin-email, and --admin-password instead to skip the prompts, for example in a script. It installs the ollama service with GPU-accelerated defaults, three models (a chat model, an embedding model, and a fast model), and a Milvus vector database. All defaults are hardcoded, and the command cannot resume after a partial failure.

Continue with DeepFellow Infra and DeepFellow Server below to configure each component individually, for example to customize SSL, connect Infras into a Mesh, or choose a different vector database.

DeepFellow Infra

Installation

Install and configure DeepFellow Infra:

$ deepfellow infra install
💡      Installing DeepFellow Infra.
❓      Provide a DF_NAME for this Infra (infra):
❓      Provide a DF_INFRA_URL for this Infra (http://infra:8086):
❓      Provide a docker network name (deepfellow-infra-net):
❓      Is it safe to print API keys here? [y/n] (n):
💡      Configuration of DF_INFRA_ADMIN_API_KEY
        key required for an admin identify in DeepFellow Infra.
💡      Configuration of DF_INFRA_API_KEY
        key needed to communication between DeepFellow Infra and DeepFellow Server.
💡      Configuration of DF_MESH_KEY
        key needed by other DeepFellow Infra to attach to this DeepFellow Infra and thus extend the Mesh.

You will be offered to optionally enter API Keys for various services you might want to use:

❓      Provide an optional Hugging Face Token (hf***bc):
❓      Provide an optional Civitai Token (13***ff):

• Hugging Face - Get Hugging Face API Key
• Civitai - Get Civitai API Key models, set DF_CIVITAI_TOKEN as well.

You can skip these if you want. You can always configure your envs later.

Lastly, successful installation will be confirmed:

💡      Generated /home/mchambers/.deepfellow/infra/.env.
💡      Updated /home/johndoe/.deepfellow/config.
💡      Updated /home/johndoe/.deepfellow/secrets.
💡      Saved Docker Compose configuration to /home/johndoe/.deepfellow/infra/compose.yaml
💡      Pulling docker image(s).
✅      DeepFellow Infra installed.
        To start the docker image - `deepfellow infra start`.
        For info about installation - `deepfellow infra info`.

Non-Interactive Installation

For scripting and automation, pass --non-interactive with the required options:

deepfellow --non-interactive infra install

The installer applies default values for all prompts and auto-generates API keys. To customize any value after installation, use deepfellow infra env set. See Envs for the full list of variables.

Configure SSL

You can setup the SSL certificates automatically by typing:

deepfellow infra ssl-on

This command will create and setup a certificate for you for default port 443. You can use your own key file and cert file as well as customize the port and the URL at which Infra with SSL is available:

deepfellow infra ssl-on [SSL-KEY-PATH] [SSL-CERT-PATH] --port [SSL-PORT] --url [SSL-INFRA-URL]

Alternatively, you can expose given DeepFellow Infra through an nginx reverse proxy that handles SSL/TLS termination.

Start

$ deepfellow infra start
💡 Starting DeepFellow Infra
✅ DeepFellow Infra started.

Restart

To apply a configuration change or recover the stack without running two commands, restart DeepFellow Infra. The restart command stops the whole Docker Compose stack, then starts it again.

$ deepfellow infra restart
💡 Restarting DeepFellow Infra
💡 DeepFellow Infra started on http://localhost:8086

To restart an installation in a non-default location, pass --directory (or --dir).

Install First Model

To install a model, you need to install a service first. Type in your terminal:

deepfellow infra service install ollama
deepfellow infra model install ollama gemma3:1b

Install bigger models according to your available VRAM. See Hardware Requirements for model recommendations by VRAM tier.

After successful installation, you will see:

✅      Service ollama installed.
✅      Model gemma3:1b installed.

The ollama service runs locally and needs no API key. To install a remote service, pass the provider API key with the --api-key flag:

deepfellow infra service install claude --api-key ANTHROPIC_API_KEY
deepfellow infra service install google --api-key GEMINI_API_KEY
deepfellow infra service install openai --api-key OPENAI_API_KEY

When you omit --api-key for a service that requires one, the CLI prompts you for the key.

To list the services installed on an Infra instance, run:

deepfellow infra service list

The command shows only installed services. For each one it prints the id, type, instance, description, and whether the backend is downloaded:

$ deepfellow infra service list
💡      id: ollama
        type: ollama
        instance: default
        description: Self-hosted easy to use LLM model runner.
        downloaded: True

When no services are installed, the command prints No services installed.

To target a specific instance, pass --url. Otherwise the command resolves the instance from the DF_INFRA_EXTERNAL_URL environment variable or prompts you for it:

deepfellow infra service list --url http://localhost:8086

To uninstall model you can type:

deepfellow infra model uninstall ollama gemma3:1b

If you have many installed models in one of the services you can simply uninstall the service:

deepfellow infra service uninstall ollama

All models in the service will be uninstalled automatically.

Connect More Infras

You can build an arbitrary topology (called Mesh) with your Infras by connecting them in child-parent relations.

Repeat the previous installation and configuration steps for each machine you dedicate to be DeepFellow Infra.

Then, to connect two Infras, use the following command on one of them:

deepfellow infra connect DF_INFRA_MESH_URL DF_MESH_KEY

To disconnect them:

deepfellow infra disconnect

See Connecting Infras into a Mesh for a worked example that connects a parent and a child Infra.

Envs

See Environment Variables (CLI) to inspect and change DeepFellow Infra's configuration from the command line.

DeepFellow Server

Installation

To install and configure DeepFellow Server, start with:

deepfellow server install

You will proceed to configure built-in components:

• Docker network
• no-sql database (for example MongoDB)
• connection with DeepFellow Infra
• vector database and embedding model
• telemetry

Docker Network

The installer first asks which Docker network DeepFellow Server will join. Use the same network name you chose during Infra installation so Server and Infra can reach each other:

$ deepfellow server install
💡      Installing DeepFellow Server.
❓      Provide a docker network name (deepfellow-infra-net):

MongoDB

💡      DeepFellow Server requires a MongoDB to be installed.
❓      Install a local MongoDB for DeepFellow Server? [y/n] (y):
💡      A default MongoDB setup is created.

If you choose n instead, you will be asked to provide Mongo URL (not mongo connection string!):

❓      Provide host:port for MongoDB e.g. 192.168.1.5:27017: mongo:27017

If you use a service name like mongo, Docker will resolve it to the MongoDB container. Be careful: localhost will not work as it refers to the container's own loopback interface.

You will be asked about database name and credentials:

❓      Provide database name for MongoDB: deepfellow
❓      Provide username for MongoDB: deepfellow-usr
❓      Provide password for MongoDB:

Connection with Infra

Next, the installator will proceed to configure connection with Infra:

💡      DeepFellow Server is communicating with DeepFellow Infra.
❓      Provide DeepFellow Infra URL (http://infra:8086):
❓      Provide DeepFellow Infra API KEY:

Docker resolves a name like infra internally to a Compose service name. Be careful: localhost will not work as it refers to the container's own loopback interface.

Vector Database

Next, the installer configures the vector database and embedding model:

💡      DeepFellow Server might use a vector DB. If not provided some features will not work.
❓      Do you want to use a vector database with DeepFellow? [y/n] (y):
❓      Choose embedding type dense
❓      Choose the type of the vector database qdrant
❓      Install a local vector database for DeepFellow Server? [y/n] (y):
💡      DeepFellow will manage a Qdrant instance.
❓      Provide the model for embedding (mxbai-embed-large):
❓      Provide the embedding size (1024):

The available embedding types are dense and sparse. The available vector database backends are qdrant and milvus.

Answer n to "Install a local vector database?" if you want to connect to an existing instance. You will be asked for its URL:

❓      Install a local vector database for DeepFellow Server? [y/n] (y): n
❓      Provide Qdrant instance URL (http://qdrant:6333):

If you use a service name like qdrant, Docker will resolve it to the Qdrant service. Be careful: localhost will not work as it refers to the container's own loopback interface.

Telemetry

After that, OpenTelemetry configuration will start:

💡      DeepFellow Server might use an Open Telemetry.
❓      Do you have an Open Telemetry server ready? [y/n] (n): n
❓      Do you want to run Open Telemetry from this machine? [y/n] (n): y
💡      Let's configure Open Telemetry
❓      Do you want to export to Elasticsearch? [y/n] (n):

If you answer n to "Do you want to export to Elasticsearch?" (the default), DeepFellow generates a debug-only OTel collector configuration. No Elasticsearch instance is required.

Inspect telemetry via the container log once Server is running:

docker logs -f otel-collector-container

This mode suits local development, workshops, and demo environments.

To export to Elasticsearch, answer y. You will be prompted for your credentials:

❓      Do you want to export to Elasticsearch? [y/n] (n): y
❓      Provide your ElasticSearch endpoint: https://myelastic.com:9200
❓      Provide traces index: my-index
❓      Provide username: elastic_user
❓      Provide password:

In both cases, installation ends with:

⚠️       Open Telemetry configuration stored in file:
        /home/johndoe/.deepfellow/server/otel-collector-config.yaml
        Please review its content before starting the DeepFellow Server.

To use an existing OTel server instead of running one locally, answer y to "Do you have an Open Telemetry server ready?" You will be asked to provide the URL:

❓      Provide OTL url (http://otel-collector:4317):

If you use a service name like otel-collector, Docker will resolve it to the otel-collector service in compose. Be careful: localhost will not work as it refers to the container's own loopback interface.

By default, the server exports only traces to the collector. To also forward the server's Python log records, set DF_OTEL_LOGGING_ENABLED to true:

deepfellow server env set DF_OTEL_LOGGING_ENABLED true

The server ships logs to the endpoint defined by DF_OTEL_EXPORTER_OTLP_ENDPOINT (default http://localhost:4317). This endpoint must accept the OTLP log signal over insecure gRPC. The server exports logs under the service name llm-audit, which lets you correlate them with existing traces in your observability backend. Tracing and log export are independent. Enable each one with its own variable, DF_OTEL_TRACING_ENABLED and DF_OTEL_LOGGING_ENABLED.

After configuring the components, successful installation will be confirmed:

💡      Generated /home/johndoe/.deepfellow/server/.env.
💡      A default Qdrant setup is created.
💡      Updated /home/johndoe/.deepfellow/config.
💡      Saved Docker Compose configuration to /home/johndoe/.deepfellow/server/compose.yaml
✅      DeepFellow Server Installed.
        Call `deepfellow server start`.

Non-Interactive Installation

For scripting and automation, pass --non-interactive with the required options:

deepfellow --non-interactive server install

The installer applies default values for all prompts and auto-generates secrets. To customize any value after installation, use deepfellow server env set. See Envs for the full list of variables.

OpenTelemetry in Non-Interactive Mode

In non-interactive mode, you have two ways to enable tracing:

• --otel-local – starts a local debug-only OTel collector as part of the Docker Compose stack. No Elasticsearch is required. Use this for development or testing environments where you want tracing enabled without an external OTel backend.
• --otel-url URL – connects to an existing OTel collector at the given gRPC endpoint.

--otel-local and --otel-url are mutually exclusive. Pass only one.

To install DeepFellow Server with a local OTel collector:

deepfellow --non-interactive server install \
  --infra-url http://infra:8086 \
  --otel-local

The collector writes traces to its debug exporter only. To ship traces to Elasticsearch, use --otel-url and point it at an existing OTel collector configured with an Elasticsearch exporter, or run the interactive installer.

Start

$ deepfellow server start
Server start using config: /Users/simplito/.deepfellow/server/config.json
💡      Starting server
✅      DF Server started.

Restart

To apply a configuration change or recover the stack without running two commands, restart DeepFellow Server. The restart command stops the whole Docker Compose stack, then starts it again.

$ deepfellow server restart
💡 Restarting DeepFellow Server
💡 DeepFellow Server started on http://localhost:8000

To restart an installation in a non-default location, pass --directory (or --dir).

Create Admin Account

To create Admin account use deepfellow server create-admin command:

$ deepfellow server create-admin
❓      Provide admin name: admin
❓      Provide admin email: admin@example.com
❓      Provide admin password:
💡      Admin account created.

Login

See Logging In to authenticate on DeepFellow Server via CLI.

Reset Password

To reset the password for a DeepFellow Server account, see Resetting a Password.

Configure Email for Invitations

DeepFellow Server sends invitations over email. See Configure Email for Invitations to set up the required SMTP server.

Envs

See Environment Variables (CLI) to inspect and change DeepFellow Server's configuration from the command line.