Quick Start

This walks through the whole loop as it exists today: run a control plane on your own machine, install the CLI, and deploy a real pywa project to a real container.

Note

There’s no hosted Pywa Cloud to point at yet — you run the control plane yourself. See Deploying a Pywa Bot for what’s still ahead of a hosted version.

Prerequisites

• Python 3.12+ and Docker, for running the control plane (it builds and runs your bot’s container directly — see Deploying a Pywa Bot for why).
• Python 3.10+ for the CLI.

1. Run a control plane

git clone <this-repo> && cd pywa-cloud/control-plane
python3 -m venv .venv && .venv/bin/pip install -e .
PYWA_CLOUD_API_TOKEN=devtoken .venv/bin/uvicorn control_plane.main:app --reload

Pick any value for PYWA_CLOUD_API_TOKEN — it’s the single shared credential this early version uses instead of real accounts (see CLI Reference for what that means today).

2. Install the CLI

cd ../cli
python3 -m venv .venv && .venv/bin/pip install -e .

3. Log in

.venv/bin/pywa login --token devtoken --api-url http://127.0.0.1:8000

(.venv/bin/pywa exists because pywa-cloud-cli depends on pywa[server] directly - installing the CLI in step 2 pulled pywa in too, and its own CLI auto-mounts pywa cloud ... whenever both packages are present.)

4. Create a bot

.venv/bin/pywa cloud bots create "My Bot" --slug my-bot

5. Scaffold a project

.venv/bin/pywa new --cloud -o my-bot

Writes a deployable pywa project into my-bot/: main.py reading every secret from the environment (never hardcoded), plus a real pyproject.toml declaring pywa[server] — see Deploying a Pywa Bot for the exact project shape this matches. (Plain pywa new, without --cloud, is pywa’s own default scaffold instead — hardcoded placeholder credentials and a local ngrok tunnel, meant for local editing, not deploying as-is.)

6. Deploy

.venv/bin/pywa deploy my-bot --bot my-bot

The first deploy links the directory to the bot (writes my-bot/.pywacloud/link.json), so every deploy after this one just needs:

.venv/bin/pywa deploy my-bot

A successful deploy prints the local URL your bot’s container is now listening on.

Next steps

• Deploying a Pywa Bot — what actually happens on deploy, and what’s still a simplification.
• Environment Variables & Secrets — get your bot’s real WhatsApp token and phone ID into the container.
• Logs — see what your bot is actually printing.