Agent endpoints
An agent endpoint is what the devgate agent creates when it runs: it forwards traffic from a URL to a service on the agent’s machine, and goes away when the agent stops.
$ devgate http 8080
What follows http is the service: a port (8080, meaning
http://localhost:8080), or an address such as 192.168.1.2:80 or
myapp.test:8080.
Flags
| Flag | What it does |
|---|---|
--url | The public URL: your dev domain, a reserved domain, or https://name.internal. Without it — or with https://{$random}.devgate-free.run — a random URL. |
--traffic-policy-file | A Traffic Policy the edge runs before traffic reaches you. |
--pooling-enabled | Let other agents start on the same URL; traffic is load balanced. |
--host-header | The Host your service receives — rewrite or a name. See local vhosts. |
--basic-auth user:pass | Ask visitors for a password; repeat for more users. Same as a basic-auth rule. |
--cidr-allow, --cidr-deny | Let in or keep out IP ranges (restrict-ips). |
--verify-webhook <provider> --verify-webhook-secret <s> | Check webhook signatures at the edge (verify-webhook). |
--request-header-add, --request-header-remove, --response-header-add, --response-header-remove | Change headers on the way in or out (name:value). |
--ua-filter-allow, --ua-filter-deny | Allow or deny clients by a regular expression on their User-Agent. |
--oidc <issuer URL>, --oidc-client-id, --oidc-client-secret, --oidc-scope | Make visitors sign in with your OpenID Connect provider (openid-connect). |
--compression | Compress responses with gzip, Brotli or deflate, whichever the visitor’s browser prefers (compress-response). |
--upstream-protocol http2 | Speak HTTP/2 without TLS (h2c) to your service — for one that only speaks HTTP/2, such as a gRPC server. See below. |
--inspect=false | Don’t start the local inspector and agent API on 127.0.0.1:4040. |
--log, --log-format, --log-level | Where and how the agent logs. |
Flags become a Traffic Policy
The access, header and compression flags are shortcuts, as on ngrok: the agent writes them as Traffic Policy rules — addresses
first, then webhook signatures, then sign-in, then headers, and compression last — and puts them ahead of a
--traffic-policy-file’s own rules, so the two combine.
$ devgate http 8080 --basic-auth 'team:correct-horse' --cidr-allow 203.0.113.0/24 HTTP/2 to your service
$ devgate http 50051 --upstream-protocol http2
By default the edge speaks HTTP/1.1 to your service. With --upstream-protocol http2 — or
upstream.protocol: http2 in the config file, as on ngrok —
it speaks HTTP/2 without TLS (h2c, prior knowledge), trailers included: what a gRPC server, or any service that only speaks
HTTP/2, expects. The service has to accept h2c; one that speaks only HTTP/1.1 answers such an endpoint with an error.
Visitors reach the edge over HTTPS with HTTP/2 or HTTP/1.1. A gRPC call stays on HTTP/2 all the way to your service, trailers included, so any gRPC client calls the endpoint on port 443 as it would a gRPC server with TLS — unary and streaming calls alike. gRPC-Web and Connect clients, which also work over HTTP/1.1, can too.
$ grpcurl brave-otter-moon.devgate-free.run:443 list HTTP/2 requests show in the request log with their method, path and status, and count as requests as HTTP/1.1 ones do; the local inspector shows HTTP/1.1 exchanges only.
From a config file
The same settings can live in ~/.devgate/devgate.yml, one entry per endpoint, started with
devgate start <name> or --all. See the
config file.
Starting from the wizard
The New Endpoint wizard writes the command for you; the endpoint appears once the agent runs it:
-
With a Traffic Policy, save it as
policy.yamlin the folder you’ll run the agent from. The download lands in Downloads — move it, or point--traffic-policy-fileat it there. - Run the command and keep the terminal open.
- The wizard watches for the agent and says when the endpoint is online; then open it with View Endpoint.
The agent reads the policy file once, when it starts: after editing it, restart the agent. An agent endpoint lives as long as its agent — stop the agent and the endpoint goes away, and the wizard says the agent disconnected. Run the command again to bring it back.
From the dashboard
Each endpoint on the Endpoints page has a
⋯ menu, as on ngrok:
- Inspect Traffic — its requests in the Traffic Inspector.
- Agent Details — the agent running it: version, OS, IP address, device, when it started and its last heartbeat.
- View Traffic Policy — the policy it was started with.
- Stop Endpoint — the agent drops this endpoint now and keeps its other endpoints running; restarting the agent brings it back. Needs agent 0.20.0 or later — older agents are stopped with Ctrl+C.
Read only in the dashboard
An agent endpoint is whatever its command says. The dashboard shows its settings and policy but doesn’t change them: edit the command or the policy file and restart the agent. For an endpoint you manage centrally, use a cloud endpoint in front of it.