AbdelftahZowail/Quickly installation guide

Install Quickly on macOS Tahoe (Apple silicon)

What you are installing

Quickly is an MIT-licensed, self-hosted cold-email application. It combines a React/Vite interface, a Python/FastAPI backend, PostgreSQL, and background scheduling. It can connect Gmail, Microsoft 365/Outlook, and generic SMTP senders, and it includes campaign sequencing, reply handling, analytics, webhooks, REST APIs, and optional AI reply classification.

For a Mac, the repository’s clearest supported path is its **Docker development stack**. The project describes this as the fastest local setup and says it provides hot reload for both frontend and backend development. This guide therefore installs a local testing/development instance, available at `http://localhost:5173`. A laptop-hosted local instance is not the repository’s documented production deployment path; Railway or a Linux VPS is documented for a public deployment.

Relationship to Claude Code: **unclassified**

The supplied files do not document a Claude Code plugin, skill, hook, command, configuration path, or tested Claude Code integration. Quickly is principally a standalone application. It does expose an MCP-over-HTTPS endpoint at `/api/mcp` for leads tools and mentions `mcp-remote` with Cursor or other clients, but the supplied MCP guide was not included and no Claude Code setup is evidenced. Its optional Anthropic provider is for classifying email replies, not for extending Claude Code. Consequently, its Claude Code mechanism should remain **unclassified** rather than inferring native compatibility.

Before you begin

You need:

• An Apple-silicon Mac running macOS Tahoe.
• Git, so you can clone the public repository.
• A working Docker installation with Docker Engine and the Docker Compose plugin.
• Free local ports `5173` and `8000` for the documented development stack.
• Google or Microsoft OAuth credentials if you want to connect those inbox types.

The repository links to Docker’s official installation documentation but does not provide a macOS-specific Docker installation command or an Apple-silicon compatibility matrix. Install Docker through Docker’s first-party macOS instructions, then start the Docker application and wait until its engine is running. Do not use the Linux-only quick-install shell command from the VPS section on macOS.

The supplied files also do not state that the published images were explicitly tested on macOS Tahoe or Apple silicon. Docker may report an architecture issue if an image required by the stack is unavailable for your Mac; the repository does not document a workaround, so report that upstream rather than applying an undocumented emulation change.

1. Open Terminal

Open **Terminal** from Applications → Utilities. Commands below may be pasted one block at a time. Keep Terminal open while the local stack runs.

Choose a parent folder in which you are comfortable creating a new `quickly` directory. The clone command itself creates that directory.

2. Download the repository

Run the exact local-development commands documented by the project:

git clone https://github.com/azowail/quickly.git
cd quickly
cp .env.example .env

This downloads the source, enters its directory, and copies the provided environment template to `.env`. Although the supplied GitHub metadata names `AbdelftahZowail/Quickly`, the project’s own installation guide documents the shorter `azowail/quickly` clone URL above.

3. Configure the local URL

Open the newly created `.env` file in a plain-text editor. Find `BASE_URL` and set it to the value required by the repository’s Docker development instructions:

BASE_URL=http://localhost:8000

Do not add quotation marks or a trailing slash unless the existing template specifically requires them.

For a stable signing secret, the installation guide recommends setting `QUICKLY_SECRET_KEY`; otherwise, a new key can be generated at restart and existing login sessions become invalid. If your Mac already has a working `python` command, the repository documents this generator:

python -c "import secrets; print(secrets.token_urlsafe(64))"

Copy the printed value into `.env` as the value of `QUICKLY_SECRET_KEY`. Treat it like a password and do not commit or share `.env`.

A separate source file warns that sensitive columns—including SMTP and IMAP passwords—fall back to plaintext when `QUICKLY_ENCRYPTION_KEY` is absent. However, the supplied installation guide does not document that variable’s production configuration lifecycle. Before storing real mailbox credentials in a production instance, review that limitation and obtain project-supported guidance; do not assume the local development defaults provide encrypted credential storage.

