DeepFellow Infra

Installation

$ deepfellow infra install
💡      Installing DeepFellow Infra.
❓      Provide a Name for this Infra (infra):
❓      Provide a 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 Admin API Key
        key required for an admin to identify in DeepFellow Infra.
💡      Configuration of Infra API Key
        key needed for communication between DeepFellow Infra and DeepFellow Server.
💡      Configuration of Mesh Key
        key needed by other DeepFellow Infra to attach to this DeepFellow Infra and thus extend the Mesh.

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

💡      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.

If Docker runs as root on the host, the installer warns about the security risk and asks you to confirm. The default answer is no. In non-interactive mode, the installation stops after the warning. To install Infra on such a host anyway, add --allow-rootful:

deepfellow --non-interactive infra install --allow-rootful

To avoid the warning, run Docker in rootless mode.

Published Port

By default, DeepFellow Infra publishes its port, 8086, on all network interfaces of the host. Docker manages its own firewall rules for published ports, so a host firewall such as ufw doesn't block them. The installer warns you about it:

⚠️      DeepFellow Infra port is published on all network interfaces, and Docker bypasses host firewalls such as ufw. Set a bind address (e.g. 127.0.0.1) to restrict it.

To publish the port on one address only, pass --bind-address with an IPv4 or IPv6 address:

deepfellow infra install --bind-address 127.0.0.1

The installer stores the address in .env as DF_INFRA_BIND_ADDRESS and writes an IPv6 address in brackets, for example [::1]. A reinstall keeps the stored address. To publish the port on all interfaces again, pass --bind-address "". An empty value covers both IPv4 and IPv6. The installer also shows the warning for 0.0.0.0 and ::, but 0.0.0.0 publishes the port on IPv4 interfaces only.

With a bind address, the CLI reaches Infra at that address instead of localhost, for example in DF_INFRA_EXTERNAL_URL and in the address deepfellow infra start prints. DeepFellow Server reaches Infra over the Docker network, at http://infra:8086, so the bind address doesn't affect it.

To change the bind address of an existing install, set DF_INFRA_BIND_ADDRESS with deepfellow infra env set and confirm the restart it offers. The command checks the address and writes an IPv6 address in brackets. On an install made with an earlier CLI version, run deepfellow infra update first. See Published Ports.

After Installation

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

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 a Mesh by connecting your Infras in parent-child relations, forming a tree of instances.

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

The child Infra connects to the parent's published port. If the parent has a bind address, the child reaches the parent only through that address. For example, a parent on 127.0.0.1 accepts no children from other hosts.

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

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.

Envs

See Configuration for every variable DeepFellow Infra reads, with its config.json field and default value. See Environment Variables (CLI) to inspect and change them from the command line.

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).

Uninstall

See Uninstall to remove DeepFellow Infra.