Routes and service discovery

An application declares its private upstream address and public path prefixes because the gateway must route without importing or statically configuring the application. The gateway builds its route table from live declarations.

Declare only served prefixes

export const app = defineApp({
  // required metadata
  baseUrl: "http://app-inventory:3000",
  routes: [
    "/api/inventory",
    "/app/inventory",
    "/admin/inventory",
    "/public/inventory",
  ],
});

An API-only application needs only its API prefix. Applications with special public paths declare those exact paths.

See Route conventions for the standard prefixes, reserved paths, and matching rules.

Do not serve HTML below /public. Cloud handles /public/* before the application router and returns a terminal asset response. Use a separate prefix such as /share/<id> for anonymous pages.

Mount the same paths in Hono

The gateway preserves the original path:

const router = new Hono()
  .route("/api/inventory", apiRoutes)
  .route("/app/inventory", pageRoutes);

Declaring a prefix does not create a Hono route. Mounting a Hono route does not publish it to the gateway.

Internal service address

baseUrl is the address used by the gateway:

baseUrl: "http://app-inventory:3000",

The hostname normally matches the Compose or Kubernetes service name.

Do not use localhost when the gateway runs in another container. localhost would refer to the gateway container itself.

Service registration

app.start() writes one registry entry containing:

• application identity and baseUrl;
• route prefixes;
• navigation and administration links;
• optional search, widget, setting, legal-link, and OpenAPI metadata.

The application refreshes the entry while it runs. A clean shutdown removes it. The gateway watches the registry and rebuilds its route table when entries change.

No static gateway rule is required for each application.

Diagnose an unreachable route

Check the path in this order:

1. Confirm the application process is running.
2. Confirm app.start() completed.
3. Resolve baseUrl from the gateway container.
4. Confirm the prefix is listed in routes.
5. Confirm the same path is mounted in Hono.
6. Check for a duplicate-prefix warning in gateway logs.

Use the target deployment's application and gateway health or log commands for the first two checks. Repository-specific development commands are maintainer tools, not part of the standalone application contract.

See Operations troubleshooting for registry and container failures.

Protect the destination

The gateway selects an upstream. It does not authenticate or authorize the request.

Use:

• Route policies for caller classes;
• Resource authorization for domain access;
• Public access for anonymous routes.