Flask

Install + wire

from flask import Flask
from z4j_flask import Z4J

z4j = Z4J()

def create_app():
    app = Flask(__name__)
    app.config.from_object("myapp.config.Config")

    z4j.init_app(app, {
        "brain_url": app.config["Z4J_BRAIN_URL"],
        "token":     app.config["Z4J_TOKEN"],
        "project_id": app.config.get("Z4J_PROJECT_ID", "default"),
    })
    return app

Or the one-shot form:

Z4J(app, {...config...})

Lifecycle

Flask’s application context doesn’t have a natural “startup” hook. z4j-flask uses app.before_request (first-request) to start the agent. This is fine for web processes; for worker processes, call z4j.start() manually in your worker boot.

from myapp import create_app
from z4j_flask import z4j

app = create_app()
z4j.start(app)   # or place inside `with app.app_context():`

# ... RQ worker loop ...

Multi-process

Same as Django: each worker is its own agent. Set agent_name to include the role:

import socket, os
z4j.init_app(app, {..., "agent_name": f"web-{socket.gethostname()}-{os.getpid()}"})

Config keys

See Django for the full Z4J config dict - the keys are identical.

Blueprints

z4j does not register any Flask blueprints. It attaches as pure background behavior - your URL space is untouched.

CLI (`flask ...`)

Management commands don’t start the agent unless you explicitly call z4j.start(app).

Verify with doctor

python -m z4j_flask doctor runs the same probes the agent runtime does (buffer dir writable, brain DNS / TCP / TLS, WebSocket upgrade) using the Z4J_* env vars your service is configured with.

# Always run as the same user the service runs under.
sudo -u www-data /srv/app/venv/bin/python -m z4j_flask doctor

# Skip the WS round-trip when the brain is intentionally offline:
python -m z4j_flask doctor --no-websocket

# Machine-readable for scripting:
python -m z4j_flask doctor --json

Exits 0 on all-green, 1 on any failure. Catches the gunicorn-under-www-data silent startup failure, NAT / firewall / cert issues, and wrong-token / wrong-project_id problems with a specific failure reason. See service-user deployments.

Troubleshooting

First, run python -m z4j_flask doctor — it surfaces the most common failures with a specific reason.

Agent starts but never connects - the first request triggers start. If your app has no inbound traffic yet (fresh deploy), the agent will appear offline until traffic arrives. Call z4j.start(app) at app-factory time if you prefer eager-start.
Gunicorn preload mode - the agent’s asyncio loop is per-worker. Preload is fine, but each worker still opens its own WebSocket after fork.
PermissionError: ... /var/www/.z4j in service log - upgrade to z4j-bare 1.0.6+ (auto-relocates buffer to $TMPDIR/z4j-{uid}) and see service-user deployments.