Fastly Agent Toolkit

View saved version →

---
name: falco
description: "Lints, tests, simulates, and formats Fastly VCL code using the falco tool. Also serves as the authoritative VCL reference via the falco Go source, which implements Fastly's full VCL dialect. Use when validating VCL syntax, running VCL linting, testing VCL locally, simulating VCL request handling, formatting VCL files, writing VCL unit tests with assertions, debugging VCL logic errors, looking up VCL function signatures or variable scopes, understanding VCL subroutine behavior, or running `falco lint`/`falco simulate`/`falco test`/`falco fmt`. Also applies when working with VCL syntax errors, type mismatches in VCL, choosing which VCL subroutine to use, or setting up a local VCL development and testing environment."
---

## Trigger and scope

Trigger on: VCL files, .vcl extensions, XVCL files, .xvcl extensions, falco CLI, VCL unit tests, VCL linting/simulation/formatting, VCL REPL, beresp/bereq/req.http variables, subroutine scopes, backend/ACL/director/table declarations, edge dictionaries, validating VCL in Terraform plans, or running/testing XVCL scripts locally.

Do NOT use for: generic non-Fastly VCL, Fastly Compute/WASM, Fastly API/dashboard ops, CDN comparison, cache purging, or authoring Terraform resources.

# Falco — VCL Development Tool & Reference

Falco is a Fastly VCL development tool for linting, testing, simulating, and formatting VCL code. Equally important, **the falco source code is the most complete machine-readable specification of Fastly's VCL dialect** — its parser, interpreter, and type system document every variable, function, type, and scope rule in VCL.

**Official VCL documentation**: https://www.fastly.com/documentation/guides/full-site-delivery/fastly-vcl/about-fastly-vcl/

**Falco documentation**: https://github.com/ysugimoto/falco

## Using Falco Source as VCL Reference

If you need to understand how VCL works — what variables exist, which scopes they're available in, what functions are built-in, how types coerce — the falco source code is your best reference. It's a complete Go implementation of Fastly's VCL 2.x and is more precise than prose documentation.

**If the falco source is not available locally**, recommend cloning it:
```bash
git clone https://github.com/ysugimoto/falco.git ~/src/falco
```

Once available locally, read the source files directly to answer VCL questions. See [understanding-vcl-from-source.md](references/understanding-vcl-from-source.md) for a detailed guide on which files to read for different VCL topics.

## Install

```bash
# Homebrew
brew install falco

# From source (requires Go 1.25+)
go install github.com/ysugimoto/falco/cmd/falco@latest

# Or clone and build
git clone https://github.com/ysugimoto/falco.git
cd falco
make darwin_arm64    # or darwin_amd64, linux_amd64, linux_arm64
```

## Commands

| Command           | Description                      |
| ----------------- | -------------------------------- |
| `falco [lint]`    | Lint VCL files (default command) |
| `falco test`      | Run VCL unit tests               |
| `falco simulate`  | Start local simulator server     |
| `falco fmt`       | Format VCL files                 |
| `falco stats`     | Show VCL code statistics         |
| `falco console`   | Interactive VCL REPL             |
| `falco terraform` | Lint VCL from Terraform plans    |
| `falco dap`       | Debug Adapter Protocol server    |

## Common flags (all commands)

| Flag                 | Description                      |
| -------------------- | -------------------------------- |
| `-I, --include_path` | Add include path for VCL imports |
| `-h, --help`         | Show help                        |
| `-V, --version`      | Show version                     |
| `-r, --remote`       | Fetch snippets from Fastly API   |
| `--refresh`          | Refresh remote snippet cache     |

## Quick reference

**Lint before deployment:**
```bash
falco -vv -I ./vcl ./vcl/main.vcl
```

