How to Configure Rate Limiting Tiers for Humans and Agents in Buzz

Buzz enforces rate limits through a three-tiered precedence model where control-plane caps are immutable, policy defaults provide baseline limits, and user environment variables offer deployment-specific overrides that cannot exceed Tier 1 ceilings.

Buzz, the open-source framework developed by Block, implements a sophisticated rate limiting system that distinguishes between human-initiated traffic and agent-initiated traffic. The architecture relies on a layered tier system defined in docs/remote-agents.md and enforced through the relay admission layer in desktop/src-tauri/src/relay_admission.rs. Understanding how to configure these tiers allows operators to set hard ceilings for automated agents while providing flexibility for human users.

The Three-Tier Precedence Model

Buzz organizes rate limiting into three distinct tiers that follow strict override rules. Higher-priority tiers cannot be overridden by lower-priority ones, creating a hierarchy that protects system stability while allowing customization.

Tier 1: Control-Plane Caps (Immutable)

Tier 1 represents hard limits baked into the binary or injected by the provider infrastructure. These settings control maximum parallelism and quotas for agents through environment variables such as BUZZ_ACP_AGENTS. According to the source code in relay_admission.rs, these values are never overridden by later tiers, making them absolute ceilings that even administrative users cannot circumvent.

Tier 2: Policy Defaults

Tier 2 provides baseline limits defined in the launch.policy_env section of community launch descriptors (YAML files). These defaults apply to both human users and agents when no user-specific overrides exist. While Tier 3 configurations can supersede these values, Tier 2 settings cannot be modified by human-provided environment variables directly.

Tier 3: User Environment Overrides

Tier 3 allows per-deployment customizations through the launch.env section of launch descriptors. These values take precedence over Tier 2 policy defaults but remain bounded by Tier 1 restrictions. For example, a community can raise the human request quota for a specific deployment, but cannot exceed the hard agent limits established in Tier 1.

Step-by-Step Configuration

Configuring rate limiting requires modifications across all three tiers, followed by a relay restart to propagate changes to both the Rust backend (relay_admission.rs) and the client-side gate (relay_rate_limit_gate.dart).

Setting Tier 1 Control-Plane Limits

Set Tier 1 variables through your infrastructure configuration or .env files. These establish the absolute maximums that agents cannot exceed.

# Limit agents to 4 concurrent workers (immutable by users)

export BUZZ_ACP_AGENTS=4

# Example in systemd or container orchestration

BUZZ_ACP_AGENTS=8

These values are processed by the relay admission layer in desktop/src-tauri/src/relay_admission.rs, which implements the activate_rate_limit function to enforce these hard caps.

Defining Tier 2 Policy Defaults

Modify the launch.policy_env section in your community launch descriptor to establish default quotas for human and agent traffic.

# community-launch.yaml

launch:
  policy_env:
    BUZZ_MAX_HUMAN_RATE: 150    # requests/second for human clients

    BUZZ_MAX_AGENT_RATE: 30     # requests/second per agent key

    BUZZ_BURST_SIZE: 10         # burst tolerance for human users

These defaults apply universally to deployments using this launch descriptor unless Tier 3 overrides exist.

Applying Tier 3 User Overrides

Add environment variables to the launch.env section to customize limits for specific deployments without modifying the global policy.

launch:
  env:
    BUZZ_MAX_HUMAN_RATE: 300    # Raise human quota for this deployment only

    BUZZ_BACKOFF_WINDOW: 5s     # Custom retry interval

Remember that these values cannot exceed Tier 1 caps. If you attempt to set BUZZ_ACP_AGENTS=16 in Tier 3 when Tier 1 specifies BUZZ_ACP_AGENTS=8, the system enforces the Tier 1 value of 8.

Implementation Details

Relay Admission Layer Enforcement

The actual rate limiting enforcement occurs in desktop/src-tauri/src/relay_admission.rs, which maintains a rate-limit gate that blocks outgoing requests until a hint-derived cool-down expires. The gate stores state through the wait_for_rate_limit function and activates via activate_rate_limit.

When the relay receives an HTTP 429 response containing a rate-limited: … retry in N s hint, the relay.rs file extracts this timing information and feeds it into the shared gate. This mechanism applies identically to both human and agent traffic streams.

Human vs. Agent Traffic Handling

Human traffic flows through the desktop relay (desktop/src-tauri/src/relay.rs), which monitors HTTP responses and populates the rate-limit gate reactively based on server feedback.

Agent traffic shares the same gate through the ACP (Agent Control Plane) harness. The BUZZ_ACP_AGENTS environment variable (Tier 1) determines effective parallelism and is injected automatically by the control plane. Agents cannot raise this value themselves because the Tier 1 configuration takes precedence in the admission logic.

Client-Side Coordination

Mobile and desktop clients implement the gate logic in mobile/lib/shared/relay/relay_rate_limit_gate.dart, ensuring consistent throttling behavior across platforms. This Dart implementation coordinates with the Rust backend to honor the three-tier configuration hierarchy.

Summary

• Three immutable tiers control rate limiting: Tier 1 (control-plane), Tier 2 (policy defaults), and Tier 3 (user env).
• Tier 1 caps such as BUZZ_ACP_AGENTS are hard-coded or infrastructure-injected and cannot be overridden by any configuration.
• Tier 2 defaults are set in launch.policy_env and provide baseline limits for communities.
• Tier 3 overrides in launch.env allow deployment-specific customization but remain bounded by Tier 1.
• Relay enforcement occurs in relay_admission.rs through a shared gate mechanism that processes HTTP 429 hints.
• Restart required after modifying launch descriptors to load new limits into both Rust and Dart components.

Frequently Asked Questions

What happens if Tier 3 settings conflict with Tier 1 caps?

The system enforces Tier 1 control-plane limits regardless of user configuration. If launch.env specifies a higher concurrency limit than BUZZ_ACP_AGENTS in Tier 1, the relay admission layer in relay_admission.rs automatically clamps the value to the Tier 1 ceiling. This ensures provider-defined hard limits remain absolute.

How do I verify which rate limit tier is currently active?

Check the effective configuration by inspecting the launch descriptor used by your deployment. Active settings propagate from launch.policy_env (Tier 2) merged with launch.env (Tier 3), then bounded by environment variables like BUZZ_ACP_AGENTS (Tier 1). The relay logs in desktop/src-tauri/src/relay.rs indicate which limits triggered rate-limiting events when HTTP 429 responses occur.

Can agents bypass rate limits by using multiple keys?

No. The BUZZ_ACP_AGENTS Tier 1 variable controls the total concurrent agent count across all keys within a deployment. The relay admission gate tracks aggregate agent activity through the shared gate mechanism implemented in activate_rate_limit. Attempting to distribute requests across multiple agent keys still counts against the global Tier 1 concurrency cap.

Where is the rate-limit gate state stored between requests?

The gate state persists in memory within the Rust relay process (relay_admission.rs) and synchronizes with client-side implementations like relay_rate_limit_gate.dart. State derives from HTTP 429 response hints rather than configuration files, meaning the gate dynamically adjusts based on upstream server feedback while respecting the static tier boundaries defined in your YAML configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}