Raspberry Pi Guide

Run Grantex-authorized Gemma agents on Raspberry Pi 5 with offline token verification, scope enforcement, local audit records, and later synchronization.

Overview

Raspberry Pi 5 with 8GB RAM can run smaller Gemma model variants locally through compatible runtimes. This guide shows how to add Grantex offline authorization so configured actions are scope-checked and recorded locally without internet connectivity; current revocation state requires later synchronization.

Prerequisites

• Raspberry Pi 5 (8GB recommended, 4GB minimum for smaller Gemma 4 variants)
• Raspberry Pi OS (64-bit Bookworm or later)
• Python 3.10+ (ships with Bookworm)
• A Grantex account with API key and a registered agent
• Wi-Fi or Ethernet for initial setup (offline operation starts after provisioning)

Hardware Notes

Component	Recommendation
Board	Raspberry Pi 5, 8GB
Storage	32GB+ microSD or NVMe SSD via M.2 HAT
Cooling	Active cooler recommended — inference is CPU-intensive
Power	Official 27W USB-C PSU

Gemma 4’s 2B parameter model requires ~4GB of RAM. The 7B model requires an 8GB Pi with swap configured.

Step 1: Install Dependencies

# Update system
sudo apt update && sudo apt upgrade -y

# Install Python build dependencies
sudo apt install -y python3-pip python3-venv

# Create a project directory
mkdir ~/gemma-agent && cd ~/gemma-agent
python3 -m venv .venv
source .venv/bin/activate

# Install grantex-gemma
pip install grantex-gemma

Step 2: Provision the Consent Bundle

Run this script once while the Pi has internet access. It creates a consent bundle and encrypts it to disk.

#!/usr/bin/env python3
"""provision.py — Run once while online to create a consent bundle."""

import os
from grantex_gemma import create_consent_bundle, store_bundle

BUNDLE_PATH = os.path.expanduser("~/gemma-agent/bundle.enc")
ENCRYPTION_KEY = os.environ["BUNDLE_KEY"]

bundle = create_consent_bundle(
    api_key=os.environ["GRANTEX_API_KEY"],
    agent_id=os.environ["AGENT_ID"],
    user_id="pi-user-001",
    scopes=["sensor:read", "actuator:write", "log:append"],
    offline_ttl="72h",
)

store_bundle(bundle, BUNDLE_PATH, ENCRYPTION_KEY)

print(f"Bundle created: {bundle.bundle_id}")
print(f"Offline until:  {bundle.offline_expires_at}")
print(f"Stored at:      {BUNDLE_PATH}")

Run it:

export GRANTEX_API_KEY="gx_..."
export AGENT_ID="ag_01HXYZ..."
export BUNDLE_KEY="a-strong-passphrase-here"

python3 provision.py

Step 3: Build the Offline Agent

This is the main agent script. It loads the bundle, creates a verifier and audit log, then runs a loop that checks authorization before every action.

#!/usr/bin/env python3
"""agent.py — Offline Gemma 4 agent with Grantex authorization."""

import os
import time
from grantex_gemma import (
    load_bundle,
    create_offline_verifier,
    create_offline_audit_log,
    enforce_scopes,
)

BUNDLE_PATH = os.path.expanduser("~/gemma-agent/bundle.enc")
AUDIT_PATH = os.path.expanduser("~/gemma-agent/audit.jsonl")
ENCRYPTION_KEY = os.environ["BUNDLE_KEY"]

# Load the consent bundle (decrypts from disk)
bundle = load_bundle(BUNDLE_PATH, ENCRYPTION_KEY)

# Create offline verifier using the JWKS snapshot
verifier = create_offline_verifier(
    jwks_snapshot=bundle.jwks_snapshot,
    require_scopes=["sensor:read"],
    clock_skew_seconds=60,  # Pi clocks can drift
)

# Create audit log
audit_log = create_offline_audit_log(
    signing_key=bundle.offline_audit_key,
    log_path=AUDIT_PATH,
    max_size_mb=10,  # conservative for SD card
)

def read_sensor():
    """Simulate reading a sensor value."""
    return {"temperature": 22.5, "humidity": 45.2}

def run_agent():
    """Main agent loop — verify token before every action."""
    print("Agent starting...")

    # Verify the grant token (offline, no network call)
    start = time.perf_counter_ns()
    grant = verifier.verify(bundle.grant_token)
    verify_ms = (time.perf_counter_ns() - start) / 1_000_000

    print(f"Token verified in {verify_ms:.2f}ms")
    print(f"Agent: {grant.agent_did}")
    print(f"Scopes: {', '.join(grant.scopes)}")
    print(f"Expires: {grant.expires_at.isoformat()}")

    # Simulate an agent action
    sensor_data = read_sensor()

    # Log the action
    entry = audit_log.append(
        action="sensor.read",
        agent_did=grant.agent_did,
        grant_id=grant.grant_id,
        scopes=grant.scopes,
        result="success",
        metadata=sensor_data,
    )

    print(f"Audit entry #{entry.seq}: {entry.hash[:16]}...")
    print(f"Sensor: {sensor_data}")

if __name__ == "__main__":
    run_agent()

Run it:

export BUNDLE_KEY="a-strong-passphrase-here"
python3 agent.py

Expected output:

