Routes - troqcloud

troqcloud A route in troqcloud is the configuration record that connects a public hostname to a deployed application. When you create a route, the platform’s proxy picks it up and starts forwarding traffic from that hostname to the app’s upstream URL. Routes also carry optional policy configuration for security headers, CORS, middleware, and routing rules. TLS certificate management is handled separately and is not yet available through the CLI. The commands documented here cover everything up to that boundary: route lifecycle, proxy policy, and operational inspection.

Creating and Updating a Route

troq routes upsert creates a new route or updates an existing one. The command is idempotent by route ID: running it again with the same --route-id updates the existing record rather than creating a duplicate. The minimum required fields are a route ID, an app ID, an upstream URL, and at least one hostname.

troq routes upsert \
  --route-id my-app-route \
  --app-id my-app \
  --upstream-url http://my-app.internal:3000 \
  --hostname app.example.com

Multiple hostnames can be attached to a single route by repeating --hostname:

troq routes upsert \
  --route-id my-app-route \
  --app-id my-app \
  --upstream-url http://my-app.internal:3000 \
  --hostname app.example.com \
  --hostname www.example.com

--strip-prefix removes a path prefix before forwarding the request to the upstream. This is useful when the app is mounted at a subpath but expects requests at the root:

troq routes upsert \
  --route-id api-route \
  --app-id api-app \
  --upstream-url http://api.internal:8080 \
  --hostname api.example.com \
  --strip-prefix /v1

--expected-version can be passed for optimistic concurrency control. If the current route version does not match, the upsert is rejected. This prevents overwriting a route that was modified between when you read it and when you write it.

Listing Routes

troq routes list returns all routes in the active workspace. You can filter by app with --app-id.

troq routes list
troq routes list --app-id my-app

Route Status

troq routes status shows the current apply state of a single route, including whether it has been picked up by the proxy and any pending changes.

troq routes status --route-id my-app-route

Effective Configuration

troq routes effective-config returns a summary of the merged route configuration currently active on the proxy, including the total route count, the configuration fingerprint, and apply statistics. This is useful for verifying that a recent upsert has been applied and how long it took.

troq routes effective-config

Apply Errors

troq routes apply-errors lists the most recent route configuration errors that the proxy encountered during apply. If a route upsert appears to have no effect, this command shows whether an error was recorded during processing.

troq routes apply-errors
troq routes apply-errors --limit 20

Route History

troq routes history-query returns the change history for routes in the workspace. You can narrow by app or by a specific route ID.

troq routes history-query
troq routes history-query --app-id my-app
troq routes history-query --route-id my-app-route

Deleting a Route

troq routes delete removes a single route by ID. This is a confirmed operation.

troq --yes routes delete --route-id my-app-route

After deletion, the proxy stops forwarding traffic for the hostnames that were attached to that route. If the app is still running but all its routes are deleted, it becomes unreachable from the public internet until a new route is created.

Decommissioning Routes for an App

troq routes decommission removes all routes associated with a given app in the workspace. This is the right command when you are retiring an application entirely and want to clean up its proxy configuration in one step rather than deleting routes one by one.

troq --yes routes decommission --app-id my-app

You can also pass --route-id to decommission a single route through this path, which behaves like delete but goes through the decommission flow.

Security Headers

Security headers are set per route through flags on upsert. They are applied by the proxy to every response on that route.

troq routes upsert \
  --route-id my-app-route \
  --app-id my-app \
  --upstream-url http://my-app.internal:3000 \
  --hostname app.example.com \
  --security-content-type-nosniff \
  --security-frame-options SAMEORIGIN \
  --security-referrer-policy strict-origin-when-cross-origin \
  --security-hsts-max-age-secs 31536000 \
  --security-hsts-include-subdomains \
  --security-force-https-redirect

The --security-allowed-method flag restricts which HTTP methods the proxy accepts on this route. Requests with other methods are rejected before reaching the upstream.

  --security-allowed-method GET \
  --security-allowed-method POST

CORS

CORS policy is configured through the --cors-* flags on upsert. The proxy handles CORS preflight responses and injects the appropriate headers on all responses matching the route.

troq routes upsert \
  --route-id api-route \
  --app-id api-app \
  --upstream-url http://api.internal:8080 \
  --hostname api.example.com \
  --cors-allow-origin https://app.example.com \
  --cors-allow-method GET \
  --cors-allow-method POST \
  --cors-allow-header Authorization \
  --cors-allow-header Content-Type \
  --cors-allow-credentials \
  --cors-max-age-secs 86400

Middleware

Middleware flags control request and response header manipulation, rate limiting, IP filtering, and auth forwarding. They are all applied at the proxy layer before the request reaches the upstream.

troq routes upsert \
  --route-id my-app-route \
  --app-id my-app \
  --upstream-url http://my-app.internal:3000 \
  --hostname app.example.com \
  --middleware-add-request-header X-Forwarded-App=my-app \
  --middleware-strip-request-header X-Internal-Token \
  --middleware-rate-limit-requests-per-minute 200 \
  --middleware-ip-deny-cidr 10.0.0.0/8

--middleware-auth-forward-url enables auth forwarding: the proxy sends each incoming request to the specified URL for authorization before forwarding to the upstream. If the auth endpoint returns a non-2xx response, the request is rejected.

Routing Policy

Routing policy controls how the proxy selects upstreams, handles retries, and matches requests to routes. --routing-upstream-target allows weighted load balancing across multiple upstream URLs. Each target is specified as URL@WEIGHT, where weight defaults to 1 if omitted.

  --routing-upstream-target http://my-app-v1.internal:3000@7 \
  --routing-upstream-target http://my-app-v2.internal:3000@3

This sends 70% of traffic to v1 and 30% to v2, which is the standard pattern for gradual rollouts. --routing-path-prefix restricts the route to requests matching specific path prefixes. --routing-header-equals and --routing-query-equals further narrow matching by request header or query parameter values. Retry configuration:

  --routing-retry-attempts 3 \
  --routing-retry-backoff-ms 100

Active health checking:

  --routing-active-healthcheck-path /healthz \
  --routing-max-consecutive-failures 5

Sticky sessions route repeat visitors to the same upstream based on a cookie value:

  --routing-sticky-session-cookie session_id

TLS Configuration

TLS certificate provisioning and mode configuration exist in the route policy model (--tls-mode, --tls-cert-mode) but are not yet enforced through the CLI. This section will be completed when TLS management is available end-to-end through troq routes. For now, TLS configuration should be managed through the platform web interface.

Output Formats

All routes commands support --output table, --output json, and --output jsonl.

troq routes list --output json
troq routes effective-config --output jsonl

Permission Requirements

Read operations (list, status, effective-config, apply-errors, history-query) require routes.read. Write operations (upsert, delete, decommission) require routes.write. You can verify your access with:

troq rbac check --permission routes.write

Last Updated: 2026-05-11