Copilot Instructions for Dev Proxy

Overview

Dev Proxy is a cross-platform .NET API simulator and proxy for testing how applications handle API failures, rate limits, latency, and more.

Critical (Non-Obvious)

• Proxy engine: Built on ASP.NET Core Kestrel (a custom forward-proxy + MITM engine; see DevProxy.Proxy.Kestrel)
• Config tokens: Paths in config files can use ~appFolder for resolution
• MCP Server: Use @devproxy/mcp to programmatically retrieve up-to-date docs and JSON schemas

Best Practices

See the comprehensive best practices guide: https://raw.githubusercontent.com/dev-proxy-tools/mcp/refs/heads/main/assets/best-practices.md

Key points:

• Store Dev Proxy files in .devproxy folder in the workspace
• Schema version in $schema must match installed Dev Proxy version
• In config files: plugins first, then urlsToWatch, then plugin configs
• Plugin order matters: latency plugins first, response simulators before reporters, reporters last
• URL matching is order-dependent: most specific URLs first, use ! prefix to exclude
• File paths are relative to the config file where they're defined
• Hot reload (v2.1.0+): config changes are detected and the proxy restarts automatically to apply them

Plugin Development

To create a new plugin:

1. Implement the IPlugin interface (DevProxy.Abstractions/Plugins/IPlugin.cs) either directly or by inheriting from BasePlugin / BaseReportingPlugin. Optionally implement IStdioPlugin for stdio-based communication.
2. Implement it as a public class in a class library project.
3. Implement the required interface members and override any relevant base class methods/events for your use case.

Commits & Releases

• Commit messages: Clear, succinct, and reference the issue they close when applicable
• Versioning: We follow semver. Use the upgrade-devproxy-version skill for version bumps
• Release: After release builds, homebrew is updated manually. Use the publish-to-winget skill for winget submissions

Testing Code Changes

When testing code, features, or changes, always launch the proxy in detached mode with these settings to avoid conflicts:

dotnet run --project DevProxy -- --detach --as-system-proxy false --port 0 --api-port 0

• --as-system-proxy false — prevents modifying system-wide network settings
• --port 0 — lets the OS assign a random available port for the proxy
• --api-port 0 — lets the OS assign a random available port for the API

Auth for M365/Azure: No automated auth. You can try m365 util accesstoken get or az account get-access-token (use -h for options) but the user may not be signed in.

Cleanup: After testing, stop the proxy using devproxy stop (preferred, cross-platform). If you started it with dotnet run, you can also stop it with Ctrl+C in that terminal; as a last resort, terminate the process using OS-specific tools (for example, kill <PID> on Unix-like systems or Task Manager on Windows). Clean up any generated log files (devproxy-*.log).

Reference (Architecture)

• Main entry point: DevProxy/Program.cs — sets up web host, configuration, logging, plugins, and starts proxy engine
• Proxy Engine: DevProxy/Proxy/ProxyEngine.cs — network interception, request/response handling, plugin invocation
• Plugins: Implement IPlugin interface (DevProxy.Abstractions/Plugins/IPlugin.cs). Base classes: BasePlugin, BaseReportingPlugin in DevProxy.Abstractions/Plugins/
• CLI Commands: DevProxy/Commands/ — built with System.CommandLine, registered via DevProxyCommand.cs
• Configuration: DevProxy/config/devproxyrc.json and other JSON files in config/
• macOS scripts: trust-cert.sh, remove-cert.sh, toggle-proxy.sh in DevProxy/

Resources

• Official documentation
• YouTube channel