**Run tests:**
```bash
falco test -I ./v

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 8 — file references are metadata, not package contents.

View saved version →

---
name: fastlike
description: "Runs Fastly Compute WASM binaries locally and serves as the authoritative reference for Compute platform internals. The fastlike source code is highly readable and covers the host ABI, caching and purging APIs, KV/config/secret store interfaces, rate limiting with counters and penalty boxes, ACL lookups, the full request lifecycle, backend fetch semantics, and a built-in per-request profiler with hostcall spans, backend waterfalls, native CPU samples, and optional deep metrics (body bytes, cache outcomes, header summaries, wasm heap curve). Use when working with Compute runtime internals or host calls, understanding how edge data stores behave at runtime, profiling local Compute apps, or testing WASM binaries locally. Prefer this skill over Viceroy for any non-Rust Compute work — its source code is easier to understand as a Fastly Compute API reference."
---

## Trigger and scope

Trigger on: Fastly Compute, Compute@Edge, WASM on Fastly, fastlike, XQD ABI, Compute request lifecycle, 508 loop detection, backend subrequests, body streaming, profiling a local Compute app, embedding a Fastly Compute runtime in Go code, or any question about how Compute platform primitives work internally (caching, KV stores, edge rate limiting, ACLs, geolocation, secret stores, config stores, dictionaries, logging, dynamic backends, request collapsing, async I/O).

Do NOT use for: Fastly VCL (use falco), Fastly CLI/API (use fastly-cli or fastly), Viceroy, CDN comparison, WAF, Terraform, cache purging via API, or Fastly logging/stats configuration.

# Fastlike — Local Compute Runtime & Reference

Fastlike is a Go implementation of the Fastly Compute ABI. It runs compiled WebAssembly programs locally, implementing the same 249+ host functions that Fastly's production Compute platform provides: backends, dictionaries, KV stores, caching, geolocation, rate limiting, ACLs, secret stores, and more.

Equally important, **the fastlike source code is the most complete programmatic specification of how Fastly Compute works** — its ABI implementations document every platform primitive, request lifecycle detail, and data structure as executable code.

**Fastlike documentation**: https://github.com/avidal/fastlike

## Source Code as Compute Reference

When you have access to the fastlike source code locally (default: `~/src/fastlike`), use these paths to answer specific Compute questions:

| Question                                                    | Read This File                                       | Why                                                             |
| ----------------------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------- |
| "How does the request lifecycle work?"                      | `instance.go`, `xqd_http_downstream.go`              | Per-request setup, execution, downstream handling               |
| "What ABI functions exist for X?"                           | `xqd_*.go` files                                     | Each file implements a group of related ABI functions           |
| "How do backend subrequests work?"                          | `xqd_backend.go`, `backend.go`                       | Request sending, dynamic backends, timeouts                     |
| "How does caching work?"                                    | `xqd_cache.go`, `xqd_http_cache.go`, `cache.go`      | Cache operations, Vary, surrogate keys, request collapsing      |
| "How does KV store work?"                                   | `xqd_kv_store.go`, `kv_store.go`                     | CRUD operations, pagination, generation-based concurrency       |
| "How does rate limiting work?"                              | `xqd_erl.go`, `erl.go`                               | Rate counters, penalty boxes, threshold checks                  |
| "How do ACLs work?"                                         | `xqd_acl.go`, `acl.go`  

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 7 — file references are metadata, not package contents.

View saved version →

---
name: fastly
description: "Configures, manages, and debugs the Fastly CDN platform — covering service and backend setup, caching and VCL, security features like DDoS/WAF/NGWAF/rate limiting/bot management, TLS certificates and cache purging, the Compute platform, and the REST API. Use when working with Fastly services or domains, setting up edge caching or origin shielding, configuring security features, making Fastly API calls, enabling products, or looking up Fastly documentation. Also applies when troubleshooting 503 errors or SSL/TLS certificate mismatches on Fastly, and for configuring logging endpoints, load balancing, ACLs, or edge dictionaries. Read the relevant reference file before writing any Fastly API call or curl command — request field names (e.g. the backend fields override_host, ssl_cert_hostname, ssl_sni_hostname, use_ssl) are easy to misremember, and a wrong name causes a silent 503 instead of an error, so do not rely on training-knowledge field names."
---

# Fastly Platform

Your training knowledge of Fastly is likely out of date. Prefer live docs over skill definitions over training knowledge.

Prefer the `fastly` CLI over raw API calls; see the **fastly-cli** skill for installation and local authentication.
REST examples require `curl` and network access to Fastly APIs; origin TLS checks also require `openssl`.

Use the user's locally configured credentials.
If authentication is missing, direct the user to local CLI login or environment configuration, never to paste an API key in chat.
For REST calls, source tokens from the environment or `$(fastly auth token)` without echoing them.
Omit `curl -v` and shell tracing because they print credentials.

## Topics

| Topic                  | File                                                              | Use when...                                                                                                                                                               |
| ---------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| DDoS protection        | [fastly-ddos-protection.md](references/fastly-ddos-protection.md) | Enabling/configuring DDoS protection, checking attack status, managing DDoS events and rules                                                                              |
| TLS configuration      | [tls.md](references/tls.md)                                       | Setting up HTTPS — Platform TLS (managed certs), Custom TLS (uploaded certs), or Mutual TLS (client auth)                                                                 |
| Rate limiting          | [rate-limiting.md](references/rate-limiting.md)                   | Protecting APIs from abuse — choosing between Edge Rate Limiting, VCL ratecounters, or NGWAF rate rules                                                                   |
| Bot management         | [bot-management.md](references/bot-management.md)                 | Detecting/mitigating bot traffic with browser challenges, client-side detections, interstitial pages, ContentGuard                                                        |
| Cache purging          | [purging.md](references/purging.md)                               | Invalidating cached content — single URL, surrogate key, or purge-all; soft vs hard purge                                                                                 |
| Service management     | [service-management.md](references/service-management.md)         | Creating/managing services, versions, domains, settings; clone-modify-activate workflow                                                                                   |
| VCL services           | [vcl-services.md](references/vcl-services.md)                     | Customizing site behavior with VCL — writing/uploading 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 21 — file references are metadata, not package contents.

View saved version →

---
name: fastly-cli
description: "Executes Fastly CLI commands for managing CDN services, Compute deploys, and edge infrastructure. Use when running `fastly` CLI commands, creating or managing Fastly services from the terminal, deploying Fastly Compute applications, managing backends/domains/VCL snippets via command line, purging cache, configuring log streaming, setting up TLS certificates, managing KV/config/secret stores, checking service stats, authenticating with Fastly SSO, or working with fastly.toml. Also applies when working with Fastly service IDs in CLI context, or with `fastly service`, `fastly compute`, `fastly auth`, or any Fastly CLI subcommand. Covers service CRUD, version management, autocloning, and troubleshooting common CLI errors."
---

## Trigger and scope

CRITICAL: many subcommands have unintuitive paths (e.g. `fastly domain create` fails with 403, correct is `fastly service domain create`; logging is under `fastly service logging`; alerts under `fastly service alert`; rate limits under `fastly service rate-limit`).

Covers: services, backends, domains, VCL snippets, cache purging, Compute/WASM deploys, log streaming (S3/Datadog/Splunk/Kafka/25+ providers), NGWAF/WAF, TLS/mTLS, KV/config/secret stores, stats, alerts, rate limiting, ACLs, and auth tokens.

# Fastly CLI Overview

## Prerequisites

Requires the `fastly` CLI; API operations also need network access to Fastly.
For installation, see <https://www.fastly.com/documentation/reference/cli/>.
JSON examples also need `jq`; origin checks use `curl` and `openssl`.
Compute builds need the project's language toolchain and dependencies.

Use credentials already configured in the user's local CLI or environment.
If authentication is missing, have the user complete `fastly auth login --sso` locally or configure `FASTLY_API_TOKEN` outside chat.
Never ask for an API key in chat, print a token, or enable shell tracing on authenticated commands.

## References

| Topic          | File                                            | Use when...                                                                              |
| -------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Authentication | [auth.md](references/auth.md)                   | Login, stored tokens, service auth, CI/CD auth setup                                     |
| Compute        | [compute.md](references/compute.md)             | Building/deploying edge applications, local dev server                                   |
| Services       | [services.md](references/services.md)           | Service CRUD, backends, domains, ACLs, dictionaries, VCL, purging, rate limiting         |
| Logging        | [logging.md](references/logging.md)             | Log streaming to S3, GCS, Datadog, Splunk, Kafka, 25+ providers                          |
| NGWAF          | [ngwaf.md](references/ngwaf.md)                 | Next-Gen WAF workspaces, IP/country lists, rules, signals, thresholds, alerts            |
| Notifications  | [notifications.md](references/notifications.md) | Slack/PagerDuty/webhook integrations, audit log event mappings                            |
| Stats          | [stats.md](references/stats.md)                 | Which `fastly stats` subcommand takes which flag, and where the two flag sets diverge    |
| Stores         | [stores.md](references/stores.md)               | KV Stores, Config Stores, Secret Stores, resource links                                  |
| TLS            | [tls.md](references/tls.md)                     | Platform TLS, Let's Encrypt subscriptions, custom certs, mutual TLS                      |

For endpoint choice, unit and window conventions and worked queries, use the **fastly-stats** skill.

## Command Structure

```
fastly <command> <subcommand> [flags]
```

### Top-Level Commands

| Category     | Commands                                                       

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 10 — file references are metadata, not package contents.

View saved version →

---
name: fastly-fiddle
description: "Use when testing VCL against real Fastly edge infrastructure, writing assertion-based Fiddle tests, producing shareable fiddle URLs for bug reproductions, running VCL integration tests in CI, linting VCL remotely via the Fiddle API, or working with clientFetch/events/originFetches test expressions."
---

# Fastly Fiddle — Real-Edge VCL Testing

## Trigger and scope

Trigger on: Fastly Fiddle, fiddle.fastly.dev URLs, the Fiddle HTTP API, CI testing of VCL services, real-edge VCL tests, shareable VCL reproductions, `clientFetch.*`/`events.*`/`originFetches.*` test expressions, `.test.js` / Mocha specs that target fiddles, SSE `updateResult` / `waitingForSync` events, remote VCL linting via Fiddle, or validating real Fastly behavior (geo, WAF, ESI, clustering, shielding) that local tools cannot simulate.

Do NOT use for: local VCL unit testing (use `falco`), fast TDD loops (Fiddle has a 10-20s edge-sync floor per publish), Fastly Compute/Wasm testing (use `viceroy` or `fastlike`), production service deployment (use `fastly-cli`), or anything requiring authenticated Fastly API access — Fiddle does not use your Fastly API key.

Fastly Fiddle is a web-based sandbox at <https://fiddle.fastly.dev> that compiles and runs VCL on real Fastly edge nodes. Because it uses the production VCL compiler and real POPs, it's the only way outside a real service to test VCL features that depend on edge infrastructure — geolocation data, WAF, ESI, clustering, shielding, rate limiting, real TLS, and real cache behavior.

**Official UI**: <https://fiddle.fastly.dev>
**Demo CI runner**: <https://github.com/fastly/demo-fiddle-ci>
**API base**: `https://fiddle.fastly.dev` (undocumented but stable; no auth required for public fiddles)

