> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Routes

> Manage project routes that map domains and paths to rooms or managed agents.

Routes map a domain to either room HTTP paths or a managed agent websocket.

Use them when you want a stable URL for something running inside a room, such as a web app or HTTP integration.

This is the normal way to publish an HTTP service from a room. A common pattern is: an agent or service creates a web app in the room, serves it on a published port, and then a route gives that app a stable URL.

Routes can front either a fully public site or a private app protected by MeshAgent. For browser apps, MeshAgent can act as an identity-aware proxy in front of your service: it authenticates the user, checks that they are allowed into the room, and only then forwards the request to your app.

For deployment basics, see [Service YAML](../services/deployment/deploy_services). Routes are managed from the [MeshAgent CLI](../reference/meshagent_cli_help).

## How routes work

* A service in the room listens on an HTTP port.
* That port is marked as `published` in the service config.
* The route maps a domain and one or more paths to that room and published port.
* When a request arrives, MeshAgent matches the route path, resolves the room and port, applies the port's security rules, and then proxies the request to the service.

## Create a route

Use a MeshAgent-managed domain such as `*.meshagent.app`:

1. Deploy a service that exposes an HTTP endpoint and marks its port as published.
2. Create a route:

```console theme={null}
meshagent route create --room my-room --port 5002 --domain my-app.meshagent.app
```

3. The route is ready as soon as it is created.

You can also create or update a route from a RouteSpec file:

```yaml theme={null}
kind: Route
version: v1
metadata:
  name: my-app
  annotations: {}
domain: my-app.meshagent.app
backend:
  room:
    name: my-room
paths:
  - path: /
    pathType: prefix
    targetPort: 5002
```

```console theme={null}
meshagent route create -f route.yaml
meshagent route update my-app.meshagent.app -f route.yaml
```

Managed agent routes use an agent backend and expose the agent websocket on the route domain:

```yaml theme={null}
kind: Route
version: v1
metadata:
  name: my-agent
  annotations: {}
domain: my-agent.meshagent.app
backend:
  agent:
    name: my-agent
```

## Mark the port as published

In your service config, the HTTP port must be marked as published:

```yaml theme={null}
ports:
  - num: 5002
    type: http
    published: true
```

## Public and private published ports

`published: true` makes a port routable from a route.

`public` controls whether that routed URL is open to the internet or protected by MeshAgent:

* `public: true`: MeshAgent forwards requests without requiring room authentication.
* `public: false`: MeshAgent requires the caller to authenticate before the request can reach the app.
* If you omit `public`, the port is treated as private.

For API clients and server-to-server callers, a private published port expects a participant token:

```http theme={null}
Authorization: Bearer <participant-token>
```

That token must be valid for the room. If the caller does not have access to the room, MeshAgent rejects the request before it reaches your app.

## Integrated security for browser apps

For browser-based apps, use cookie validation so MeshAgent behaves like an identity-aware proxy in front of your route. This is the easiest way to publish a private app without making the app itself handle MeshAgent tokens directly.

```yaml theme={null}
ports:
  - num: 5002
    type: http
    published: true
    public: false
    liveness: /healthz
    annotations:
      meshagent.request.validation.method: cookie
```

You can set `meshagent.request.validation.method: cookie` on the port or on a specific endpoint. Endpoint annotations override port annotations.

With that configuration, the request flow looks like this:

1. A user visits the routed URL.
2. If they do not already have a valid MeshAgent IAP session for that route, MeshAgent redirects the browser to sign in.
3. After sign-in, MeshAgent stores a secure, HTTP-only session cookie and retries the request through the route.
4. On each request, MeshAgent validates that the session still maps to a participant token for the target room.
5. If the user is not allowed in the room, the request is rejected before it reaches your app.

This gives you a stable URL with MeshAgent-managed authentication and room-level authorization in front of the service.

For normal browser navigation, unauthenticated `GET` requests are redirected into the login flow automatically. Non-`GET` requests without a valid session are rejected until the browser has signed in.

## Headers your app receives

When a request passes through cookie-based IAP, MeshAgent removes the internal `__meshagent_iap` cookie before forwarding the request to your app and adds trusted identity headers:

| Header                  | Meaning                                                                                                 |
| ----------------------- | ------------------------------------------------------------------------------------------------------- |
| `X-MESHAGENT-USER`      | The participant token `name`, typically the signed-in user's email or display identity.                 |
| `X-MESHAGENT-API-SCOPE` | The participant token API permissions, serialized as JSON. If the token has no API grant, this is `{}`. |

These headers are intended for the destination app to consume.

MeshAgent also strips any client-supplied `X-MESHAGENT-USER` or `X-MESHAGENT-API-SCOPE` headers before forwarding the request, so callers cannot spoof them without actually going through MeshAgent IAP.

## Queue-backed routes

Routes are not limited to proxying traffic into an HTTP app. They can also turn incoming HTTP requests into queue messages for agents or workers inside the room.

This is useful when you want:

* a stable public URL
* no always-on HTTP app inside the room
* an internal queue that workers can process asynchronously

When `meshagent.request.queue` is configured on the matched port or endpoint, MeshAgent enqueues the request body instead of proxying the request to a destination app.

```yaml theme={null}
ports:
  - num: 5002
    type: http
    published: true
    public: false
    annotations:
      meshagent.request.queue: inbound-events
      meshagent.request.validation.method: bearer
```

With that configuration:

1. A request arrives at the route.
2. MeshAgent validates the caller using the configured route auth method.
3. If validation succeeds, MeshAgent publishes the request body to the queue.
4. MeshAgent returns `202 Accepted`.

Today the queued message payload is:

```json theme={null}
{"body":"<raw request body text>"}
```

### Required annotations

| Annotation                            | Purpose                                                                                 |
| ------------------------------------- | --------------------------------------------------------------------------------------- |
| `meshagent.request.queue`             | Queue name to publish into.                                                             |
| `meshagent.request.validation.method` | Optional request validation method. Supported values are `bearer`, `jwt`, and `cookie`. |

You can place these annotations on the port or on a specific endpoint. Endpoint annotations override port annotations.

Queue-backed routes must remain non-public. They are intended for authenticated ingress handled by MeshAgent, not open anonymous forwarding.

## Liveness and startup behavior

`liveness` is the HTTP path MeshAgent uses to decide when a published port is actually ready to serve traffic.

```yaml theme={null}
ports:
  - num: 5002
    type: http
    published: true
    liveness: /healthz
```

When a request hits a route and MeshAgent cannot connect to the target port yet, it checks the `liveness` URL and waits for it to return `2xx`. Once the service is live, MeshAgent retries the original request.

This matters during startup, cold starts, and restarts:

* With a liveness URL, MeshAgent can wait for the app to finish booting instead of immediately failing the first request.
* Without a liveness URL, an early request is more likely to fail with a bad gateway while the process is still starting.

You should give published HTTP ports a liveness URL that is:

* Cheap to evaluate.
* Available without external user auth.
* Wired to real readiness, not just process start.

A good pattern is `/healthz` or `/ready` returning `200` only after the app is ready to serve the same traffic the route will send.

## Manage routes

```bash theme={null}
meshagent route list
meshagent route get my-app.meshagent.app
meshagent route update my-app.meshagent.app --port 5003
meshagent route delete my-app.meshagent.app
```

To create or update a route, you need permission to administer the target room.

## Related docs

* [Feeds](./feeds)
* [Projects](./projects)
* [Service YAML](../services/deployment/deploy_services)
* [MeshAgent Image](../services/containers/meshagent_image)
* [Participant Tokens](../rest_api/participant_tokens)