Agent starting...
Token verified in 3.42ms
Agent: did:grantex:ag_01HXYZ...
Scopes: sensor:read, actuator:write, log:append
Expires: 2026-04-06T12:00:00+00:00
Audit entry #1: a3f29c81b4e2f1a7...
Sensor: {'temperature': 22.5, 'humidity': 45.2}

Step 4: Sync When Online

Create a sync script that runs when the Pi reconnects:

#!/usr/bin/env python3
"""sync.py — Upload offline audit entries to Grantex cloud."""

import os
from grantex_gemma import load_bundle, create_offline_audit_log

BUNDLE_PATH = os.path.expanduser("~/gemma-agent/bundle.enc")
AUDIT_PATH = os.path.expanduser("~/gemma-agent/audit.jsonl")

bundle = load_bundle(BUNDLE_PATH, os.environ["BUNDLE_KEY"])

audit_log = create_offline_audit_log(
    signing_key=bundle.offline_audit_key,
    log_path=AUDIT_PATH,
)

result = audit_log.sync(
    api_key=os.environ["GRANTEX_API_KEY"],
    bundle_id=bundle.bundle_id,
)

print(f"Accepted: {result.accepted}")
print(f"Rejected: {result.rejected}")
print(f"Revocation status: {result.revocation_status}")

if result.revocation_status == "revoked":
    print("WARNING: Grant was revoked. Stopping agent.")
    os.remove(BUNDLE_PATH)

Performance Considerations

A Raspberry Pi deployment performs these operations locally:

Operation	Execution characteristic	Notes
loadBundle (decrypt)	Local cryptographic operation	AES-256-GCM decryption of the stored bundle
verifier.verify()	Local signature verification	Runtime depends on key material, implementation, and device load
enforce_scopes()	Local array comparison	Cost scales with the number of required and granted scopes
audit_log.append()	Local hashing, signing, and storage	Runtime depends on storage and signing configuration
verify_chain()	Full-chain verification	Cost scales with the number of entries

Benchmark these operations on the target device and workload. Performance varies with bundle size, key implementation, storage, thermal state, and concurrent inference load.

Production Tips

Log Rotation

The audit log grows by ~200 bytes per entry. At 1 action per second, that is ~17MB per day. Set max_size_mb appropriately for your SD card:

audit_log = create_offline_audit_log(
    signing_key=bundle.offline_audit_key,
    log_path=AUDIT_PATH,
    max_size_mb=10,  # rotates at 10MB
)

Rotated files are named audit.jsonl.2026-04-03T12-00-00-000Z.bak.

Bundle Refresh Cron

If the Pi connects to Wi-Fi daily, add a cron job to refresh the bundle:

# crontab -e
0 3 * * * cd ~/gemma-agent && source .venv/bin/activate && python3 refresh.py 2>> /var/log/gemma-refresh.log

The refresh script:

#!/usr/bin/env python3
"""refresh.py — Refresh the consent bundle if TTL is running low."""

import os
import sys
from grantex_gemma import load_bundle, store_bundle

# Import shouldRefresh and refreshBundle from the TS SDK's Python equivalent
BUNDLE_PATH = os.path.expanduser("~/gemma-agent/bundle.enc")
ENCRYPTION_KEY = os.environ.get("BUNDLE_KEY", "")

if not ENCRYPTION_KEY:
    print("BUNDLE_KEY not set, skipping refresh")
    sys.exit(0)

bundle = load_bundle(BUNDLE_PATH, ENCRYPTION_KEY)

# Check if refresh is needed (< 20% TTL remaining)
from datetime import datetime, timezone
expires = datetime.fromisoformat(bundle.offline_expires_at)
remaining = (expires - datetime.now(timezone.utc)).total_seconds()
total_ttl = (expires.timestamp() * 1000 - bundle.checkpoint_at) / 1000

if total_ttl > 0 and (remaining / total_ttl) < 0.2:
    from grantex_gemma import create_consent_bundle
    fresh = create_consent_bundle(
        api_key=os.environ["GRANTEX_API_KEY"],
        agent_id=os.environ["AGENT_ID"],
        user_id="pi-user-001",
        scopes=["sensor:read", "actuator:write", "log:append"],
        offline_ttl="72h",
    )
    store_bundle(fresh, BUNDLE_PATH, ENCRYPTION_KEY)
    print(f"Bundle refreshed: {fresh.bundle_id}")
else:
    pct = (remaining / total_ttl * 100) if total_ttl > 0 else 0
    print(f"Bundle OK ({pct:.0f}% TTL remaining)")

Systemd Service

Run the agent as a systemd service for automatic restart:

# /etc/systemd/system/gemma-agent.service
[Unit]
Description=Gemma 4 Agent with Grantex Auth
After=multi-user.target

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi/gemma-agent
Environment=BUNDLE_KEY=your-key-here
ExecStart=/home/pi/gemma-agent/.venv/bin/python3 agent.py
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl enable gemma-agent
sudo systemctl start gemma-agent

SD Card Wear

Frequent writes to the audit log can wear out SD cards. Mitigations:

• Use an NVMe SSD via M.2 HAT for write-heavy workloads
• Set max_size_mb to limit log file growth
• Use tmpfs for temporary logs and sync to persistent storage periodically

Next Steps

• Offline Authorization — architecture and security model
• Gemma 4 SDK Reference — complete API reference
• Quickstart: Gemma 4 — step-by-step tutorial
• Android Guide — run on Android devices