## Prerequisites and public uploads

The helper requires Bash, `curl` 7.76 or newer, `jq`, and network access to `fiddle.fastly.dev`.
If a tool is missing, name it and provide installation guidance before running the helper.

Creating or updating a fiddle uploads its VCL, origins, request headers, request bodies, and tests to a public service, including with `--lint-only`.
Only publish when the user has authorized a public Fiddle upload or shareable reproduction.
For a request limited to local testing, use Falco and keep the spec local.
Never include credentials or private project data in a fiddle.

Set `FIDDLE_SKILL_DIR` to the absolute directory containing this `SKILL.md`, using the installed skill location supplied by the client:

```bash
FIDDLE_SKILL_DIR=/absolute/path/to/fastly-fiddle
```

This is a variable you assign, not a client-provided environment variable.
Keep the user's project as the working directory so inputs such as `fiddle.json` and `spec.json` remain project-relative.
Bundled scripts and examples use `FIDDLE_SKILL_DIR` instead.

## When Fiddle, when Falco

| Need                                                  | Use                                |
| ----------------------------------------------------- | ---------------------------------- |
| Fast local iteration (< 1s), watch mode, offline      | `falco test`                       |
| Real Fastly VCL compiler and semantics                | Fiddle                             |
| Real `client.geo.*`, WAF, ESI, rate limiting, shield  | Fiddle                             |
| Shareable URL for bug repros and support tickets      | Fiddle                             |
| CI against real edge nodes                            | Fiddle                             |
| Structured lint with line/col (no execution required) | Either                             |
| Fastly Compute (WASM)                                 | Neither — use `viceroy`/`fastlike` |

