wardgate-proxy

name: wardgate-proxy description: > Use wardgate-proxy to call APIs through Wardgate. Use when the agent runs behind a local wardgate-proxy and needs to make HTTP requests to external services. The agent uses any HTTP client (curl, requests, fetch) pointing at the proxy address -- no special binary needed. compatibility: Requires wardgate-proxy running on a known local address (default 127.0.0.1:18080).

wardgate-proxy

A local reverse proxy that transparently injects the agent key into every request to a Wardgate server. The agent makes plain HTTP requests to the proxy using any HTTP client -- no special binary, no shell access, no restarts required.

How it works

Your HTTP request → http://127.0.0.1:18080/todoist/tasks
  → wardgate-proxy injects agent key
    → https://wardgate.example.com/todoist/tasks (with Bearer <agent-key>)
      → response streamed back to you

The proxy handles authentication automatically. You never see or manage the agent key.

Key constraints

• Fixed server -- all requests go to the Wardgate server configured in the proxy. You cannot change the destination.
• Auth is automatic -- do not pass Authorization headers. Any you send will be overwritten by the proxy.
• Access control is server-side -- Wardgate's policy engine decides what's allowed. If a request is denied, the response will tell you why.

Discovery -- always start here

Before making requests, discover what endpoints are available:

curl http://127.0.0.1:18080/endpoints

Returns JSON with name, description, upstream, and docs_url for each endpoint. Use the endpoint name as the first path segment in all requests.

Making requests

Use any HTTP client. The proxy address is http://127.0.0.1:18080 by default.

curl

# GET
curl http://127.0.0.1:18080/todoist/tasks

# POST with JSON body
curl -X POST -H "Content-Type: application/json" \
  -d '{"content":"Buy milk"}' \
  http://127.0.0.1:18080/todoist/tasks

# PUT
curl -X PUT -H "Content-Type: application/json" \
  -d '{"content":"Buy oat milk"}' \
  http://127.0.0.1:18080/todoist/tasks/123

# DELETE
curl -X DELETE http://127.0.0.1:18080/todoist/tasks/123

Python

import requests

BASE = "http://127.0.0.1:18080"

# GET
tasks = requests.get(f"{BASE}/todoist/tasks").json()

# POST
requests.post(f"{BASE}/todoist/tasks", json={"content": "Buy milk"})

Node.js

const BASE = "http://127.0.0.1:18080";

// GET
const resp = await fetch(`${BASE}/todoist/tasks`);
const tasks = await resp.json();

// POST
await fetch(`${BASE}/todoist/tasks`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ content: "Buy milk" }),
});

Custom headers

All headers you send (except Authorization and X-Forwarded-For) are forwarded to the Wardgate server and then to the upstream API. Use this for Content-Type, Accept, or any other headers the upstream expects.

curl -H "Accept: application/json" \
  -H "X-Request-Id: req-123" \
  http://127.0.0.1:18080/my-endpoint/resource

Sealed credentials

If the endpoint is configured for sealed credentials, you can send encrypted headers via X-Wardgate-Sealed-* prefixed headers. The Wardgate server decrypts them before forwarding to the upstream.

# Encrypt a credential with the endpoint's public seal key, then send it:
curl -H "X-Wardgate-Sealed-Authorization: <base64-encrypted-value>" \
  http://127.0.0.1:18080/my-endpoint/resource

Allowed sealed headers: Authorization, X-Api-Key, X-Auth-Token, Proxy-Authorization. The Wardgate server strips the X-Wardgate-Sealed- prefix after decryption and sets the real header.

Streaming and SSE

The proxy supports Server-Sent Events and chunked transfer encoding. Responses are flushed immediately -- no buffering.

curl -N http://127.0.0.1:18080/my-endpoint/events

Troubleshooting

Important rules

1. Always call /endpoints first to discover what's available before guessing paths.
2. Never fabricate endpoint paths -- use only what discovery returns.
3. Do not pass Authorization headers -- auth is handled by the proxy.
4. Respect denials -- if a request is denied by policy, do not attempt workarounds.
5. Use the proxy address for all external service requests -- do not call upstream APIs directly.