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.

Requirements

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

Git
Python 3 – version 3.10 or newer
Docker engine
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.

DeepFellow Infra

Installation and Configuration

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):
💡      An Admin needs to identify itself in DeepFellow Infra to perform actions by providing DF_INFRA_ADMIN_API_KEY.
❓      DF_INFRA_ADMIN_API_KEY created. Is it safe to print it here? [y/n] (n):
💡      Configuration of DF_INFRA_API_KEY - key needed to communication between DeepFellow Infra and DeepFellow Server.
❓      DF_INFRA_API_KEY created. Is it safe to print it here? [y/n] (n):
💡      Configuration of DF_MESH_KEY - key needed by other DeepFellow Infra to attach to this DeepFellow Infra and thus extend the Mesh.
❓      DF_MESH_KEY created. Is it safe to print it here? [y/n] (n):
❓      Provide a docker network name (deepfellow-infra-net):
❓      Provide an optional Hugging Face API Key:
❓      Provide an optional Civitai Token:
💡      Generated /home/johndoe/.deepfellow/infra/.env.
💡      Saved Docker Compose configuration to /home/johndoe/.deepfellow/infra/docker-compose.yml

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

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 come back to this step later by typing:

deepfellow infra env-set DF_HUGGING_FACE_TOKEN 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

to setup Hugging Face, and:

deepfellow infra env-set DF_CIVITAI_TOKEN 7fea22cc5605cf498066059415157828

to setup Civitai.

In general, setting env values can be done with the command:

deepfellow infra env-set ENV_NAME ENV_VALUE

You can always display DeepFellow Infra API Keys by running deepfellow infra info command on your Infra host.

$ deepfellow infra info
💡      Variables stored in /home/johndoe/.deepfellow/infra/.env
        DF_NAME=infra
        DF_INFRA_URL=https://infra:8086
        DF_INFRA_MESH_URL=wss://infra:8086
        DF_INFRA_PORT=8086
        DF_INFRA_IMAGE=github.simplito.com:5050/df/deepfellow-infra:latest
        DF_MESH_KEY=dfmesh_cd11296a-1724-4db0-88d2-c5e92f8d22f7
        DF_INFRA_API_KEY=dfinfra_d7cc7af9-9615-4eb1-9a50-bff6aa31b23b
        DF_INFRA_ADMIN_KEY=dfinfraadmin_62594d27-3fcb-4aae-a7e5-a0bd3f505566
        DF_CONNECT_TO_MESH_URL=
        DF_CONNECT_TO_MESH_KEY=
        DF_INFRA_DOCKER_SUBNET=deepfellow-infra-net
        DF_INFRA_COMPOSE_PREFIX=dfd834zh_
        DF_INFRA_DOCKER_CONFIG=/home/johndoe/.docker/config.json
        DF_INFRA_STORAGE_DIR=/home/johndoe/.deepfellow/infra/storage
        DF_HUGGING_FACE_TOKEN=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
        DF_CIVITAI_TOKEN=7fea22cc5605cf498066059415157828
...

DF_INFRA_URL - URL of the installed DeepFellow Infra
DF_INFRA_MESH_URL - URL for connecting Infras
DF_INFRA_API_KEY - key to authenticate requests from DeepFellow Server
DF_INFRA_ADMIN_KEY - key needed to perform administrative tasks on DeepFellow Infra
DF_MESH_KEY - key needed by some other host to connect to this Infra and thus extend the Mesh
DF_CONNECT_TO_MESH_KEY - DF_MESH_KEY value of the parent Infra
DF_CONNECT_TO_MESH_URL - DF_INFRA_URL value of the parent Infra

Lastly, successful installation will be confirmed:

