Skip to main content

Use your own domain

A managed tunnel gives your gateway an address on permaura.app: permaura.com creates the tunnel, and the gateway or the desktop app runs its connector on your machine. If you would rather your gateway answered on a domain you own (gateway.yourcompany.com), you can, and your agents reach it directly, with Permaura out of their path. It needs to know the address, because that address becomes the audience agents authenticate against, and the console and the Permaura app still reach the gateway through permaura.com, which relays their requests in memory and without logging them.

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, the Remote access card on the Local Gateway tab (press Modify first if remote access is already on). Pick custom domain in the Domain type dropdown, enter the hostname and press Enable (or Update).
  • Console: Settings → Gateway, on the gateway's card: Enable remote access (or Modify), pick custom domain in the Domain type dropdown, enter the hostname and press Enable (or Update).

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​

In the app or the console, press Modify, pick permaura.app in the Domain type dropdown and press Update. It provisions a permaura.app address, and the custom one is forgotten. See Remote access.

Last updated on