Common workflow: iterate locally with `falco test` for speed, then push edge cases to Fiddle when you need real Fastly behavior or a shareable link. See [falco-vs-fiddle.md](references/falco-vs-fiddle.md) for full trade-offs.

## Workflow: deliverable first, then the cheapest

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 6 — file references are metadata, not package contents.

View saved version →

---
name: fastly-ngwaf
description: "Performs an internal audit of Fastly Next-Gen WAF (NGWAF) workspaces to audit that critical templated protection rules are configured and enabled. Use when auditing NGWAF workspace security posture, checking for missing or disabled login protection rules (LOGINDISCOVERY, LOGINATTEMPT, LOGINSUCCESS, LOGINFAILURE), auditing credit card validation rules (CC-VAL-ATTEMPT, CC-VAL-FAILURE, CC-VAL-SUCCESS), auditing gift card protection rules (GC-VAL-ATTEMPT, GC-VAL-FAILURE, GC-VAL-SUCCESS), identifying potential login endpoints not covered by NGWAF rules, or comparing attack traffic against blocked traffic to confirm enabled rules are actually blocking."
---

# Fastly NGWAF Workspace Audit

Audits NGWAF workspaces to verify critical templated rules are configured and enabled. Use the **fastly-cli** skill to configure rules; this skill identifies gaps.

