Quickstart

This path uses loopback authentication and a synthetic environment value.

It does not use a real vendor credential.

Run every step in a disposable directory and one terminal.

1. Prepare the declarations

mkdir -p .mint

cat > .mint/capabilities.yaml <<'EOF'
version: 2
capabilities: []
EOF

cat > .mint/policy.yaml <<'EOF'
version: 1
default: deny
rules:
  - actor: "local-agent"
    service: "127.0.0.1:18080"
    method: ["GET"]
    allowed_schemes: ["http"]
    path: "/echo"
    aliases: ["secret://example/default"]
    require_placeholder: true
    allow_private_network: true
    effect: allow
EOF

cat > .mint/call-guards.yaml <<'EOF'
version: 1
guards:
  - actor: "local-agent"
    service: "127.0.0.1:18080"
    max_calls: 10
    window_seconds: 60
EOF

The policy permits one synthetic destination.

The policy requires a Mint placeholder.

The default denies every other request.

The call guard bounds this local test window.

2. Start a synthetic receiver

Run this receiver in the current terminal.

python3 - <<'PY' &
from http.server import BaseHTTPRequestHandler, HTTPServer

class Receiver(BaseHTTPRequestHandler):
    def do_GET(self):
        value = self.headers.get("Authorization", "")
        body = ("received=" + value + "\n").encode()
        self.send_response(200)
        self.send_header("Content-Type", "text/plain")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

    def log_message(self, *_):
        pass

HTTPServer(("127.0.0.1", 18080), Receiver).serve_forever()
PY
RECEIVER_PID=$!

The receiver returns the header it receives.

It represents a vendor without using a real service.

3. Issue a development capability

Run this command before starting the broker.

cargo run -p mint-cli -- capability issue \
  --path .mint/capabilities.yaml \
  --actor local-agent \
  --expires-at "2030-01-01T00:00:00Z"

The command prints one raw capability in its own JSON result.

Read that value without saving it to a file.

read -r -s MINT_CAPABILITY
export MINT_CAPABILITY

The shell environment holds the temporary development capability.

Never put it in source, argv, or committed configuration.

4. Start Mint with synthetic custody

The generated value stays in the process environment.

export MINT_AUTH_MODE=shared-secret
export MINT_SECRET_BACKEND=env
export MINT_SECRET_EXAMPLE_DEFAULT="synthetic-only-value-$$"
export MINT_BIND_ADDR=127.0.0.1:4949
export MINT_POLICY_PATH=.mint/policy.yaml
export MINT_CAPABILITIES_PATH=.mint/capabilities.yaml
export MINT_CALL_GUARDS_PATH=.mint/call-guards.yaml
export MINT_AUDIT_LOG_PATH=.mint/audit.log
cargo run -p mint-cli -- serve > .mint/mint.log 2>&1 &
MINT_PID=$!
sleep 2

Do not print or copy the environment value.

5. Make the brokered request

Use Python to read the capability from the environment.

This keeps the temporary capability out of the request command's argv.

MINT_CAPABILITY="$MINT_CAPABILITY" python3 - <<'PY'
import os
import urllib.request

request = urllib.request.Request(
    "http://127.0.0.1:4949/proxy/http/127.0.0.1:18080/echo",
    headers={
        "X-Mint-Capability": os.environ["MINT_CAPABILITY"],
        "Authorization": "Bearer __mint.example.default__",
    },
)
with urllib.request.urlopen(request) as response:
    print(response.status)
    print(response.read().decode())
PY

The receiver gets the synthetic value.

The caller receives a scrubbed response.

The placeholder never leaves the intended request path.

6. Prove denial and readiness

Call a path without a matching rule.

MINT_CAPABILITY="$MINT_CAPABILITY" python3 - <<'PY'
import os
import urllib.error
import urllib.request

request = urllib.request.Request(
    "http://127.0.0.1:4949/proxy/http/127.0.0.1:18080/blocked",
    headers={
        "X-Mint-Capability": os.environ["MINT_CAPABILITY"],
        "Authorization": "Bearer __mint.example.default__",
    },
)
try:
    urllib.request.urlopen(request)
except urllib.error.HTTPError as error:
    print(error.code)
PY

The command must print 403.

The receiver must not receive a second request.

Run the readiness checks while Mint is running.

cargo run -p mint-cli -- doctor --self-test-alias secret://example/default

Doctor prints one JSON object per check.

Doctor returns a nonzero exit code when a required check fails.

Stop both processes after the run.

kill "$MINT_PID" "$RECEIVER_PID"