Rules as code: file-based configuration

Store HTTPeep rules as YAML files, version them with Git, and share them across your team — so your debugging setup travels with your code.

HTTPeep stores every rule, bypass, DNS override, external proxy setting, and rate limit as a plain YAML file under ~/.httpeep/rules/. Because your configuration lives on disk, you can commit it to Git, branch it per project, review changes in pull requests, and share it with your team the same way you share application code. Rules you build today become reusable assets you never have to recreate.

Configuration directory structure

All configuration files live in a single directory:

~/.httpeep/rules/
├── rule.yaml           # Rule configuration
├── bypass.yaml         # Bypass configuration
├── dns_override.yaml   # DNS override configuration
├── external_proxy.yaml # External proxy configuration
└── rate_limit.yaml     # Rate limit configuration

Each file controls one aspect of HTTPeep's behavior. You can edit them directly in a text editor, or let the GUI write them for you — both approaches produce the same files.

The rule.yaml file

rule.yaml is the primary configuration file. It holds an ordered list of rules; HTTPeep evaluates them top-to-bottom for every request.

Each rule follows the Match → Request Actions → Resolve → Response Actions pipeline:

# rule.yaml - Main Rule Configuration Example
- id: rule_mnhi5xkt
  description: "Frontend Mock API"
  enabled: true           # Toggle without deleting the rule
  builtin: false
  stopAfterMatched: false # Continue evaluating later rules if true is not set

  match:
    domains:
      - type: exact         # Match types: exact, wildcard, regex
        value: api.example.com
    originProtocol: https   # Match only HTTPS requests

  requestActions: []        # Actions to run before sending to the target

  resolve:
    type: map_local_dir     # Resolve types: pass_through, map_remote, map_local, map_local_dir, block
    filePath: /Users/chris/mocks/api
    headers:
      x-httpeep-debug: '1' # Inject a header into the mock response

  responseActions:
    - type: delay_response
      id: action_1775140499860
      enabled: true
      delayMs: 500           # Add 500 ms of artificial latency

    - type: throttle_response
      id: action_1775591855867
      enabled: true
      speed:
        max: 384             # Maximum throughput in KB/s
        burst: 768           # Burst ceiling in KB/s

Exporting and importing rules

You can move rules between machines, share them with colleagues, or back them up using the GUI or CLI.

In the HTTPeep sidebar, navigate to Rules.

Click the Export button (or right-click a rule) and choose Export to file. HTTPeep writes a YAML file you can save anywhere.

Click Import, select a previously exported YAML file, and HTTPeep adds the rules to your current set. Duplicate IDs are skipped.

# Export all rules to a file
httpeep-cli rules export --output rules-backup.yaml

# Import rules from a file
httpeep-cli rules import rules-backup.yaml

Importing via CLI adds the rules from the file to your existing ruleset. It does not replace rules that already exist with the same ID.

Because rules are plain files, they fit naturally into any Git workflow. A typical team setup looks like this:

Initialize a Git repository in ~/.httpeep/rules/ (or symlink it to a location inside your project repo). Commit your rules alongside your code.

cd ~/.httpeep/rules
git init
git add .
git commit -m "Initial rule configuration"

Create a remote repository for team-wide rules (for example, a httpeep-rules repo in your organization). Team members clone or pull from this remote to get the shared baseline.

git remote add origin https://github.com/your-org/httpeep-rules.git
git push -u origin main

Check out a branch per project or environment. Switching branches instantly changes which rules are active.

git checkout -b feature/payments-api
# Edit rules for this project, then commit
git checkout main
# Back to the shared baseline

When a teammate adds or modifies a rule, they open a pull request. Because each rule is a readable YAML diff, reviewers can see exactly what changed before merging.

Add a .gitignore entry for any rules containing sensitive values (for example, hardcoded credentials in a request body rewrite). Use environment variable placeholders instead.

Environment branches

Different branches can hold different rule sets for each stage of your workflow:

Branch	Purpose
`main`	Shared baseline rules safe for all developers
`dev`	Rules that redirect traffic to local services
`staging`	Rules that point to the staging environment
`security-testing`	Rules that chain through Burp Suite for penetration testing

Because HTTPeep reads rules from disk in real time, checking out a different branch takes effect immediately — no restart required.

Benefits of rules as code

Reproducibility — any developer on the team can clone the rules repo and reproduce the exact same proxy behavior.
Audit history — git log shows who changed which rule and why, with a full diff.
Code review — rule changes go through the same PR process as application code, catching mistakes before they affect the team.
Environment isolation — branch-per-environment means staging rules never accidentally apply to production traffic.
Backup and recovery — rules are never locked inside the app; they exist as files you own.

Rules as code: file-based configuration

Configuration directory structure

The rule.yaml file

id

stopAfterMatched

match.domains

resolve types

Exporting and importing rules

Git workflow for team sharing

Environment branches

Benefits of rules as code

On this page