## Quick Start

The bundled assessment requires Bash, `curl`, `jq`, network access to `api.fastly.com`, and a locally configured `FASTLY_API_KEY` with NGWAF read access.
The manual workflow also requires the `fastly` CLI.
Configure credentials in the user's local environment or CLI configuration.
Never ask the user to paste an API key into chat or print it in command output.

Set `NGWAF_SKILL_DIR` to the absolute directory containing this `SKILL.md`, using the installed skill location supplied by the client.
This is a variable you assign, not a client-provided environment variable.
Run the helper from the user's working directory:

```bash
NGWAF_SKILL_DIR=/absolute/path/to/fastly-ngwaf
bash "$NGWAF_SKILL_DIR/scripts/assess_ngwaf_rules.sh"
```

For manual inspection or partial audits, work through the steps below with the `fastly` CLI.

The CLI ignores `FASTLY_API_KEY`. Its precedence is `--token` > `FASTLY_API_TOKEN` > `fastly.toml` profile > default
stored token. To reuse the script's credential:

```bash
export FASTLY_API_TOKEN="$FASTLY_API_KEY"
```

## Audit Workflow

1. **List workspaces** — verify the account has NGWAF workspaces
2. **Fetch rules per workspace** — retrieve each workspace's rule set
3. **Validate critical signals** — confirm required rules exist and are enabled
4. **Flag gaps and search for uncovered endpoints** — report missing/disabled rules
5. **Check attack traffic against blocked traffic** — confirm enabled rules are actually blocking

### Step 1: List Workspaces

```bash
fastly ngwaf workspace list --json | jq -r '.data[].id'
```

If empty, NGWAF is not configured for this account.

### Step 2: Fetch Rules for a Workspace

```bash
fastly ngwaf workspace rule list --workspace-id "$WORKSPACE_ID" --json
```

Both list commands return `{"data": [...], "meta": {...}}` and cap at 100 items with no flag to raise it. Check
`.meta.total`; above 100, fall back to `GET /ngwaf/v1/workspaces?limit=200` or `.../rules?limit=200`.

