Cloudflare Tunnel on StartOS

Upstream docs: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/

Everything not listed in this document should behave the same as upstream cloudflared. If a feature, setting, or behavior is not mentioned here, the upstream documentation is accurate and fully applicable.

Cloudflare Tunnel (cloudflared) creates an outbound-only connection from your StartOS server to the Cloudflare edge network, allowing you to expose services publicly via your own domain without opening any inbound ports or configuring a router.

Upstream repo: https://github.com/cloudflare/cloudflared

---

Table of Contents

• Image and Container Runtime
• Volume and Data Layout
• Installation and First-Run Flow
• Configuration Management
• Network Access and Interfaces
• Actions
• URL Plugin
• Backups and Restore
• Health Checks
• Dependencies
• What Is Unchanged from Upstream
• Limitations and Differences
• Quick Reference for AI Consumers

---

Image and Container Runtime

• Base image: cloudflare/cloudflared:2026.3.0 copied into debian:12-slim
• Architectures: x86_64, aarch64 (aarch64 emulated if missing)
• Entrypoint: cloudflared tunnel --credentials-file /root/.cloudflared/<tunnel-id>.json run <tunnel-id>
• Autoupdate disabled via --no-autoupdate

Volume and Data Layout

All persistent data is stored in the main volume:

Path	Contents
/root/data/start9/config.yaml	Package store with selected tunnel, logged-in DNS zones, and managed routes
/root/data/start9/login-url.txt	Temporary Cloudflare authorization URL during login flow
/root/data/.cloudflared/zone-<zone-id>.pem	Zone-specific Cloudflare origin certificate
/root/data/.cloudflared/<tunnel-id>.json	Tunnel credentials file used to run cloudflared

Installation and First-Run Flow

1. Login to Cloudflare by running the Login to Cloudflare action.
2. Open the returned authorization URL and approve access for one DNS zone.
3. Repeat the login action if you want this package to manage additional DNS zones.
4. Run Select Tunnel to choose an existing tunnel or create a new one.
5. The package stores the tunnel credentials automatically and starts cloudflared.

No manual token or credentials-file management is required.

Configuration Management

• The package stores the selected tunnel, logged-in DNS zones, and managed routes in start9/config.yaml.
• Tunnel ingress is managed through the Cloudflare API.
• After selecting a tunnel, the package retrieves the credentials file automatically with cloudflared tunnel token --cred-file ....
• DNS record management uses the zone-specific origin certificate for the selected zone.
• If hostnames already exist on the tunnel in Cloudflare, use Import Public Hostnames before making further edits in StartOS so those routes are brought into the package store.

Network Access and Interfaces

• Metrics - Prometheus metrics endpoint at http://cloudflared.startos:20241/metrics (internal only)
• All public traffic is proxied through the Cloudflare edge. No inbound ports need to be opened on your router.

Actions

Action	When available	Purpose
Login to Cloudflare / Add DNS Zone	Always	Start the Cloudflare login flow and authorize one DNS zone at a time
Select Tunnel	When at least one zone is configured	Choose an existing tunnel or create a new one
Remove DNS Zone	When zones exist	Remove a DNS zone from this package without deleting existing Cloudflare records
Import Public Hostnames	Always	Import existing Cloudflare tunnel hostnames into the StartOS-managed route list
Managed Public Routes	Always	Show the selected tunnel, managed DNS zones, and application routes

URL Plugin

Cloudflare Tunnel registers as a url-v0 URL plugin. Any other installed service can add a public Cloudflare hostname directly from its StartOS URL list.

Adding a hostname:

• Open any service → URLs → Add URL → select Cloudflare Tunnel
• Enter a subdomain and choose one of the logged-in DNS zones
• The package updates the Cloudflare tunnel ingress configuration automatically
• It also tries to create the DNS CNAME automatically
• If the DNS step fails, the route is still added and the action returns the manual fallback: hostname → <tunnelID>.cfargotunnel.com (proxied)

Removing a hostname:

• Open the service → URLs → remove the Cloudflare URL
• The package removes the ingress rule from the tunnel configuration
• It also tries to delete the matching DNS record and returns a warning if manual cleanup is still needed

Importing existing dashboard routes:

• If routes already exist on the tunnel in Cloudflare, run Import Public Hostnames
• Matching routes are added to the package store so StartOS can manage and display them

Backups and Restore

The entire main volume is backed up, including zone certificates, tunnel credentials, selected tunnel info, DNS zone info, and managed ingress entries. After restore, the service can resume using the same tunnel and managed routes.

Health Checks

• Cloudflare tunnel - polls http://cloudflared.startos:20241/metrics
• The service is considered healthy when the metrics endpoint responds successfully

Dependencies

None.

What Is Unchanged from Upstream

• Cloudflare Tunnel still uses your existing Cloudflare account, Zero Trust tunnel model, and DNS zones.
• Advanced tunnel settings that are not described here should still be managed exactly as documented in the upstream Cloudflare documentation.

Limitations and Differences

1. One selected tunnel per package instance - this package runs one cloudflared tunnel at a time.
2. No tunnel management UI - tunnels are selected or created through StartOS actions, not a web UI. For advanced tunnel settings, use the Cloudflare Zero Trust dashboard.
3. Import before editing dashboard-managed routes - if routes already exist in the Cloudflare dashboard, import them into StartOS first so later edits here do not overwrite unknown entries.
4. DNS automation can still need manual fallback - if a DNS record already exists or Cloudflare rejects the change, the package returns the manual CNAME fallback instead of silently failing.
5. Autoupdate disabled - --no-autoupdate is set; updates are delivered via new package versions.
6. Metrics endpoint is internal only - the Prometheus metrics endpoint is not proxied through the tunnel.

---

Quick Reference for AI Consumers

package_id: cloudflared
upstream_version: 2026.3.0
image: cloudflare/cloudflared:2026.3.0
architectures: [x86_64, aarch64]
volumes:
  main:
    - /root/data/start9/config.yaml
    - /root/data/start9/login-url.txt
    - /root/data/.cloudflared/zone-<zone-id>.pem
    - /root/data/.cloudflared/<tunnel-id>.json
ports:
  metrics: 20241
dependencies: none
startos_managed_env_vars: []
actions:
  - cloudflare-login
  - select-tunnel
  - remove-zone
  - import-public-hostnames
  - managed-overview