Skip to main content

Use your own domain

A managed tunnel gives your gateway an address on permaura.app and Permaura runs the connector. If you would rather your gateway answered on a domain you own — gateway.yourcompany.com — you can, and Permaura stays out of the path entirely. It only needs to know the address, because that address becomes the audience agents authenticate against.

This is a bring your own setup. It replaces the managed tunnel rather than sitting alongside it: a gateway uses one or the other, never both.

What you need​

  • A domain you control the DNS for.
  • Somewhere the gateway can be reached: a tunnel you run yourself (Cloudflare Tunnel, ngrok, a Tailscale Funnel), or a server with a TLS reverse proxy in front of the gateway.
  • HTTPS. Not a preference: the address is an OAuth audience, and agents will refuse to sign in against a plain-HTTP one.
Use an HTTP tunnel or proxy, never a raw TCP forwarder

The gateway tells local traffic from remote traffic by the standard forwarding headers an HTTP tunnel or proxy stamps on every request. A raw TCP forwarder — ssh -R, a bare socat pipe — adds none, so remote traffic arrives looking local and reaches controls that must stay loopback-only.

1. Put your domain in front of the gateway​

The gateway listens on 127.0.0.1:7376 by default and speaks plain HTTP. Something has to terminate TLS and forward to it. Two common shapes:

If the gateway runs on a server, put a proxy in front. Caddy needs no TLS configuration — it obtains and renews a certificate for you:

gateway.yourcompany.com {
    reverse_proxy 127.0.0.1:7376
}

The nginx equivalent, once you hold a certificate:

server {
    listen 443 ssl;
    server_name gateway.yourcompany.com;

    ssl_certificate     /etc/letsencrypt/live/gateway.yourcompany.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/gateway.yourcompany.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:7376;
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

X-Forwarded-For is not optional. It is how the gateway knows a request came from outside the machine, and without it remote callers are treated as local.

Then point an A or AAAA record at the server and let the certificate issue.

Self-host on a cloud VM covers this end to end, including running the gateway as a service that survives a reboot.

2. Check it answers​

Before registering it, confirm the address reaches your gateway and not something else:

curl https://gateway.yourcompany.com/health

You want {"status":"ok","service":"permaura-gateway"}. A gateway tells an unauthenticated caller only that it is alive — the version and the rest of the health document need a token — so this response is exactly what a healthy public gateway should give a stranger.

If you get an error page instead, the DNS or the proxy is the thing to fix, not Permaura.

3. Register the address​

Permaura needs to know the address so it can be used as the sign-in audience.

  • Desktop app — Settings → Remote access → Advanced settings, choose custom domain, enter the hostname and press Update.
  • Console — the gateway's Remote access panel, under Advanced, in the bring-your-own field.

Saving it turns off any managed tunnel on that gateway, and the gateway relaunches so it serves the new audience.

Changing the address disconnects agents

The address is the audience. Every agent pointed at the old one stops being able to sign in until you update it there too.

What Permaura does and does not do​

It registers the URL as the audience agents authenticate against, and that is all. It does not issue your certificate, run your tunnel, or sit in the path of your traffic. The bytes go from the agent to your ingress to your gateway.

That also means the parts you own are yours to keep working: certificate renewal, the tunnel process staying up, DNS. If the address stops answering, agents stop connecting, and Permaura has no way to route around it.

Going back to a managed tunnel​

Turn remote access off and on again in the app or the console. It provisions a permaura.app address, and the custom one is forgotten. See Remote access.