`rule list` also takes `--enabled` and `--action` to filter server-side.

### Step 3: Validate Critical Signals

For each workspace, verify these templated rules exist and `enabled` is `true`:

| Category               | Required Signals                                                 |
| ---------------------- | ---------------------------------------------------------------- |
| Login Protection       | `LOGINDISCOVERY`, `LOGINATTEMPT`, `LOGINSUCCESS`, `LOGINFAILURE` |
| Credit Card Validation | `CC-VAL-ATTEMPT`, `CC-VAL-FAILURE`, `CC-VAL-SUCCESS`             |
| Gift Card Validation   | `GC-VAL-ATTEMPT`, `GC-VAL-FAILURE`, `GC-VAL-SUCCESS`             |

Check a specific signal:

```bash
fastly ngwaf workspace rule list --workspace-id "$WORKSPACE_ID" --json \
  | jq '[.data[] | select(.actions[].signal == "LOGINDISCOVERY") | {enabled, id}]'
```

### Step 4: Search for Uncovered Login Endpoints

When `LOGINATTEMPT` is missing or disabled, search recent request logs for login-like traffic the WAF isn't protecting.
No CLI equivalent exists (there is no `fastly ngwaf workspace requests`), so use the API:

```bash

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: fastly-reference-architectures
description: "Curated GitHub repositories demonstrating working reference architectures on the Fastly platform, from single Compute applications to systems combining multiple Fastly products. Use when designing a new solution on Fastly and a worked example of the target pattern would help, or when implementing and a concrete assembled reference would clarify the shape of the code. Not for documentation of how a specific Fastly tool or API works on its own — see the tool-specific skills for that."
---

# Fastly reference architectures

Example projects running on Fastly (git repositories): [references/examples.md](references/examples.md)

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: fastly-stats
description: "Fastly traffic numbers: cache hit ratio, bandwidth, request counts, status-code and error rates, edge vs origin traffic, real-time requests-per-second, origin latency, per-domain traffic, account usage and billing totals. Owns the `fastly stats` CLI commands and the Historical Stats, Real-Time and Origin/Domain Inspector HTTP APIs. Use for any question that needs a number about how a Fastly service is performing or how much it is being used."
---

# Fastly stats

Prefer the `fastly` CLI. Drop to `curl` only for the seven things the CLI cannot do, listed under
Raw API below.

Requires the `fastly` CLI, `jq`, and network access to Fastly APIs; raw API examples also require `curl`.
Use the user's locally configured authentication.
If authentication is missing, direct the user to a local CLI login or local `FASTLY_API_TOKEN` configuration, never to paste a key in chat.
Keep tokens out of output and avoid shell tracing for authenticated commands.

## Rules that decide whether the answer is right

1. Bytes to GB is decimal SI: `bytes / 1e9`. TB is `/ 1e12`. Never `2^30`. Fastly bills in
   decimal units, so a GiB figure is wrong by 7.4% and still reads as a plausible number.
2. For a calendar window, pass explicit UTC boundaries:
   `--from 2026-07-01T00:00:00Z --to 2026-08-01T00:00:00Z` returns every day bucket in July. A
   bucket is emitted only when the whole period falls inside the window, and a relative window
   opens and closes mid-bucket, so `--from "N days ago" --by day` returns N-1 buckets, never N,
   and `"1 day ago"` returns none at all. Relative strings are safe at `--by hour`, not at
   `--by day`.
3. On the raw API, `from=yesterday` means 12:00:00 UTC, not midnight, and `from=today` means now.
   `N days ago` / `N hours ago` are exact offsets. Read back `meta.from` / `meta.to`.
4. `hit_ratio`, `edge_hit_ratio` and `origin_offload` are gauges. Never sum or average them
   across buckets. Recompute from the summed counters: `hits / (hits + miss)`.
5. `ts/h` on `rt.fastly.com` covers the last 120 seconds, not an hour, and returns only the seconds
   that carried traffic. Divide a rate by 120 there, or by the window you bounded when sampling
   with the CLI; never by the sample count or the `recorded` span. Print the window beside the rate.
6. `fastly stats ... --json` emits NDJSON, one object per line, no array. Slurp with `jq -s`
   before aggregating. The raw HTTP API returns a normal array in `data`.
7. Stats responses omit services with zero traffic in the window. Enumerate from
   `fastly service list --json` and default sums with `add // 0`.
