Networking
Each Computer has an HTTPS website address and an SSH destination. For my-site, these are https://my-site.heaven.dev and my-site@heaven.dev. You can sign your team in to an internal tool, share a preview with a client or put a TCP service on the internet from the same Computer.
On this page
HTTP and TLS
#Heaven terminates HTTPS and forwards requests to an HTTP/1.1 port inside the Computer. WebSockets use the same address.
The application must listen on 0.0.0.0 or the Computer's network address. A loopback listener at 127.0.0.1 is reachable only from inside the Computer.
Set the website port for an application listening on port 8000:
heaven website my-site --port 8000The default port comes from the image.
Heaven sends X-Forwarded-Proto: https and X-Forwarded-Host with the visitor's hostname. Use these headers when constructing URLs and redirects. If the application accepts connections through other routes, restrict trusted proxy headers to the appropriate sources.
Website access
#Websites are private by default. The Computer's Sharing tab selects the audience:
| Setting | Audience |
|---|---|
| Private | People granted access to the Computer and visitors with a share link. |
| Organization | Signed-in members of the organization. |
| Public | Anyone on the internet. |
Site only grants website access. Site and SSH also grants root access inside the Computer. Organization policy can restrict external sharing.
Read the current grants:
heaven access my-sitePrograms can authenticate to private websites with a site token.
Share links
#A share link opens only the Computer's main website to anyone who has the link. Use one to share an internal preview with a client who doesn't have a Heaven account.
In the Computer's Sharing tab, choose Links → New link. Set the expiration and, if you want to limit access, the number of browsers that can use the link. Choose Create and copy to get the URL. Heaven shows it only when you create it.
Links expire after 30 days by default. Each browser counts once toward the limit. To end access early, choose Revoke in the link's menu. Revoking the link also ends site sessions opened through it.
Signed-in visitors
#Heaven signs visitors in to your private website. Your internal tool can read their identity from request headers to show each person's work or record who made a change.
| Header | When Heaven sends it |
|---|---|
X-Heaven-User-Id | The visitor is signed in through a Heaven browser session or authenticates with a site token tied to a user. |
X-Heaven-Email | The visitor is signed in through a Heaven browser session and has a verified primary email address. |
A signed-out visitor using a share link has neither header. Heaven strips all visitor-supplied X-Heaven- headers before forwarding the request, including spellings that use underscores in place of hyphens. If the app also accepts connections directly, trust the identity headers only on requests forwarded by Heaven's HTTPS proxy.
Development ports
#Ports 3000 through 9999 are available through HTTPS. For example, https://my-site.heaven.dev:5173 forwards HTTP and WebSocket requests to port 5173 inside the Computer.
Development ports require ownership or root access. Port 6080 is reserved for the browser desktop.
Use an SSH forward for other protocols or services listening on loopback.
Custom domains
#A custom domain routes to the Computer's website. Its DNS records point to the organization's Heaven address, so they remain valid when the Computer is renamed.
An organization can connect up to 50 domains. Several website names, such as app.example.com and preview.example.com, can share one connected domain. A subdomain you connect in its own right counts as a domain.
Request the DNS records for your domain:
heaven domain check app.example.com --computer my-siteAdd the returned records at your DNS provider, then register the domain:
heaven domain add my-site app.example.com
heaven domain view my-siteSubdomains use a CNAME. Root domains use the address records and ownership proof returned by the check.
For a domain behind Cloudflare's proxy, add the returned _acme-challenge CNAME with DNS only and set SSL/TLS to Full (strict). This record proves ownership and lets Heaven obtain the certificate. It must be the only record at that name: remove any TXT records another certificate provider left there.
Heaven verifies DNS and obtains an HTTPS certificate. Names awaiting DNS remain in a waiting state and are removed after seven days if verification fails. Certificates renew automatically.
The domain uses the Computer's website access setting. A domain assignment can route to a specific port or path.
Public ports
#Publish a TCP service such as a game server on a public port. Public ports are included in every plan. Heaven publishes them on a shared public address, or on a static address attached to the pool or the account. For a service listening on port 25565, run this from your local terminal.
heaven port add my-site 25565Heaven assigns a public port and returns the address and port clients connect to, such as 198.51.100.20:24117. Anyone on the internet can connect. Require authentication in the service itself to control who can use it.
Computer owners and organization admins can publish ports. Members can also publish with an Admin share or a grant for port add. If the organization restricts external sharing to admins, publishing requires organization admin authority or an organization-level grant for port add. Use a credential without command restrictions.
Pools in the same account on the same server share an allowance based on the capacity of the account's pools there that haven't been stopped. These are the allowances for a single plan.
| Plan | Public TCP ports |
|---|---|
| 1, Tiny | 5 |
| 2, Small | 6 |
| 3, Medium | 8 |
| 4, Big | 12 |
| 5–8, Huge through Giga | 20 |
Run heaven port view my-site to see the current allowance and the Computer's published ports. Use the assigned port number to close it to new connections.
heaven port remove my-site 24117Existing connections continue until they end or you stop the service.
Static addresses
#A static IPv4 address gives an application or pool a fixed internet address. It's an add-on at $7.50 per address per month (pricing). Buy an address for your account with heaven ip buy. Use the returned address in the command for your destination.
| Attach to | Command | What the address does |
|---|---|---|
| Computer | heaven ip attach ADDRESS my-site | Receives inbound TCP and UDP for the Computer. The Computer also uses the address for outbound internet traffic. |
| Pool | heaven ip attach ADDRESS --pool web | Carries outbound internet traffic and published TCP ports for Computers in the pool that have no address of their own. |
| Account | heaven ip attach ADDRESS --account | Does the same for the account's pools that have no address of their own. |
Use a Computer's own address and the service's port for direct access, including to a UDP service. Use a pool address when several Computers need the same outbound address on an allowlist. Services exposed directly on a Computer's static address need their own authentication to restrict access.
Detach with heaven ip detach ADDRESS to keep the address in your account for another attachment. When you detach a pool's address, its public ports move to the address the pool falls back to and keep their numbers. If the pool has nowhere to publish them, they close.
Release with heaven ip release ADDRESS --yes to give the address back and remove its attachment. For 12 hours, your account can buy it back with heaven ip buy --address ADDRESS. Heaven holds it for your account during that period, giving you time to remove it from allowlists before another account can get it.
Outbound and peer connections
#Computers connect to the internet over IPv4. To send email from a Computer, use Heaven's mail service.
Computers have isolated private networks. A peer integration authorizes one Computer to call another's private HTTP service.
To let my-site call api, create a peer integration from your local terminal.
heaven integration create http-proxy --name backend --target https://api.heaven.dev --peer --attachment computer:my-siteCall the private service from inside my-site.
curl https://backend.int.heaven.dev/The connection remains authorized while the integration exists and its creator retains access to the target.
Troubleshooting
#Read the Computer's state and website settings:
heaven view my-site
heaven access my-siteInside the Computer, inspect the listener and response:
ss -ltn
curl -v http://127.0.0.1:8000/For website access, ss must show the application listening on 0.0.0.0:8000 or the Computer's network address.
| Symptom | Check |
|---|---|
| Sign-in required or access denied | Account permissions and the website's audience. Development ports require root access. |
| Computer stopped, paused or waiting | The state message in Overview. |
| No listener or HTTP 502 | Application process, port and bind address. The application must serve plain HTTP. |
| HTTP 504 | Guest firewall and application response. |
| Custom domain fails | DNS records and the domain's verification state. |