DeepFellow Workspace

What is DeepFellow Workspace?Copy Anchor Link

DeepFellow Workspace is a private, source-grounded AI tool designed to help you work with your own documents and knowledge resources.

Source-grounded means that DeepFellow Workspace generates responses based on the knowledge sources you upload. Private means that the tool runs on your own infrastructure, ensuring that your uploaded content is never shared with or exposed to third parties.

Use DeepFellow Workspace to analyze research materials, query technical documentation, or interact with any documents you need. Content is organized into Knowledge Bases with intuitive access controls, giving you precise oversight over who can access what.

DeepFellow Workspace is an application that works on top of a DeepFellow Server project. The installer sets it up in Docker together with its own MongoDB and Redis.

RequirementsCopy Anchor Link

Before you install DeepFellow Workspace, prepare:

• Docker engine on the host
• A running DeepFellow Server that the DeepFellow Workspace container can reach. When both run in Docker on the same host, they share the deepfellow-infra-net network
• An API key of the DeepFellow Server project that DeepFellow Workspace will use
• A small model served by DeepFellow Server, for background tasks such as session titles and summaries of long conversations. The default is gemma4:e4b

InstallationCopy Anchor Link

deepfellow workspace install

❓      DeepFellow Server URL:
❓      DeepFellow Server project API key:

❓      Small model name served by DeepFellow Server (gemma4:e4b):

❓      Address Workspace is opened at in the browser (http://localhost:3000):

❓      Install a local MongoDB for DeepFellow Workspace? [y/n] (y):
❓      Install a local Redis for DeepFellow Workspace? [y/n] (y):

❓      MongoDB connection URL (a replica set is required):
❓      Redis URL:

❓      Create an initial admin account? [y/n] (y):

❓      Configure sending e-mails (SMTP)? [y/n] (n):

When the installation finishes, the installer prints the address of DeepFellow Workspace. By default, it is http://localhost:3000. The /mcp endpoint requires the bearer token MCP_AUTH_TOKEN from ~/.deepfellow/workspace/.env; give it to your MCP clients. If you created an admin account, its password stays in .env: once you have logged in, remove the three BOOTSTRAP_ADMIN_* lines from it.

With the --yes flag, the installer does not ask for the address and uses the default. The --yes flag does not answer the questions about MongoDB, Redis, the admin account, and SMTP. To skip them, pass the matching flags. See DeepFellow Workspace CLI Reference for all flags.

Non-Interactive InstallationCopy Anchor Link

To install without any question, pass the values as flags or environment variables and add --non-interactive:

deepfellow --non-interactive workspace install \
  --df-server-url http://server:8000/v1 \
  --df-server-api-key YOUR_API_KEY

In this mode, the installer uses defaults for everything else, including the http://localhost:3000 address, and installs a local MongoDB and Redis. It creates no admin account and does not configure email, unless you pass the matching flags. If DeepFellow Server does not offer gemma4:e4b, pass --small-model; otherwise the installation fails.

HTTPS Behind a Reverse ProxyCopy Anchor Link

To open DeepFellow Workspace at an https:// address, put it behind a reverse proxy that terminates TLS and forwards the requests to the DeepFellow Workspace port. The installer does not set up the reverse proxy.

Give the https:// address of the reverse proxy as the Workspace address:

deepfellow workspace install --public-url https://workspace.example.com

For an https:// address, the installer:

• Enables --trusted-proxy, so DeepFellow Workspace trusts the X-Forwarded-For and X-Real-IP headers that the reverse proxy sets. To keep it disabled, pass --no-trusted-proxy.
• Asks for other origins that DeepFellow Workspace trusts, for example another host name of the reverse proxy.

The question about other origins looks like this:

❓      Other trusted origins, comma-separated (optional):

Press Enter to add none. To skip the question, pass the origins with --trusted-origins:

deepfellow workspace install --public-url https://workspace.example.com \
  --trusted-origins https://ws.example.com,https://workspace.example.com:8443

ReinstallCopy Anchor Link

If the ~/.deepfellow/workspace directory already exists, for example after an uninstall, the installer asks whether to reinstall over it. A reinstall keeps the generated secrets, the stored data, and the image, port, bind address, Docker network, and trusted origins, and asks no questions about the optional settings. It asks for the Workspace address again, with the previous address as the default. If the previous installation ran with --no-trusted-proxy, a reinstall keeps it disabled. To change a setting, pass its flag. To go back from an external MongoDB or Redis to the local one, pass --local-mongodb or --local-redis. To stop sending emails, pass --no-smtp.

To skip the question, pass --force-install.

UninstallCopy Anchor Link

To remove the DeepFellow Workspace containers, run:

deepfellow workspace uninstall

The MongoDB data, compose.yaml, and .env stay in place. See Uninstall.

To remove DeepFellow Workspace together with its data, run:

deepfellow workspace prune

The command deletes the containers, the MongoDB and Redis volumes, and the installation directory with .env, and removes the DeepFellow Server webhook endpoint of DeepFellow Workspace. You cannot restore the data. See DeepFellow Workspace CLI Reference.