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.
- 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
- Debian 12+, Ubuntu 22.04+, Fedora 40+, Arch Linux, or macOS with Homebrew for local development
- Python 3.11+
Run the installer as your normal user:
curl -fsSL https://raw.githubusercontent.com/frappe/pilot/main/install.sh | bashOn a root-only VPS, run it as root; the installer creates a non-root bench user.
Create a bench and launch the setup wizard:
bench new dev-bench
bench -b dev-bench startThe 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 |
|---|---|
bench new <name> |
Create a bench and bench.toml |
bench ls |
List benches, status, production state, and Admin URL |
bench -b <name> init |
Initialize a bench from bench.toml |
bench -b <name> start |
Start development processes |
bench -b <name> stop |
Stop development processes |
bench -b <name> get-app <repo> |
Clone and install an app |
bench -b <name> new-site <site> |
Create a site |
bench -b <name> update |
Pull apps, install deps, build assets, and migrate sites |
bench -b <name> setup production |
Configure process manager, nginx, Admin domain, and optional TLS |
bench -b <name> restart |
Restart production processes |
bench -b <name> remove production |
Remove production deployment files and services |
For the full command list, see Commands.
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 = falseApps and sites also exist on disk under the bench. See Configuration for every config section.
Production setup writes process-manager config, nginx integration, Admin routing, monitoring config, and optional Let's Encrypt certificates.
bench -b main setup production --admin-domain admin.example.com
bench -b main setup production --admin-domain admin.example.com --tls --letsencrypt-email ops@example.comThe Admin domain is required in production. Set admin.tls = false when HTTPS terminates at an upstream proxy.
Supported process managers:
systemdsupervisornonefor local development
See Production.
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.
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:$PATH"Create a development bench:
bench new dev
bench -b dev startUseful development toggles in bench.toml:
[bench]
watch_apps_js = true
reload_python = true
watch_admin_js = trueRun checks:
uv run ruff check admin pilot tests
uv run pytest tests/ --ignore=tests/integrationIntegration tests under tests/integration/ use real services and run the full bench lifecycle.
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.
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.
