# Pistachio Gateway: Agent Deployment Runbook

This is a machine-readable deployment guide for AI agents. Follow these steps exactly to deploy a Pistachio inference gateway.

## Prerequisites (verify before starting)

1. Docker installed: `docker --version`
2. An Ethereum wallet private key for Base network (0x... hex format)
3. A free Alchemy account at https://alchemy.com with a Base Mainnet API key
4. One of: Fly.io CLI (`fly`), Google Cloud CLI (`gcloud`), or any Docker host

## Step 1: Generate an API key

```bash
export GATEWAY_API_KEY="pst_$(openssl rand -hex 12)"
echo "Your API key: $GATEWAY_API_KEY"
```

Save this key. Your users will need it to authenticate.

## Step 2: Set environment variables

```bash
export PISTACHIO_PRIVATE_KEY="0x..."          # Your wallet private key
export BASE_RPC_URLS="https://base-mainnet.g.alchemy.com/v2/YOUR_ALCHEMY_KEY"
export GATEWAY_MODE="true"
export GATEWAY_REQUIRE_AUTH="true"
export GATEWAY_INSTANCE="my-gateway"          # Optional: label for the UI
```

## Step 3: Deploy

### Option A: Fly.io (recommended, ~$5/mo)

```bash
fly apps create $GATEWAY_INSTANCE
fly secrets set \
  PISTACHIO_PRIVATE_KEY=$PISTACHIO_PRIVATE_KEY \
  GATEWAY_API_KEY=$GATEWAY_API_KEY \
  BASE_RPC_URLS=$BASE_RPC_URLS \
  --app $GATEWAY_INSTANCE

cat > fly.toml << 'FLYEOF'
app = 'my-gateway'
primary_region = 'iad'

[build]

[env]
  GATEWAY_MODE = "true"
  GATEWAY_REQUIRE_AUTH = "true"

[http_service]
  internal_port = 19377
  force_https = true
  auto_stop_machines = 'off'
  auto_start_machines = true
  min_machines_running = 1

[[http_service.checks]]
  grace_period = "60s"
  interval = "15s"
  method = "GET"
  timeout = "10s"
  path = "/inference/health"

[[vm]]
  memory = '1gb'
  cpu_kind = 'shared'
  cpus = 1
FLYEOF

# Replace app name in fly.toml
sed -i '' "s/my-gateway/$GATEWAY_INSTANCE/" fly.toml 2>/dev/null || sed -i "s/my-gateway/$GATEWAY_INSTANCE/" fly.toml

fly deploy --image drm3/pistachio:latest
```

### Option B: Docker (any host)

```bash
docker run -d \
  --name pistachio-gateway \
  -p 19377:19377 \
  -e GATEWAY_MODE=true \
  -e GATEWAY_REQUIRE_AUTH=true \
  -e PISTACHIO_PRIVATE_KEY=$PISTACHIO_PRIVATE_KEY \
  -e GATEWAY_API_KEY=$GATEWAY_API_KEY \
  -e BASE_RPC_URLS=$BASE_RPC_URLS \
  -e GATEWAY_INSTANCE=$GATEWAY_INSTANCE \
  --restart unless-stopped \
  drm3/pistachio:latest
```

### Option C: Google Cloud Run

```bash
gcloud run deploy pistachio \
  --image drm3/pistachio:latest \
  --port 19377 \
  --set-env-vars "GATEWAY_MODE=true,GATEWAY_REQUIRE_AUTH=true,GATEWAY_INSTANCE=$GATEWAY_INSTANCE" \
  --set-secrets "PISTACHIO_PRIVATE_KEY=pistachio-key:latest,GATEWAY_API_KEY=gateway-key:latest,BASE_RPC_URLS=base-rpc:latest" \
  --allow-unauthenticated \
  --min-instances 1 \
  --memory 1Gi
```

## Step 4: Verify deployment

```bash
# Health check (no auth required)
curl -s https://YOUR_GATEWAY_URL/inference/health | python3 -m json.tool

# Expected: {"status":"ok", ...}
```

```bash
# List available models
curl -s https://YOUR_GATEWAY_URL/inference/v1/models \
  -H "Authorization: Bearer $GATEWAY_API_KEY" | python3 -m json.tool
```

```bash
# Test inference
curl -s https://YOUR_GATEWAY_URL/inference/v1/chat/completions \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-4.7",
    "messages": [{"role": "user", "content": "Hello, what model are you?"}]
  }' | python3 -m json.tool
```

## Step 5: Claim a DRM3 Pass (required for staking)

Visit your gateway dashboard in a browser and go to the Wallet page. Click "Claim Free Pass" to mint a DRM3 Pass NFT (~$0.01 gas). This enables session staking.

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| Health returns 502 | Container not ready | Wait 60s after deploy |
| "no_endpoint" errors | No staked sessions | Open dashboard, go to Auto-Staker, pick a template |
| "unauthorized" | Wrong API key | Check GATEWAY_API_KEY matches your Bearer token |
| "insufficient capacity" | No DRM3 Pass | Claim a pass from the Wallet page |
| Models list empty | Chain data loading | Wait 5 minutes for background chain sync |

## Configuration reference

| Variable | Required | Description |
|----------|----------|-------------|
| PISTACHIO_PRIVATE_KEY | Yes | Wallet private key (0x hex) |
| GATEWAY_API_KEY | Yes | Bearer token for API access |
| BASE_RPC_URLS | Yes | Base mainnet RPC (comma-separated) |
| GATEWAY_MODE | Yes | "true" for hosted mode |
| GATEWAY_REQUIRE_AUTH | Yes | "true" to require API keys |
| GATEWAY_INSTANCE | No | Instance label for UI |
| GATEWAY_BASE_URL | No | Base URL for OpenGraph |
| ALLOWED_HOSTS | No | Restrict to custom domain |

## API (OpenAI-compatible)

Base URL: `https://YOUR_GATEWAY_URL/inference`

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | /v1/chat/completions | Bearer | Chat completion (streaming supported) |
| GET | /v1/models | Bearer | List available models |
| GET | /health | None | Health check |

## Cost

~$5-8/month total: shared CPU (~$5-7), free RPC, minimal gas (~$0.30).

## Links

- Docker image: https://hub.docker.com/r/drm3/pistachio
- Full docs: https://github.com/drm3labs/drm3-releases/blob/main/products/pistachio/GATEWAY.md
- Blog post: https://drm3.io/blog/pistachio-v023-telemetry-provider-intelligence
- Product page: https://drm3.io/products/pistachio
- Releases: https://github.com/drm3labs/drm3-releases/releases

---
Pistachio v0.20 . DRM3 Labs Corp.