✅      DeepFellow Infra installed.
        To start the docker image - `deepfellow infra start`.
        For info about installation - `deepfellow infra info`.

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] --server [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.

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

You can install bigger models according to the VRAM you have. Here are some recommendations:

Model	8GB	12GB	16GB	24GB	32GB	64GB	80GB
qwen3:8b	✅	✅	✅	✅	✅	✅	✅
deepseek-r1:8b	✅	✅	✅	✅	✅	✅	✅
gemma3:4b	✅	✅	✅	✅	✅	✅	✅
gemma3:12b	❌	✅	✅	✅	✅	✅	✅
qwen3:14b	❌	✅	✅	✅	✅	✅	✅
deepseek-r1:14b	❌	✅	✅	✅	✅	✅	✅
gpt-oss:20b	❌	❌	❌	✅	✅	✅	✅
gemma3:27b	❌	❌	❌	✅	✅	✅	✅
qwen3:32b	❌	❌	❌	✅	✅	✅	✅
deepseek-r1:32b	❌	❌	❌	❌	✅	✅	✅
deepseek-r1:70b	❌	❌	❌	❌	❌	✅	✅

The recommendations above apply to models that use Q4_K_M quantization.

After successful installation, you will see:

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

You can install services and models using Web Panel as well. See DeepFellow Infra Web Panel guide for details.

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

Example

Assume you want to connect two Infras in a child-parent relation.

Think which one of the two machines will be parent, and which one child.
On parent Infra, get its DF_MESH_KEY value type by typing:

$ deepfellow infra info    # on parent Infra

💡      Variables stored in /home/mark/.deepfellow/infra/.env
        DF_NAME=infra
        DF_INFRA_URL=https://df-infra-node-1.com
        DF_INFRA_MESH_URL=wss://df-infra-node-1.com
        DF_INFRA_PORT=8086
        DF_INFRA_IMAGE=github.simplito.com:5050/df/deepfellow-infra:latest
        DF_MESH_KEY=dfmesh_dbc8c1cf-c07a-4bba-bda1-d89829be37bb
        DF_INFRA_API_KEY=dfinfra_c7a934fc-5e1f-41b2-b10e-57016c18d516
        DF_INFRA_ADMIN_KEY=dfinfraadmin_99d7df55-107b-4327-aeef-54e187f6c5aa
        DF_CONNECT_TO_MESH_URL=
        DF_CONNECT_TO_MESH_KEY=
        DF_INFRA_DOCKER_SUBNET=deepfellow-infra-net
        DF_INFRA_COMPOSE_PREFIX=dfd834zh_
        DF_INFRA_DOCKER_CONFIG=/home/mark/.docker/config.json
        DF_INFRA_STORAGE_DIR=/home/mark/.deepfellow/infra/storage
        DF_HUGGING_FACE_TOKEN=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
        DF_CIVITAI_TOKEN=7fea22cc5605cf498066059415157828
...

The list of environmental variables for parent Infra will appear.

Note the values of DF_CONNECT_TO_MESH_KEY and DF_CONNECT_TO_MESH_URL are empty - this means parent Infra is not connected as child to any other Infra.

To connect child Infra to a parent, type the following on the child:

deepfellow infra connect wss://df-infra-node-1.com dfmesh_dbc8c1cf-c07a-4bba-bda1-d89829be37bb

Child Infra will attempt to call parent Infra with DF_MESH_KEY. If parent Infra accepts the request, it will connect the child Infra. If succeeded, from now on the child Infra will have its DF_CONNECT_TO_MESH_KEY and DF_CONNECT_TO_MESH_URL values set:

$ deepfellow infra info    # on child Infra
💡      Variables stored in /home/helen/.deepfellow/infra/.env
        DF_NAME=infra
        DF_INFRA_URL=https://df-infra-node-2.com
        DF_INFRA_MESH_URL=wss://df-infra-node-2.com
        DF_INFRA_PORT=8086
        DF_INFRA_IMAGE=github.simplito.com:5050/df/deepfellow-infra:latest
        DF_MESH_KEY=dfmesh_05f1b75e-9951-4dda-88b3-2868646d26c7
        DF_INFRA_API_KEY=dfinfra_c7a934fc-5e1f-41b2-b10e-57016c18d516
        DF_INFRA_ADMIN_KEY=dfinfraadmin_99d7df55-107b-4327-aeef-54e187f6c5aa
        DF_CONNECT_TO_MESH_KEY=dfmesh_dbc8c1cf-c07a-4bba-bda1-d89829be37bb
        DF_CONNECT_TO_MESH_URL=https://df-infra-node-1.com
        DF_INFRA_DOCKER_SUBNET=deepfellow-infra-net
        DF_INFRA_COMPOSE_PREFIX=dfd834zh_
        DF_INFRA_DOCKER_CONFIG=/home/helen/.docker/config.json
        DF_INFRA_STORAGE_DIR=/home/helen/.deepfellow/infra/storage
        DF_HUGGING_FACE_TOKEN=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
        DF_CIVITAI_TOKEN=7fea22cc5605cf498066059415157828

This means child Infra is connected as child to another Infra located at https://df-infra-node-1.com.

Repeat the process to build a desired topology of Infras.

DeepFellow Server

Installation and Configuration

As administrator, prepare your administrator credentials (email and password) you want to use for managing DeepFellow Server. Remember your password. You can always Reset Password if needed.

Install and configure DeepFellow Server:

$ deepfellow server install
💡      Installing DeepFellow Server.
💡      DeepFellow Server requires a MongoDB to be installed.
❓      Do you have MongoDB installed for DeepFellow Server? [y/n] (n):
💡      A default MongoDB setup is created.
💡      DeepFellow Server is communicating with DeepFellow Infra.
❓      Provide DeepFellow Infra URL (http://infra:8086):
❓      Provide Deepfellow Infra API KEY:
❓      Provide a docker network name (deepfellow-infra-net):
💡      DeepFellow Server might use a vector DB. If not provided some features will not work.
❓      Do you have a vector DB ready? [y/n] (n):
❓      Do you want to run Milvus from this machine? [y/n] (y):
❓      Provide the model for embedding (text-embedding-3-small):
❓      Provide the embedding size (1536):
💡      Generated /home/johndoe/.deepfellow/server/.env.
💡      Saved Docker Compose configuration to /home/johndoe/.deepfellow/server/docker-compose.yml

✅      DeepFellow Server Installed.
        Call `deepfellow server start`.

Display information about DeepFellow Server by running deepfellow server info command on your Server host.

$ deepfellow server info
💡      Variables stored in /home/johndoe/.deepfellow/server/.env
        DF_SERVER_PORT=8000
        DF_SERVER_IMAGE=github.simplito.com:5050/df/deepfellow-server:latest
        DF_INFRA_DOCKER_SUBNET=deepfellow-infra-net
        DF_MONGO_URL=mongo:27017
        DF_MONGO_USER=deepfellow-user
        DF_MONGO_PASSWORD=some-password
        DF_MONGO_DB=deepfellow
        DF_INFRA__URL=http://infra:8086
        DF_INFRA__API_KEY=
        DF_VECTOR_DATABASE__PROVIDER__ACTIVE=1
        DF_VECTOR_DATABASE__PROVIDER__TYPE=milvus
        DF_VECTOR_DATABASE__PROVIDER__URL=http://milvus:19530
        DF_VECTOR_DATABASE__PROVIDER__DB=deepfellow
        DF_VECTOR_DATABASE__PROVIDER__USER=deepfellow_usr
        DF_VECTOR_DATABASE__PROVIDER__PASSWORD=some-other-password
        DF_VECTOR_DATABASE__EMBEDDING__ACTIVE=1
        DF_VECTOR_DATABASE__EMBEDDING__ENDPOINT=http://infra:8086
        DF_VECTOR_DATABASE__EMBEDDING__MODEL=text-embedding-3-small
        DF_VECTOR_DATABASE__EMBEDDING__SIZE=1536

Start

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

Create admin account

Before creating Admin account the DeepFellow Server should be up. If DeepFellow Server is down, enter deepfellow server start command.

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.

To perform administrative tasks on DeepFellow Server via CLI you have to log-in:

$ deepfellow server login
❓      Provide DeepFellow Server address: http://localhost:8000
💡      Updated /home/johndoe/.deepfellow/config.
❓      Please enter an email: admin@example.com
✅      Entered correct email.
❓      Please enter a password:
✅      Password accepted.
✅      Login successful.

Reset Password

To reset password to DeepFellow Server enter:

deepfellow server password-reset

You will be asked to enter email address you have provided during configuration steps. After automatic verification reset instructions will be sent there. If the email is not recognized no instructions will be sent there.

On this page