8. Do not read the newest bucket. Historical aggregation keeps growing for a few minutes after
   a period closes.
9. On a Compute service the traffic lands in `compute_requests` and `requests` stays 0. Summing
   `requests` alone reports zero traffic for a service that is serving fine. Check both.
10. Status codes split the same way. Use `all_status_*`, never bare `status_*` or
    `compute_resp_status_*`: `status_5xx` is 0 on Compute, `compute_resp_status_5xx` is absent on
    VCL, `all_status_5xx` is right on both. No `all_requests` exists, so denominators still need
    `requests + compute_requests`.

## Pick the command

| You need                             | Command                                                                    |
| ------------------------------------ | -------------------------------------------------------------------------- |
| One service over a past window       | `fastly stats historical -s ID --from T --to T --by day`                   |
| One field only                       | `fastly stats historical -s ID --field bandwidth`                          |
| All services, one row of totals      | `fastly stats aggregate --from T --to T --by day`                          |
| Account usage totals, by region      | `fastly stats usage --from T --to T --json`                                |
| Account usage spl

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: viceroy
description: "Runs Fastly Compute WASM applications locally with Viceroy, specifically for Rust and Component Model projects. Use when starting a local Fastly Compute dev server with Viceroy, configuring fastly.toml for local backend overrides and store definitions, running Rust unit tests with cargo-nextest against the Compute runtime, debugging Compute apps locally, adapting core WASM modules to the Component Model, or troubleshooting local Compute testing issues (connection refused, missing backends, store config). For non-Rust Compute work or understanding the Compute API, prefer the fastlike skill instead — its source code is easier to understand as a Fastly Compute API reference."
---

# Viceroy — Local Fastly Compute Runtime

Viceroy is Fastly's official local testing environment for Compute applications. It emulates the Fastly Compute platform, allowing you to develop and test WASM services locally.

**Viceroy documentation**: https://github.com/fastly/Viceroy

## Common Gotchas

