Workspace URLs and routing
A workspace can expose the HTTP services running inside its container at public URLs. Each URL maps a host name and a container port to a browser-reachable address, optionally over TLS and optionally protected by authentication. You add URLs when you create or edit a workspace, in the External URLs section.
Trailer serves a workspace URL in one of two ways. Which one is used is decided automatically from the URL’s host. You do not pick it directly.
How a URL maps to a container port
Section titled “How a URL maps to a container port”A workspace URL has a few parts that matter for routing:
- Subdomain and Domain: together they form the host name a request is matched on, for example
app.example.com. The host is alwayssubdomain.domain. - Port: the port the service listens on inside the container. This is the routing target, not a published host port. No host port binding is required for a URL to work.
- TLS enabled: whether the public URL is served over
https.
When a request arrives for subdomain.domain, it is matched on that host and forwarded to the container on the configured port over an internal network, so nothing needs to be published on the host.
The two routing modes
Section titled “The two routing modes”Agent proxy
Section titled “Agent proxy”When a URL’s host is under the Trailer server’s own host (a subdomain of the server’s domain), the URL points back at the server itself. The server relays each request to the agent over the connection the agent already holds open, and the agent forwards it into the container. The reply travels back the same way.
This needs no reverse proxy on the host and no DNS beyond a subdomain that resolves to the server. It works out of the box, which makes it the simplest way to reach a workspace. The tradeoff is that traffic flows through the server rather than going straight to the host.
Traefik reverse proxy
Section titled “Traefik reverse proxy”When a URL uses a domain that is routed to the workspace’s host, a reverse proxy running on that host routes the request straight to the container. The server is not in the data path. This needs a domain pointed at the host and a reverse proxy configured there, and it supports its own TLS certificate issuance. Trailer integrates with Traefik for this mode. The details are in Traefik routing in depth below.
How the mode is chosen
Section titled “How the mode is chosen”You choose the mode indirectly, by picking the URL’s domain:
- A domain under the Trailer server’s own host is served through the agent proxy.
- A domain that resolves to the workspace’s host (with a reverse proxy configured on that host) is served through Traefik.
Each URL is evaluated on its own, so a single workspace can have some URLs served through the agent proxy and others through Traefik at the same time.
| Agent proxy | Traefik | |
|---|---|---|
| Setup required | None | Domain pointed at the host, plus a reverse proxy on the host |
| Data path | Through the server | Directly from the host to the container |
| DNS | A subdomain of the server’s host | A domain that resolves to the workspace’s host |
| Best for | Quick access, single-host setups | Many hosts, custom domains, higher traffic |
Domains
Section titled “Domains”A URL can only use a domain that is already registered on the workspace’s host. Domains are managed per host (see the Domains page). Each domain belongs to exactly one host, and domain host names are immutable once created.
When a workspace is created or updated, every URL is validated against the registered domains:
- The referenced domain must exist on the host.
- The requesting user must have view access to that domain.
- The full host (
subdomain.domain) must not already be in use by another workspace.
Traefik routing in depth
Section titled “Traefik routing in depth”This section applies only to URLs served through Traefik. Agent-proxy URLs need none of it.
Traefik integration is configured per host. A host chooses how the agent tells Traefik about each workspace, and it also carries the entry point that routers attach to and an optional certificate resolver used for TLS. Both are set on the host details page.
How routing is published
Section titled “How routing is published”There are three options for how a host publishes routing to Traefik:
- Off: the host does no Traefik routing.
- Container labels: the agent tags each workspace container with the routing information, and Traefik picks it up by watching containers. For each URL this includes a host-match rule on
subdomain.domain, the host’s entry point, the target container port, and the certificate resolver when one is configured. - Config files: the agent writes one routing config file per workspace into a directory that Traefik watches. The file declares the same routing for that workspace’s URLs. When a workspace ends up with no Traefik-routed URLs, its file is removed.
Networking between Traefik and the container
Section titled “Networking between Traefik and the container”So Traefik can reach the workspace without exposing host ports, the agent attaches both Traefik and the workspace to a dedicated per-workspace reverse-proxy network. The container is reachable on that network, and the published routing points Traefik at it there.
TLS is driven by Traefik, not by Trailer directly. A URL marked TLS-enabled is served over https, and its router attaches the host’s configured certificate resolver so Traefik can obtain a certificate. Certificate issuance (for example ACME / Let’s Encrypt) is configured in the Traefik instance’s own static configuration.
Managed Traefik container
Section titled “Managed Traefik container”A host can optionally let Trailer deploy and manage the Traefik container itself. When this is enabled the agent runs a Traefik container, gives it access to watch container labels, and mounts storage for the config directory and for certificates. The container image, name, published ports, and static configuration are all set on the host details page.
If managed deployment is left off, you are expected to run and configure Traefik yourself. Trailer still publishes the routing for it to consume.
Authentication
Section titled “Authentication”Independently of the routing mode, each URL has an access level:
- Public: no authentication. Anyone with the URL can reach the service.
- Basic: HTTP basic authentication with a username and password. The password is hashed and never stored in the clear.
- Internal: only signed-in Trailer users who have access to the URL can reach it.
The same access levels apply to both routing modes. On Traefik-routed URLs the protection is enforced by Traefik. On agent-proxy URLs it is enforced by the server. Either way the behavior is identical.
Changing a URL’s authentication takes effect promptly. A request made right after you save the change may briefly still use the previous setting while the new one propagates, so retry once if the old behavior lingers.