Farna Control
Read-only demoInstall

Installation

The supported way to run Farna Control is Docker Compose, on Docker Desktop or a Docker Engine on Linux. The native installers for Linux and macOS are available with the alpha. See Platform support for the full matrix.

Platform support

Farna Control v1 targets Linux server hosts, with native installers for Linux and macOS where release artifacts are published. This is the supported platform matrix, mirroring the product’s system requirements. For the quick answer, see What infrastructure does Farna Control need?.

Server host platforms

Server host platforms
Server host platform v1 status
Linux Supported (native install and container paths)
macOS Native installer available for Apple Silicon (arm64) as a signed and notarized .dmg; Intel (x86_64) support is forward-looking until that release artifact is published.
Windows Beta scope, opt-in only. The native installer is built, signed, and attested when the Beta-only Windows input is enabled, but no signed Windows installer is published yet, and real-host validation is still outstanding.

Docker Desktop on macOS or Windows is a developer convenience: it runs the Linux containers inside a Linux virtual machine, so the deployed stack is still Linux. It is not a supported production host.

Windows native support is in Beta scope and is opt-in only. Until a signed Windows installer is published, a Windows-hosted deployment means Windows Server running the Linux Docker stack in a VM or container host.

Docker Compose

The Docker Compose path is distribution-agnostic, apart from its Docker requirement: any Linux distribution that can run Docker 24+ (Docker Engine or Docker Desktop) and Docker Compose v2.20+ works, at any glibc version, because the PostgreSQL, Redis, API, frontend, and worker containers carry their own dependencies.

Native install: distributions

The native installers cover Linux and macOS. On Linux, the bundle ships its own PostgreSQL 16, Redis 8, and Python runtime, so the host requirement is the bundled service binaries’ glibc floor:

Native install: distributions
Distribution glibc Status
Ubuntu 22.04 LTS and newer 2.35+ Supported
Debian 12 and newer 2.36+ Supported
Ubuntu 20.04 and earlier 2.31 and below Not supported (below the bundled service-binary floor)
macOS (Apple Silicon) - Supported native .dmg; Rosetta is not required
Windows - Beta scope, opt-in only; native installer not yet published

The hard requirement is glibc 2.35 or newer. The bundle is built on an Ubuntu 22.04 (jammy) baseline, so it covers every currently supported Ubuntu LTS release (22.04 and 24.04) and Debian 12 or newer. Ubuntu 20.04 (glibc 2.31) and older are below the floor and are not supported native-install targets.

Native install: architectures

Native install: architectures
Architecture Status
linux-amd64 (x86_64) Supported
linux-arm64 Planned (pins exist; no artifact published yet)
macOS arm64 Supported native .dmg (Modulo-<version>-macos-arm64.dmg), Apple Silicon
macOS x86_64 Forward-looking; no artifact in the current release
Windows Beta scope, opt-in only; native installer not yet published

The Linux native bundle is currently built and published for linux-amd64 only. There is no linux-arm64 download yet.

Prerequisites

  • Docker 24+ (Engine or Desktop) and Docker Compose v2.20+
  • 4 GB RAM minimum (8 GB recommended)

Quick start

The default docker-compose.yml starts everything in one command: PostgreSQL 16, Redis 8, the API, the frontend, and the queue workers. The first run builds the Docker images, which takes several minutes; subsequent starts are fast.

git clone https://github.com/farnalabs/modulo
cd Farna Control
docker compose up -d

Open http://localhost:5173 and log in with admin:admin. These are development credentials: change them before exposing the instance beyond local use. The backend runs database migrations automatically on first start.

Development setup

For local development with hot-reload, use the development Compose file and start the API and frontend separately:

Development prerequisites

  • Python 3.12+ and uv (or pip)
  • A GitHub account (for GitHub connector setup)

Steps

Start the database and queue services first:

git clone https://github.com/farnalabs/modulo
cd Farna Control

# Start PostgreSQL 16, Redis 8, and the queue workers
docker compose -f docker-compose.local.yml up -d

Generate the two secret keys. SECRET_KEY must be at least 32 bytes (known placeholder values are rejected at startup), and FERNET_KEY must be a valid Fernet key, so do not invent values by hand:

python3 -c "import secrets; print(secrets.token_hex(32))"  # SECRET_KEY
python3 -c "import base64, os; print(base64.urlsafe_b64encode(os.urandom(32)).decode())"  # FERNET_KEY

