Documentation

Start Core

Run with Docker

The default Docker setup runs the web console on localhost and keeps persistent state in the project data folder.

The App Trust Proxy Core source repository is available at AppTrust/AppTrustProxyCore.

docker compose up --build

Open the web console after startup.

http://localhost:8080

Run without Docker

Use the local runner when Docker is not available or when you want to run the checked out project directly.

./scripts/run_without_docker.sh

The script detects macOS or the Linux distro, checks Node.js and OpenSSL, asks before installing missing tools, explains what it will run, then asks again before starting the server.

Local services

Default ports

Client setup

Connect a test app or device

Choose the local IP in Network Modes, then configure the test client to use the proxy, SOCKS, or DNS listener. Install the generated root CA only on isolated test devices that you control.

For HTTPS inspection, the target domain must be allowlisted, MITM must be enabled for that rule, and the test client must trust the generated root certificate.

Domains and URLs

Match the traffic you want to control

Add domain rules before expecting body capture, mocks, scripts, or prompts. A rule can match a host such as one of these examples.

example.com
api.example.com
*.example.com

Use URL and path conditions in rules when you need behavior for one endpoint instead of every request on a host.

Raw answers

Return an exact HTTP response

A raw answer lets Core return a configured response without contacting the upstream server. Keep a blank line between headers and body.

HTTP/1.1 200 OK
Content-Type: application/json
X-App-Trust-Proxy: mock

{"ok":true}

When the rule matches, the traffic entry records that the answer came from a mock rule and shows the modification history.

Interaction prompts

Pause traffic for user input

A profile can define prompts for matching requests or answers. Core can capture a value from headers or body, extract a value with regex, show it to the operator, wait up to the configured timeout, and apply the edited value before traffic continues.

This is useful when a shared test profile needs an environment token, account identifier, feature flag, or response field that should be chosen by the person running the proxy.

Profiles

Export a reusable setup

Profiles are meant to make a lab reproducible. Export the rules, domain settings, scripts, raw answers, interaction prompts, capture preferences, and setup notes. Another user can import the profile and run Core with the same behavior.

Review profiles before sharing because they can contain scripts, hostnames, raw answers, and workflow notes that may reveal internal testing details.

Safety

Keep local trust material private

The generated root CA private key, captures, DNS logs, mock rules, scripts, and profiles should stay private. Do not expose the web UI, proxy listeners, DNS listener, generated certificates, or captured traffic store to the public internet.

Use passthrough for domains you do not need to inspect and remove trusted root certificates from test devices when the lab is finished.