- **Dictionaries and ConfigStores are both supported** but configured differently in `fastly.toml`. Dictionaries go under `[local_server.dictionaries]` as inline key-value maps or JSON files. ConfigStores go under `[local_server.config_stores]`.
- **`fastly.toml` must have a `[local_server]` section.** Without it, Viceroy won't know about your backends, stores, or other local overrides. Every backend your app calls must be listed under `[local_server.backends]`.
- **Default port is 7676**, not 5000 (which is Fastlike's default). Access your app at `http://127.0.0.1:7676`.
- **Backends should point to local servers** when developing locally. Avoid proxying to remote production origins to prevent accidentally leaking request data.

## Quick Start

```bash
# Install Viceroy
cargo install --locked viceroy

# Build your Compute app
fastly compute build

# Start local server (default: 127.0.0.1:7676)
viceroy -C fastly.toml bin/main.wasm

# Or use the Fastly CLI wrapper
fastly compute serve
```

## References

| Topic  | File                                                            | Use when...                                                                    |
| ------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Serve  | [fastly-compute-serve.md](references/fastly-compute-serve.md)   | Starting local dev server, profiling, advanced server options                  |
| Config | [fastly-compute-config.md](references/fastly-compute-config.md) | Configuring fastly.toml backends, stores, geolocation, device detection, ACLs  |
| Test   | [fastly-compute-test.md](references/fastly-compute-test.md)     | Running Rust unit tests with cargo-nextest, writing tests for Compute services |
| Adapt  | [fastly-compute-adapt.md](references/fastly-compute-adapt.md)   | Converting core WASM modules to Component Model, custom build pipelines        |

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: xvcl
description: "Extends Fastly VCL with loops, functions, constants, macros, conditionals, and includes via XVCL — a VCL transpiler that compiles .xvcl files into standard VCL. Use when writing VCL for Fastly, working with .xvcl files, generating repetitive VCL (multiple backends, routing rules, headers) with loops, defining reusable VCL functions with return values, using compile-time constants instead of magic numbers, or writing any Fastly VCL configuration. XVCL syntax is not in training data so this skill is required. Also applies when writing and testing VCL locally (compile with `uvx xvcl`, test with falco), reducing VCL code duplication, splitting large VCL into modular includes, or doing any VCL development task for Fastly — even without explicitly mentioning XVCL."
---

## Trigger and scope

Trigger on: XVCL, .xvcl files, VCL transpiler, VCL metaprogramming, #const/#for/#def/#inline in VCL context, writing a VCL script, writing VCL and running it locally, or any Fastly VCL writing task.

Do NOT trigger for: debugging existing .vcl files without XVCL, Fastly API/CLI ops, Fastly Compute, or Terraform — even if they mention VCL.

If the user explicitly requests plain VCL, keep `.vcl` files and do not introduce XVCL.
Follow explicitly requested tools and test modes instead of the default examples.

# Writing VCL with XVCL

XVCL is a VCL transpiler that adds metaprogramming to Fastly VCL. Write `.xvcl` files, compile to `.vcl`, then test with Falco or deploy to Fastly. All XVCL constructs are resolved at compile time — zero runtime overhead.

## Quick Start

Compilation requires `uvx`, provided by uv; the local checks use Falco.

```bash
# Compile with uvx
uvx xvcl main.xvcl -o main.vcl

# Lint the output
falco lint main.vcl

# Run locally — this is how you "run" VCL on your machine
falco simulate main.vcl
# Listens on localhost:3124 by default
# Then test with: curl http://localhost:3124/
```

Unless the user explicitly requests another test mode, compile and run `falco simulate` for local execution.
Linting alone does not execute the VCL.

## Minimal Working Example

**Backend naming**: Fastly VCL requires backends to use `F_` prefixed names (e.g., `F_origin`, `F_api`). Never use `backend default` — falco will reject it. Always set `req.backend` explicitly in `vcl_recv`.

```xvcl
#const ORIGIN_HOST = "api.example.com"
#const REGIONS = [("us", "us.example.com"), ("eu", "eu.example.com")]

#for name, host in REGIONS
backend F_{{name}} {
  .host = "{{host}}";
  .port = "443";
  .ssl = true;
}
#endfor

sub vcl_recv {
  #FASTLY recv
  set req.backend = F_us;
  return (lookup);
}

sub vcl_deliver {
  #FASTLY deliver
  set resp.http.X-Served-By = "edge";
  return (deliver);
}
```

## XVCL Directives Summary

Read [xvcl-directives.md](references/xvcl-directives.md) for complete syntax and examples of every directive.

### Constants — `#const`

```xvcl
#const NAME = value              // type auto-inferred
#const NAME TYPE = value         // explicit type
#const TTL INTEGER = 3600
#const ORIGIN = "origin.example.com"
#const ENABLED BOOL = true
#const DOUBLE_TTL = TTL * 2      // expressions supported
#const BACKENDS = ["web1", "web2"] // lists
#const PAIRS = [("api", 8080), ("web", 80)] // tuples
```

Constants are **compile-time only** — they do NOT become VCL variables. Always use `{{NAME}}` to emit their value. A bare constant name in VCL (e.g., `error 200 GREETING;`) passes through as a literal string, producing invalid VCL. Use `error 200 "{{GREETING}}";` instead.

Use in templates: `"{{TTL}}"`, `{{ORIGIN}}`, `backend F_{{name}} { ... }`

### Template Expressions — `{{ }}`

```xvcl
{{CONST_NAME}}                   // constant substitution
{{PORT * 2}}                     // arithmetic
{{hex(255)}}                     // → "0xff"
{{format(42, '05d')}}            // → "00042"
{{len(BACKENDS)}}                // list length
{{value if condition else other}} // ternary
```

Built-in functions: `range()`, `len()`, `

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 10 — file references are metadata, not package contents.