Quickstart - events flowing in 5 minutes

The fastest path from zero to events in the dashboard. You need a running FastAPI application and a Guard Core account.

What you need first

• A FastAPI application (Python ≥ 3.10)
• A Guard Core account with access to app.guard-core.com
• Four environment variables you will set in the next step:
  • GUARD_API_KEY - your project API key
  • GUARD_PROJECT_ID - your project's ID, shown in the dashboard when you create or open the project
  • GUARD_PROJECT_ENCRYPTION_KEY - your project encryption key (set when you enable encryption on the key)
  • GUARD_CORE_URL - the Core API base URL (e.g. https://api.guard-core.com/api/v1)

1. Install

No version pins are published in the example requirements file. Install the latest releases within the supported ranges:

pip install "fastapi-guard>=7.0.0,<8.0.0" "guard-agent>=2.5.0,<3.0.0" "guard-core>=3.0.0,<4.0.0"

How the packages fit together

Guard Core is layered. You install three packages, but you only write code against one:

• guard-core - the framework-agnostic security engine (IP control, rate limiting, signature detection). You never import it directly; it ships as a transitive dependency of the adapter.
• fastapi-guard - the FastAPI adapter you configure: import SecurityConfig and SecurityMiddleware from guard, set the agent_* fields, and it drives everything else.
• guard-agent - the telemetry shipper. It is a separate install (not pulled in automatically) that batches your security events and sends them to https://api.guard-core.com. You do not instantiate it - enable_agent=True wires it for you.

agent_endpoint is the bare host (https://api.guard-core.com). The agent appends /api/v1/events itself, so do not add /api/v1. (GUARD_CORE_URL, used for the REST API, does include /api/v1, different value.)

2. Create a project and API key

In the dashboard, go to Settings → API Keys → Create API Key. Enable encryption (recommended for production). Copy both the API key and the encryption key, since they are shown once and cannot be recovered.

For a detailed walkthrough of what projects and API keys are, see what these are.

Set the four env vars before starting your application:

export GUARD_API_KEY="fg_01He..."
export GUARD_PROJECT_ID="proj_abc123def456..."
export GUARD_PROJECT_ENCRYPTION_KEY="<base64-key-shown-once>"
export GUARD_CORE_URL="https://api.guard-core.com/api/v1"

3. Minimal SecurityConfig

The smallest SecurityConfig that produces events in the dashboard. Every field below is required for telemetry to flow:

import os
from guard import SecurityConfig, SecurityMiddleware

api_key = os.environ.get("GUARD_API_KEY", "")
project_id = os.environ.get("GUARD_PROJECT_ID", "")
encryption_key = os.environ.get("GUARD_PROJECT_ENCRYPTION_KEY") or None
core_url = os.environ.get("GUARD_CORE_URL", "http://localhost:8000/api/v1")

agent_endpoint = core_url.rstrip("/").removesuffix("/api/v1")

security_config = SecurityConfig(
    enable_agent=True,
    agent_api_key=api_key,
    agent_project_id=project_id,
    agent_project_encryption_key=encryption_key,
    agent_endpoint=agent_endpoint,
    enable_penetration_detection=True,
    enable_rate_limiting=True,
    enable_ip_banning=True,
)

Fields used above:

Note: agent_endpoint is the base URL without the /api/v1 path suffix. The example above strips the suffix from GUARD_CORE_URL exactly as examples/app.py does.

4. Wire the lifespan helper

fastapi-guard 7.1.0 introduced guard_lifespan, a lifespan context manager that starts background tasks (buffer flushing, dynamic rule polling). Pass it as lifespan=guard_lifespan when constructing your FastAPI app, and add the middleware:

from fastapi import FastAPI
from guard import SecurityMiddleware
from guard.lifespan import guard_lifespan

app = FastAPI(
    title="My App",
    lifespan=guard_lifespan,
)

app.add_middleware(SecurityMiddleware, config=security_config)

The import path is guard.lifespan and the symbol is guard_lifespan, verified against examples/app.py. guard_lifespan warms up the agent at startup and starts its background flush loop; if you omit it the agent initializes lazily on the first request it observes. The same flush loop then starts at that point rather than at boot, so delivery only begins once the first request arrives and the earliest events can be delayed. Wire guard_lifespan so flushing starts at boot rather than on first traffic.

5. Run it and trigger an event

Start your application and send a request with an obviously malicious query string to trip the SQLi detector:

uvicorn app:app --reload

curl "http://localhost:8000/search?q=' OR 1=1 --"

The ' OR 1=1 -- pattern matches the SQLi detection rules. A detection event is appended to the agent buffer and flushed to the Core API within agent_flush_interval seconds (default 30s; set agent_flush_interval=2 in your config for faster feedback during development).

Verify in the dashboard

Open app.guard-core.com and navigate to the Events page for your project. You should see a penetration_attempt event from your local IP. The how-to guide for reading and filtering events is in the dashboard documentation, available with an account.

If nothing appears

• Wrong GUARD_CORE_URL: the agent is posting to the wrong endpoint. If agent_endpoint accidentally includes /api/v1, the agent strips the trailing /api/v1 and logs a warning. Grep logs for that warning (see step 3).
• Key not for this project: GUARD_API_KEY may belong to a different project than GUARD_PROJECT_ID. Both must match the same project row in the dashboard.
• Buffer not flushed yet: events queue in-process and flush on size-or-time trigger. At the default agent_flush_interval=30, you may wait up to 30 seconds. Set agent_flush_interval=2 during development.

A full decision tree for diagnosing missing events is in Events not appearing in the dashboard.

Next steps

• How a request flows through fastapi-guard - the mental model every config knob hangs off
• Passive mode vs fail-secure - deploy without bricking production on day one