Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.withnubo.com/llms.txt

Use this file to discover all available pages before exploring further.

Every Frame gets a Nubo-assigned domain out of the box. When you’re ready to go live you can attach a custom domain (anything like shop.mystore.com, api.mysite.io, or even a root domain) and Nubo will serve the Frame there with HTTPS. The exact DNS you’ll set up depends on whether the Frame runs on managed infrastructure (our cloud) or a self-hosted agent (your own server). The API is the same either way.

​
Add a domain from the dashboard

Open the Frame’s Settings tab and find the Custom domains section. Hit Add domain and the setup wizard walks you through four steps:
  1. Enter your hostname.
  2. Update DNS with the record we give you.
  3. Issuing TLS: we wait for your certificate to be issued and show progress while it happens.
  4. Live: the domain is serving traffic.
Most domains go from added to live in under a minute once DNS has propagated. HTTPS is on by default.

​
Add a domain via the API

curl -X POST https://shuttle.withnubo.com/v2/projects/<project_id>/spaces/<space_id>/frames/<frame_id>/domains \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"hostname": "shop.mystore.com"}'
The response tells you exactly which DNS records to create. The shape differs by infrastructure.

​
Managed Frames

You’ll create a single CNAME record pointing at the value Nubo gives you back: 
{
  "hostname": "shop.mystore.com",
  "dns": {
    "record_type": "CNAME",
    "record_name": "shop.mystore.com",
    "record_value": "<value returned by the API>"
  }
}
Add it to your registrar. Then tell Nubo to verify: 
curl -X POST https://shuttle.withnubo.com/v2/projects/<project_id>/spaces/<space_id>/frames/<frame_id>/domains/shop.mystore.com/verify \
  -H "Authorization: Bearer <your-token>"
Once DNS resolves to the right target, Nubo issues a free certificate and starts serving traffic at your hostname. You can call /verify again any time to re-poll.

​
Self-hosted agent Frames

Agent Frames provision TLS automatically - no verification step: 
{
  "hostname": "shop.mystore.com",
  "dns": {
    "record_type": "CNAME",
    "record_name": "shop.mystore.com",
    "record_value": "abc123.frames.example.com"
  }
}
Add the single CNAME, pointing at either the Frame’s system subdomain or the agent’s base domain - any name that resolves to the agent’s IP works. The first HTTPS request to the new hostname triggers cert issuance; after that, the Frame is live.
For agent Frames, port 80 must be reachable from the public internet for automatic TLS issuance to work. If it’s firewalled, TLS provisioning will fail.

​
Verify it’s working

Once DNS has propagated (usually seconds to a few minutes): 
curl -vI https://shop.mystore.com
You should get a 200 back with a valid certificate. dig shop.mystore.com should show your CNAME resolving to the right target.

​
Remove a domain

curl -X DELETE https://shuttle.withnubo.com/v2/projects/<project_id>/spaces/<space_id>/frames/<frame_id>/domains/shop.mystore.com \
  -H "Authorization: Bearer <your-token>"
This detaches the hostname from the Frame and stops serving traffic there. Remove the CNAME from your registrar once you’re done.

​
List attached domains

curl https://shuttle.withnubo.com/v2/projects/<project_id>/spaces/<space_id>/frames/<frame_id>/domains \
  -H "Authorization: Bearer <your-token>"
Returns the Frame’s system domain(s) plus every custom domain attached, with their current status (pending, active, or error).

​
Troubleshooting

​
Status stuck on pending

  • Managed: your CNAME isn’t resolving to the value Nubo handed you yet. Re-check your DNS (dig shop.mystore.com) and call /verify again.
  • Agent: the agent was offline when the domain was added. Restart the agent and the domain will apply on the next reconnect.

​
TLS certificate error

  • DNS propagated? dig shop.mystore.com should return the expected target.
  • Port 80 reachable? (Agent Frames only.) Port 80 needs to be open to the public internet for automatic TLS issuance.
  • Rate-limited? Certificate authorities cap issuance per hostname per week. If you’ve retried a lot, wait an hour.
For agent Frames, check the agent logs for TLS issuance details: journalctl -fu nubo-agent (Linux) or tail -f ~/Library/Logs/nubo-agent/stderr.log (macOS).

​
Hostname already registered

Each hostname belongs to one Frame at a time across all of Nubo. If you try to attach one that’s already in use, the API returns a 400. Remove it from the other Frame first, or pick a different hostname.