Both commands use only the Python standard library, so they run before the backend dependencies are installed. python3 is the interpreter name on Debian and Ubuntu; use python on a system that only provides that name.

Create a .env file in the backend/ directory and paste the generated outputs:

DATABASE_URL=postgresql+asyncpg://modulo:changeme@localhost:5434/modulo
# The development Compose file publishes Redis on port 6380
REDIS_URL=redis://localhost:6380/0
# Paste the SECRET_KEY output from the generator above
SECRET_KEY=paste-generated-key-here
# Paste the FERNET_KEY output from the generator above
FERNET_KEY=paste-generated-key-here
# Local development login only. Use a strong password outside local development.
MODULO_USERS=admin:admin
# CORS (Cross-Origin Resource Sharing): comma-separated allowed origins
CORS_ORIGINS=http://localhost:5173

Run migrations and start the API:

cd backend
uv run alembic upgrade heads
uv run uvicorn modulo.api.main:app --reload --port 8000

In another terminal, start the frontend:

cd frontend
npm run dev

Open http://localhost:5173 and log in with admin:admin.

Native install (Linux and macOS)

Farna Control has native installers for Linux and macOS, available with the alpha. They install without Docker.

On macOS, the current native installer is a signed and notarized .dmg for Apple Silicon: Modulo-<version>-macos-arm64.dmg. Intel support is forward-looking until an x86_64 artifact is published. Rosetta is not required for the Apple Silicon build, and the installer checks that the app matches the host architecture, so renaming a .dmg does not work. Download it from the releases page. The installer verifies the disk image with hdiutil verify and checks the Apple Developer ID signature and notarization. As on Linux, Docker Compose remains the supported production path.

On Linux, run the installer:

curl -fsSL https://raw.githubusercontent.com/farnalabs/modulo/main/scripts/install.sh -o modulo-install.sh
bash modulo-install.sh

Download the script to a file and run it rather than piping it straight into a shell. The installer verifies every download’s sha256 before executing anything, and a streamed install skips that verification.

The installer:

  • Downloads the release bundle for your architecture from GitHub Releases and verifies it
  • Installs a bundled stack: PostgreSQL 16, Redis 8, and a bundled Python runtime (no Docker or system Python needed)
  • Installs everything under your home directory and puts modulo on your PATH

modulo start runs everything: PostgreSQL, Redis, the API, and the queue workers. On systemd hosts, an optional systemd user unit manages it.

Which install to pick:

Native install (Linux and macOS)
Install Use for
Docker Compose Servers and production deployments
Native install Workstations and evaluation
Kubernetes (Helm) Teams running Farna Control on a cluster they control

To run the whole stack on a Kubernetes cluster, use the Helm chart: see the Kubernetes guide for prerequisites, the values to set, and notes for Amazon Elastic Kubernetes Service (EKS), Azure Kubernetes Service (AKS), Google Kubernetes Engine (GKE), and any other conformant cluster.

The full native install, upgrade, and backup/restore documentation lives in the deployment docs.

Install with your own agent

This is a secondary trial and evaluation path, not the primary supported production path. Docker Compose and the native installers remain the supported methods. The goal is a verified-running Farna Control instance on infrastructure you control; this path does not promise a first pipeline, autonomous deployment, vendor parity, or a hosted Farna Control service.

Claude Code plugin install

Farna Control’s public Claude Code plugin is installed from the public repository. This uses Claude Code’s third-party repository marketplace; it is not Anthropic’s official Claude Marketplace directory. In Claude Code, use the marketplace commands below:

/plugin marketplace add farnalabs/modulo
/plugin install modulo@modulo

The plugin provides the /modulo command and its /modulo:install install skill. These are the plugin’s Claude Code commands; a compatible coding agent should instead read the canonical public installation guidance and the Agent Skills content in the Farna Control repository, then follow it exactly.

Do not ask users to paste credentials into an agent prompt. The agent must never store secrets in .modulo/context.md. If .modulo/context.md or ~/.modulo/context.md is present, it is advisory context only; live verification of the user’s instance wins.

Remote MCP comes after installation

The Remote MCP entry is intentionally inert until the user has a running self-hosted instance and a canonical hostname. Configure it only after that instance is live and its hostname is known. The website does not provide a hosted Farna Control endpoint, and this interface does not promise that every agent vendor exposes identical capabilities.

Codex and other plain agents may be compatible through the same public Agent Skills content. Use the canonical repository and installation documentation as the source of truth rather than assuming a vendor-specific workflow.

Next: Architecture