Skip to main content
A Route is a domain that reaches an Instance or a Node-local service. Orbit creates a Project Route for every Instance of a web-serving Project. The route family creates explicit Project Routes and custom proxy Routes, changes their targets, domains, and publication, and removes them. The Routes reference describes the Route record, domain selection, traffic setup, and the rules that refuse a change while an active Instance depends on a Route.

​
Commands

Every command accepts --json. Route, Project, Instance, and Cluster arguments are numeric IDs. Human lists show a table with every target of a pool. route:show shows a detail tree with identity, scope, targets, publication, lifecycle, and replacement fields. Requests show progress while they wait.

​
orbit route:create

Create an explicit app Route targeting an Instance, or create a custom proxy Route for a Node-local service.
In a terminal, Orbit lists available Instances for an omitted Instance ID and prompts for an omitted domain. If no Instances are available or selection is cancelled, it creates nothing. In noninteractive or JSON mode, provide both arguments for the app form. The app form creates and activates a Route for the Instance. The Instance implies the Project and scope. An inactive Instance returns route.target_inactive; an Instance already targeted by another Route returns route.target_conflict. An identical retry for an existing active Route returns that Route. With --web-root, the Instance keeps its own Route and gets another site. See Create and change targets and Serve several web roots. --upstream or --process selects the custom proxy form. Its first argument is the domain, and it needs --node. It cannot take an Instance or public publication. A successful custom proxy request converges its Node-local serving path.

​
orbit route:list

List the Routes on the Nodes you may address, with domain, kind (app, custom_proxy, or analytics_tracking), provenance, publication, scope, target or upstream, and status.

​
orbit route:show

Show one Route with its kind, generation basis, upstream or Process, lifecycle, and the failure fields of an unfinished change.

​
orbit route:update

Change the domain or the publication of an explicit Project Route, or the web root of a Route. Give at least one option. Send --web-root on its own.
A domain change creates a replacement Route and returns its ID. The current Route stays authoritative until cutover. A publication-only change keeps the Route ID. See Change an explicit domain and Publish the public edge.
During a domain change, route:show shows both Routes, replacement_step, failed_step, and error_code. Repeat the same request to resume. A different domain or publication request changes nothing.

​
orbit route:target:set

Set the Instance target, or send a complete production target set.
Without pool options, the command sets one target. With them, it sends the complete target set and a disposition for each detached Instance. Change a production target set lists the rules and error codes. A single-target request that would take an Instance from another Route, or detach an active Instance from its only Route, returns route.target_conflict and changes nothing. A production target set can take an Instance from another Route in the same Cluster.

​
orbit route:target:unset

Clear the target and keep the Route, its domain, scope, and publication.
Clearing an empty Route returns it unchanged. The Gateway returns route.target_conflict when clearing would leave an active Instance without a Route. On a replacement that never activated, it returns route.target_conflict and names route:destroy.

​
orbit route:destroy

Remove a Route and its DNS records, Caddy sites, certificates, and firewall rules. For a Route whose Instances are not active, also withdraw the PHP-FPM pools of its development Instances. See Remove a Route. On a pending or failed replacement Route that never activated, it abandons the domain change and keeps the Route it would replace. See Remove a replacement that never activated.
When a Node the removal changes does not answer, the Gateway returns route.node_unreachable. The message names the Node and --offline. With --offline, the response lists each skipped Node and its remaining steps under retained_on_nodes. Run orbit node:converge NODE once that Node answers. See Remove a Route from an unreachable Node.
The Gateway refuses removal with route.target_conflict while an active Instance depends on the Route. A replacement that never activated is the exception, because its Instance keeps the Route it replaces. Remove the Instance with instance:destroy instead. That removal deletes the Route when it removes the last target. The Gateway also refuses direct removal of analytics tracking Routes with route.tracking_managed; disable analytics on the Instance instead. A Route kind that cannot be destroyed returns route.kind_invalid.
route:destroy and route:target:unset resolve the Route and then ask for confirmation, with No selected. Pass --yes for automation, also with --json. Declining, Ctrl-C, or end of input returns input.cancelled and sends nothing. A call without a terminal and without --yes returns input.confirmation_required.
  • instance creates the Instances that Project Routes target, and accepts --domain for an explicit Route.
  • process creates the Node Process that a custom proxy Route can target.
  • cluster sets the Router that serves Cluster-scoped Routes.
  • dns points a TLD or a Route name at an address on a Mac.