DeepFellow Server

The deepfellow server group manages the DeepFellow Server installation running in Docker.

deepfellow server [OPTIONS] COMMAND [ARGS]...

deepfellow server Commands

Install Templates

--template accepts the built-in workspace name, or a path to your own YAML template file. A template has two parts: config pre-fills the install settings (fields it sets are applied without prompting), and post_start_actions runs after the server starts — use it to create the admin user automatically.

config:
  port: 8000
  infra_url: http://infra:8086
  # Omit this key if the API key is generated at infra install time and not known ahead of install.
  infra_api_key: your-infra-api-key
  docker_network: deepfellow-infra-net
  vectordb_type: milvus
  vectordb_url: http://milvus:19530
  vectordb_database_name: deepfellow
  embedding_model: mxbai-embed-large
  embedding_size: "1024"

# Runs after the server starts, in order.
post_start_actions:
  # Create the admin user. Leave name/email/password null to be prompted for them at install time.
  - function: server.create_admin
    kwargs:
      directory: "~/.deepfellow/server"
      name: null
      email: null
      password: null

Valid config keys:

• port
• infra_url
• infra_api_key
• docker_network
• vectordb_type
• vectordb_url
• vectordb_database_name
• embedding_model
• embedding_size

The only valid post_start_actions function is server.create_admin, whose kwargs must match the server create-admin command parameters. The built-in workspace template omits infra_api_key, since that key is generated at infra install time and is not knowable by a static template.

The built-in workspace template is equivalent to the example above: it sets the milvus vector database with the mxbai-embed-large embedding model (1024 dimensions) and runs a server.create_admin action that leaves name/email/password to be prompted for at install time. Under --non-interactive there is no prompt to fall back on, so a template that leaves them null is rejected before the install starts. A full copy of this example ships with the CLI source at deepfellow/server/templates/example.yaml.

deepfellow server env

Manage DeepFellow Server environment variables. For what each variable means and what it defaults to, read Configuration.

deepfellow server env [OPTIONS] COMMAND [ARGS]...

deepfellow server config

Manage Server's dynamic runtime configuration.

deepfellow server config [OPTIONS] COMMAND [ARGS]...

deepfellow server nightshift

Manage the Nightshift background worker. deepfellow server install and deepfellow suite install always provision the worker and its RabbitMQ queue, so this group has no install, enable, or disable command. To add the worker to an install without it, run deepfellow server update or deepfellow server install.

deepfellow server nightshift [OPTIONS] COMMAND [ARGS]...

Nightshift Operating Modes

The worker runs in one of two modes:

• always: the worker runs continuously, like the rest of the stack. This is the default.
• shift: the worker runs only between a start hour and a stop hour, in the host timezone. A window that crosses midnight, such as 22:00 to 06:00, is valid.

In shift mode, the CLI creates two user-level systemd timers, nightshift-start and nightshift-stop, in ~/.config/systemd/user/. Both timers run the same internal reconcile command. It compares the current time with the schedule, then starts or stops only the nightshift container if its state is wrong. RabbitMQ and the server keep running. If the host is off at a scheduled hour, the timer fires once at the next boot, and the command still leaves the worker in the right state.

The reconcile command waits up to 5 minutes for Docker, because a timer may fire before Docker is up after a boot. It never starts the worker while the server is stopped.

The timer names are the same for every install, so only one install per user can use shift mode. deepfellow server uninstall and deepfellow server prune leave the timers alone when they belong to another install.

Tasks queued outside the active hours wait in RabbitMQ until the next scheduled start.

To keep the timers running without a login session, and after a reboot, the CLI enables lingering for your user with loginctl enable-linger. The CLI skips this step when lingering is already enabled. On some hosts it requires root. If the plain command fails, the CLI asks to retry it with sudo, and sudo asks for your password. With --non-interactive, the CLI runs sudo -n, which fails instead of asking. If that fails too, run it yourself:

sudo loginctl enable-linger USERNAME

The CLI stores the mode and schedule in the server's .env file as DF_NIGHTSHIFT_MODE, DF_NIGHTSHIFT_START, and DF_NIGHTSHIFT_STOP. The systemd units are generated from these values. Change them with deepfellow server nightshift mode, deepfellow server nightshift schedule, or deepfellow server env set, not by editing .env.

An install created before Nightshift existed has no worker. For such an install, deepfellow server status, deepfellow server logs --nightshift, deepfellow server update, and the start, stop, restart, mode, and schedule commands print a hint to run deepfellow server install to add it.

deepfellow server organization

Manage organizations.

deepfellow server organization [OPTIONS] COMMAND [ARGS]...

deepfellow server project

Manage projects.

deepfellow server project [OPTIONS] COMMAND [ARGS]...

deepfellow server toolbox

Manage toolboxes. A toolbox is a project-scoped container for tools.

deepfellow server toolbox [OPTIONS] COMMAND [ARGS]...

deepfellow server tool

Manage tools within a toolbox. A tool always belongs to a toolbox: create the toolbox first, then add tools to it.

deepfellow server tool [OPTIONS] COMMAND [ARGS]...

A tool's definition is a JSON object with a type field, one of mcp, infra-mcp, custom-mcp, file_search, image_generation, or websearch. Each type takes a different set of fields; for example, an mcp tool takes server_label and server_url:

{
  "type": "mcp",
  "server_label": "git mcp",
  "server_url": "http://127.0.0.1:8001/mcp",
  "server_description": "Git operations over MCP"
}