Getting Started

Requirements

• macOS 13 or later (CI currently runs on macOS 15)
• Docker Desktop or OrbStack
• The Canopy app

Install and launch

1. Install Docker and start it.
2. Install and open Canopy.
3. Complete first-run setup:
   • Pick your preferred IDE and terminal.
   • Install the bundled canopy CLI when prompted if you want terminal workflows.
4. Make sure core services are running (nginx + PHP + databases). You can start them from the Services list.

You can also install or update the CLI later from Settings → Canopy CLI.

Create your first site

1. Choose File → New Site (Cmd+N).
2. Select your project folder (it can be anywhere on your machine).
3. Pick a template (Laravel, PHP, static, and more).
4. Choose a domain like my-app.test.
5. Save. Canopy generates the config, links the folder into its internal workspace when needed, updates your hosts file, and reloads nginx.

You may be prompted to approve Canopy’s privileged helper the first time it needs to update /etc/hosts.

Open your site

Visit http://my-app.test, or https://my-app.test if you turned on SSL. If SSL is enabled, you’ll be prompted once to trust the local certificate authority in Keychain.

If you already have a custom nginx config

Use File → Link Project (Shift+Cmd+N) to link an existing nginx.conf from your project root instead of generating one.

Next steps

• Learn the Core Concepts
• Manage sites with Creating & Managing Sites
• Explore shared services in Services & Ports