Access, hostnames, and TLS

An application becomes publicly reachable when it has at least one access entry. An access entry connects a port on a workload to a hostname on the internet, and chooses the protocol and the TLS strategy that bridges the two.

spec:
  access:
    - name: public
      type: https
      target: { workload: web, port: http }
      hostname: { generated: true }
      tls: { managedBy: edgible }
      policies:
        auth: { mode: none }

This page walks through each piece.

Protocols

Edgible supports four access protocols today:

type	What it does	When to use
https	TLS terminated at Caddy on the serving device; HTTP forwarded to the workload.	The default for any web app or HTTP API.
http	Plain HTTP forwarded to the workload over the WireGuard tunnel; no TLS.	Internal-only apps where the WireGuard layer is sufficient encryption, or for testing.
tcp	Raw TCP byte stream forwarded over the tunnel — the gateway does not inspect or modify the bytes.	Databases, custom protocols, anything non-HTTP.
udp	Raw UDP datagrams forwarded over the tunnel.	Game servers, DNS, anything UDP-native.

For https, the platform handles TLS. For tcp and udp, your workload is responsible for any encryption it wants — the gateway is a dumb pipe.

Hostnames

A hostname tells the gateway which traffic belongs to this access entry. There are two kinds.

Generated

hostname: { generated: true }

Edgible mints a hostname under a platform-owned domain (something like <app-slug>-<short-id>.edgible.app). The hostname is stable for the lifetime of the application — it doesn’t change on redeploy. Use this for quick prototypes, internal services, anywhere you don’t need a custom name.

Custom

hostname: { custom: api.example.com }

Use any hostname you control. You’re responsible for pointing DNS at the gateway (Edgible will give you the target record at deploy time). Once DNS resolves, the certificate is issued and HAProxy starts routing.

A single access entry can have multiple hostnames if you list them — both api.example.com and api.example.net can route to the same workload port.

TLS

For https access, you choose how the certificate is obtained.

Managed (the default)

tls: { managedBy: edgible }

Edgible orders the certificate from a public CA, validates the domain through HTTP-01 (for custom domains) or via the platform’s wildcard infrastructure (for generated domains), installs it on the serving device’s Caddy, and rotates it before expiry. You don’t see the cert; the platform handles its lifecycle.

This is what you want unless you have a specific reason to do otherwise.

Auth policies

Every access entry can specify an authentication mode that runs before the request reaches your workload:

policies:
  auth: { mode: none }

Four modes are supported:

• none — anyone with the URL can reach the service. Use for genuinely public endpoints.
• org — the requester must present a valid Edgible session for a member of your organization. Use for internal tools.
• api-key — the requester must present a bearer token issued by edgible application api-keys create. Use for programmatic access.
• short-code — the requester must present a short-code token (rotating, time-bounded, optionally usage-capped). Use for short-lived shareable access.

The check happens at Caddy on the serving device, before the request reaches your workload. A missing or invalid credential returns 401 without your code seeing the request at all. See Authentication modes for the details of each.

Multiple access entries on one application

An application can have several access entries — for example, a public read API and an internal admin UI on the same workload, with different policies:

spec:
  workloads:
    - name: app
      type: compose
      composeFile: ./compose.yml
      ports:
        - { name: public, containerPort: 8080, protocol: tcp }
        - { name: admin, containerPort: 9090, protocol: tcp }
  access:
    - name: api
      type: https
      target: { workload: app, port: public }
      hostname: { custom: api.example.com }
      tls: { managedBy: edgible }
      policies: { auth: { mode: api-key } }
    - name: admin
      type: https
      target: { workload: app, port: admin }
      hostname: { custom: admin.example.com }
      tls: { managedBy: edgible }
      policies: { auth: { mode: org } }

Each access entry gets its own hostname, certificate, and policy.