Skip to content
Pywa Cloud is not live yet - there is no running control plane or dashboard to sign up on, and the CLI package is not published. Everything on this site describes a real, working, tested system, not a roadmap - but none of it is something you can actually run against Pywa Cloud today, and commands/flags/behavior can still change before it is.

Local Development

Only a bot in development can be tunnelled (new bots start there); promoting a bot to production (in the dashboard) moves it out of development, where the tunnel is refused. See CLI reference.

Normally, developing against real WhatsApp webhooks means running a separate tunnel tool (ngrok or similar) and manually repointing the callback URL in the Meta App dashboard for every session - then pointing it back at your deployed bot afterward. Pywa Cloud’s tunnel does this without either step: your bot already has one stable public webhook URL (https://ingress.pywa.cloud/webhook/<bot-id> - your bot’s opaque id - registered once when you connect a WhatsApp number) - the tunnel just changes where Pywa Cloud forwards traffic arriving at that URL, from your deployed bot to your own machine. The URL registered with Meta never has to change between local development and production.

pywa dev --tunnel goes one step further than a plain relay, too: it fetches this bot’s real, live PYWA_TOKEN/PYWA_PHONE_ID/PYWA_WABA_ID and injects them into your local process’s environment before starting - the same values your deployed bot has, not a foreign override. It also injects every variable and secret set with pywa cloud env, except where your shell or .env already sets one - your local value wins there, so you can point DATABASE_URL at a local database. (Needs the admin role on the bot’s team, like the tunnel itself.)

Because this sends live customer messages to your machine and runs your code with the bot’s real token, pywa dev --tunnel says so and asks for a yes first (a script with no terminal is told and goes ahead). Opening a tunnel and fetching the environment are both recorded in the team’s audit log, and a tunnel ends within about 30 seconds of its token being revoked or your admin role being removed. Without them your local bot would receive real webhooks but be unable to send replies at all, so there’s no real use case for tunneling without them. (If your bot has no WhatsApp number connected yet, this fails fast with a clear error - connect one first.) This is unconditional, not opt-in - anything your project’s own .env or hardcoded values set for the three WhatsApp names is overwritten by the real ones. The standalone pywa cloud tunnel below is different: it’s a byte- level relay with no server of its own to inject into, so it doesn’t do this - your local process keeps running against whatever credentials it already had.

The recommended way is pywa dev --tunnel (pywa’s own local dev server, with the tunnel and credential injection wired in), from the linked project directory (or with --bot <bot-id>):

Terminal window
pywa dev --tunnel # runs your bot locally, injects its real WhatsApp credentials, and relays
# this bot's webhook traffic here
Injected live WhatsApp credentials: PYWA_PHONE_ID, PYWA_TOKEN, PYWA_WABA_ID.
Injected env vars from Pywa Cloud: OPENAI_KEY.
🚀 Starting Pywa in development mode
🌐 Server URL: http://127.0.0.1:8000
Tunneling 'my-bot''s webhook traffic to http://127.0.0.1:8000 ...

--tunnel picks up --host/--port/--bot the same way the rest of pywa dev does - --bot <bot-id> if the directory isn’t linked to one already.

Standalone tunnel — relay only, no credential injection

Section titled “Standalone tunnel — relay only, no credential injection”

If you’re not using pywa dev - a different framework runner, or you’d rather run your bot and the tunnel as two separate steps - run your bot locally first, exactly as you would with any other Python HTTP server, providing its PYWA_TOKEN/PYWA_PHONE_ID/etc. yourself however you normally would for a local run (a .env file, hardcoded values, pywa cloud env list copied by hand - pywa cloud tunnel itself won’t fetch these for you, unlike pywa dev --tunnel above):

Terminal window
python main.py # or however you normally run it - note the port it's listening on

Then, from the linked project directory (or with --bot <bot-id>):

Terminal window
pywa cloud tunnel --port 8000 # the port your bot above is listening on
Tunneling 'my-bot''s webhook traffic to http://127.0.0.1:8000 ...
Press Ctrl+C to stop and hand control back to the deployed container.
Connected - forwarding webhook traffic to http://127.0.0.1:8000
POST /webhook -> 200

From this point, every webhook Meta sends for this bot arrives at your local process instead of the deployed one - signature-validated exactly the same way it would be in production (validation happens once, before Pywa Cloud decides where to send the request - what changes is only where an already-validated request goes). Ctrl+C (or closing your laptop, losing WiFi, anything that drops the connection) immediately hands control back to your deployed bot - nothing about your bot’s deployment or its Meta configuration needs to change either way, and your deployed bot is never stopped while a tunnel is connected, only temporarily not receiving traffic.

  • Opt-in, not automatic. The tunnel is only active while pywa dev --tunnel/pywa cloud tunnel is actually running - starting your bot locally on its own (plain pywa dev, or python main.py) doesn’t reroute anything.
  • One tunnel per bot at a time. Starting another tunnel for the same bot (e.g. a teammate starts one while yours is still connected) takes over - your own connection is closed with a clear reason, not silently starved of traffic with no explanation.
  • Visible from the dashboard too. The Overview tab shows a “Local tunnel active” badge with how long it’s been connected, whenever one is - useful for a teammate wondering why the deployed version isn’t seeing traffic it should be, without needing terminal access to whoever’s tunneling.
  • No request buffering across a reconnect. A dropped connection doesn’t queue up in-flight webhook deliveries to replay once you’re back - Meta already retries failed webhook deliveries, which is a simpler and more robust safety net than building that here.
  • This is a webhook relay, not a general tunnel. It doesn’t expose anything beyond the webhook path, and doesn’t replace pywa cloud logs or any other existing command.