README.md

July 30, 2026 · View on GitHub

Pilot

Manage Frappe benches and sites on any server

Pilot makes it simple to run Frappe on your own servers. Use the Admin UI to manage apps, sites, processes, backups, domains, and production setup, with a CLI for automation.

Apps

Key Features

Bench and site lifecycle: create, update, rename, restore, back up, and drop
Integrated marketplace to install apps on sites from Git repositories or the app registry
Local development runner for Redis, web, workers, socket.io, and Admin UI
Production setup for process managers, nginx, monitoring, domains, and TLS
Devtools for investigation: SQL playground, database analyzer, binlog browser, logs, and task history

Requirements

Debian 12+, Ubuntu 22.04+, Fedora 40+, Arch Linux, or macOS with Homebrew for local development
Python 3.11+

Installation

Run the installer as your normal user:

curl -fsSL https://raw.githubusercontent.com/frappe/pilot/develop/install.sh | bash

On a root-only VPS, run it as root; the installer creates a non-root bench user.

This installs the latest release (prebuilt admin UI, no build step). Contributors who want a source checkout that compiles the admin UI locally can pass --dev:

curl -fsSL https://raw.githubusercontent.com/frappe/pilot/develop/install.sh | bash -s -- --dev

Basic Usage

Create a bench and launch the setup wizard:

pilot new dev-bench
pilot -b dev-bench start

The first start will print the url to access the admin wizard. The wizard asks for the Admin password, database settings, and Frappe source settings, then initializes the bench with live task progress.

Common commands:

Command	Purpose
`pilot new <name>`	Create a bench and `bench.toml`
`pilot ls`	List benches, status, production state, and Admin URL
`pilot -b <name> init`	Initialize a bench from `bench.toml`
`pilot -b <name> start`	Start development processes
`pilot -b <name> stop`	Stop development processes
`pilot -b <name> get-app <repo>`	Clone and install an app
`pilot -b <name> new-site <site>`	Create a site
`pilot -b <name> update`	Pull apps, install deps, build assets, and migrate sites
`pilot -b <name> setup production`	Configure process manager, nginx, Admin domain, and optional TLS
`pilot -b <name> restart`	Restart production processes
`pilot -b <name> remove production`	Remove production deployment files and services

For the full command list, see Commands.

Configuration

Each bench has one bench.toml. It is the source of truth for apps, database, Redis, workers, production, nginx, gunicorn, Let's Encrypt, Admin, firewall, WAF, S3, and monitoring settings.

Minimal shape:

[bench]
name = "main"
python = "3.11"

[[apps]]
name = "frappe"
repo = "https://github.com/frappe/frappe"
branch = "version-16"

[mariadb]
host = "localhost"
port = 3306
root_password = "your-root-password"

[redis]
cache_port = 13000
queue_port = 11000

[[workers]]
queues = ["default", "short", "long"]
count = 1

[admin]
port = 8002
password = "your-admin-password"
domain = ""
tls = false

Apps and sites also exist on disk under the bench. See Configuration for every config section.

Production

Production setup writes process-manager config, nginx integration, Admin routing, monitoring config, and optional Let's Encrypt certificates.

pilot -b main setup production --admin-domain admin.example.com
pilot -b main setup production --admin-domain admin.example.com --tls --letsencrypt-email ops@example.com

The Admin domain is required in production. Set admin.tls = false when HTTPS terminates at an upstream proxy.

Supported process managers:

systemd
supervisor
none for local development

See Production.

Admin UI

The Admin UI runs on [admin] port, usually 8002. It exposes bench status, apps, marketplace installs, sites, backups, domains, processes, logs, tasks, database tools, updates, and settings.

Long-running Admin operations return task IDs. Task progress, logs, callbacks, and final status are handled by pilot.tasks.

See Admin UI and Admin API.

Guides

Development

Development setup and checks

Use a source checkout when working on Pilot:

git clone https://github.com/frappe/pilot ~/pilot
cd ~/pilot
export PATH="$PWD/bin:$PATH"

Create a development bench:

pilot new dev
pilot -b dev start

Useful development toggles in bench.toml:

[bench]
watch_apps_js = true
reload_python = true
watch_admin_js = true

Run checks:

uv run ruff check admin pilot tests
uv run pytest tests/ --ignore=tests/integration

Integration tests under tests/integration/ use real services and run the full bench lifecycle.

Community

Contributing

Keep CLI commands and Admin API routes thin. Put behavior on the closest core object: Server, Bench, Site, App, or a task.

Read SPEC.md, Architecture, and Commands before changing behavior.

Security

The Frappe team and community prioritize security. If you discover a security issue, please report it via our Security Report Form. Your responsible disclosure helps keep Frappe and its users safe. We'll do our best to respond quickly and keep you informed throughout the process. For guidelines on reporting, check out our Reporting Guidelines, and review our Logo and Trademark Policy for branding information.