You may leave Gmail and Microsoft variables empty for an initial interface test. They are needed when you connect those account types:

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
OFFICE365_CLIENT_ID=
OFFICE365_CLIENT_SECRET=
OFFICE365_TENANT_ID=common

Save `.env` as plain text in the repository root.

4. Start Quickly

With Terminal still inside the `quickly` folder and Docker running, start the documented development stack:

docker compose -f docker-compose.dev.yml up

Leave this Terminal window open. The first run can take longer because Docker must obtain and prepare the required images. The repository says this stack provides frontend and backend hot reload.

When startup output settles without an error, open this address in Safari or another browser:

• `http://localhost:5173` — Quickly’s development interface
• `http://localhost:8000` — backend/API address used by the local configuration

Use `http`, not `https`, for these documented localhost URLs.

5. Create the first account

The supplied first-party files differ slightly here: the main README says the first visit shows a registration form and registration closes after the initial admin is created, while the detailed installation guide describes registration through Google or Microsoft sign-in.

Open the interface and follow the registration option actually shown:

1. Create the initial administrator account.
2. Store its credentials securely.
3. Remember that later users must be invited by an administrator if registration closes after the first account.

If the interface requires Google or Microsoft sign-in, configure that provider first. Do not invent OAuth callback URLs: use the callback paths displayed by Quickly and the repository’s provider instructions, ensuring they match the `BASE_URL` used by your deployment.

6. Optional inbox setup

Gmail

In Google Cloud Console, create a project, enable **Gmail API** and **Cloud Pub/Sub API**, and create a Web application OAuth client. Put its client ID and secret into `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` in `.env`. The repository requires the Gmail scope `https://mail.google.com/` and says testing-mode accounts must be added as test users.

After changing `.env`, the documented container restart command is:

docker compose up -d

Then use **Inboxes → Add Inbox → Connect Gmail Account**. Pub/Sub push setup is optional; scheduled polling can be used instead.

Microsoft 365 or Outlook

Register an application in Microsoft Entra/Azure and add delegated Microsoft Graph permissions `Mail.ReadWrite`, `Mail.Send`, `User.Read`, and `offline_access`. Create a client secret, then place the application ID, secret value, and tenant selection into the corresponding `OFFICE365_...` variables. `common` is documented for multi-tenant use.

Restart with the same documented command:

docker compose up -d

Then choose **Inboxes → Add Inbox → Connect Office 365 Account**.

Generic SMTP is also supported. Amazon SES is documented as send-only unless replies are routed to a separately connected mailbox.

7. Confirm the services

For the standard Compose layout, the project documents these diagnostics:

docker compose ps

docker compose logs app

Use them if the page is unavailable. Confirm that `.env` exists and that `BASE_URL` is exactly `http://localhost:8000`. Also confirm Docker is still running and no other application occupies the documented ports.

Because you started with `docker-compose.dev.yml`, keep the original foreground Terminal visible as your primary source of development-stack errors. The supplied documentation does not provide a macOS-specific repair command for image-architecture, port, or Docker engine failures.

8. First safe test

From the interface, create a campaign, assign a connected inbox, add a sequence step, and import a CSV containing at least an `email` column. Additional columns become template variables such as `{{name}}` or `{{company}}`.

Before sending real mail, use the application’s documented **test mode** and review inbox limits, sending windows, warm-up settings, tracking behavior, and applicable consent and anti-spam requirements. The software can send real email through connected accounts; installation alone does not make a campaign lawful or appropriate.

What success looks like

Installation is complete when the Docker development stack stays running, `http://localhost:5173` opens, you can create the initial administrator, and the interface reaches its campaign and settings pages. OAuth, SMTP, AI classification, MCP, n8n, public HTTPS, and custom tracking are optional integrations—not prerequisites for confirming the local installation.