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

# Central hosting

> Host a shared Vexlo server and connect application hosts, browsers and coding agents.

A shared Vexlo server collects recordings from multiple application hosts and gives your team
one URL for the web UI and HTTP API. Each application host keeps its own SDK queue and relay.
The MCP server connects to the shared HTTP API on behalf of its agent client.

You operate the shared server. For a local installation, use
[Install and run](https://docs.vexlo.ai/deployment/install.md). To use either instance in a browser, follow
[Web UI](https://docs.vexlo.ai/ui.md).

## Deployment layout

```mermaid theme={"system"}
flowchart TD
  subgraph Applications[Application hosts]
    A[Application and SDK] --> Q[Host-local queue]
    Q --> R[Host relay]
  end
  R -->|HTTPS and ingest token| S[Shared Vexlo server]
  S --> D[(Server database and values)]
  B[Browser] -->|HTTPS and read token| S
  C[Agent client] --> M[MCP server]
  M -->|HTTPS and read token| S
  classDef component fill:#eff6ff,stroke:#64748b,color:#0f172a,stroke-width:1px;
  class A,Q,R,S,D,B,C,M component;
```

The SDK does not need the shared server URL or its credentials. It writes to the local queue;
the relay reads that queue and forwards records. Set the same `VEXLO_SPOOL_DIR` for the SDK
and relay on each host. Do not point applications on separate hosts at a shared queue directory.

## Prepare the server host

Complete [Build the binary](https://docs.vexlo.ai/deployment/install.md#build-the-binary) first. You also need:

* A persistent directory writable by the server process for its database and captured values.
* A DNS name reachable by the application hosts and readers.
* A TLS certificate and private key for that name, trusted by your clients and relay hosts.
* Network access to the server listener from those hosts.

Choose the storage location and configure the listener. Replace the paths below with absolute
paths on the server host; the certificate and key must already exist.

```sh theme={"system"}
export VEXLO_DATA_DIR=/srv/vexlo/data
export VEXLO_API_ADDR=0.0.0.0:8443
export VEXLO_TLS_CERT_FILE=/etc/vexlo/tls/fullchain.pem
export VEXLO_TLS_KEY_FILE=/etc/vexlo/tls/privkey.pem
mkdir -p "$VEXLO_DATA_DIR"
```

The UI and API share one listener. Supplying a certificate enables TLS.
Without TLS, a non-loopback listener is refused unless the transport check is explicitly
bypassed. Keep TLS enabled for this deployment.

## Issue credentials

Run token administration on the server host with the same `VEXLO_DATA_DIR`. For a team named
`platform`, create separate delivery and read credentials:

```sh theme={"system"}
umask 077
vexlo token create -role ingest -team platform > "$VEXLO_DATA_DIR/ingest-token.txt"
vexlo token create -role read -team platform > "$VEXLO_DATA_DIR/read-token.txt"
```

Give the ingest credential to the relays and read credentials to readers. A token's team scope
controls access to the records; a deployment environment label does not replace team scope.
For separately revocable relay credentials or restrictions on service and environment, issue
additional tokens using [Authentication](https://docs.vexlo.ai/deployment/authentication.md).

## Check and start the server

Check the configuration with an estimate of the incoming trace rate. The example below uses
`0.1` traces per second; replace that estimate with the rate you expect to record.

```sh theme={"system"}
vexlo check -expected-write-rate 0.1
```

Resolve any configuration or capacity failure before starting. The estimate is a planning
input, not a traffic limit. [Configuration](https://docs.vexlo.ai/deployment/configuration.md#capacity-check)
explains the check's fixed per-trace size estimate and the storage settings it evaluates.

Start the server with the same environment:

```sh theme={"system"}
vexlo serve
```

Retain the selected data directory across restarts. Configure your process supervisor to supply
the same paths and TLS settings; this command runs in the foreground.

## Connect application hosts

Install `vexlo` on each application host using the same build procedure. Configure that host's
relay with the shared server URL, its ingest token, and the queue directory used by its SDK.
For example, after securely placing the ingest credential in an application-host file:

```sh theme={"system"}
export VEXLO_ENDPOINT=https://vexlo.example.com:8443
export VEXLO_SPOOL_DIR=/var/lib/vexlo/spool
export VEXLO_INGEST_TOKEN_FILE=/etc/vexlo/ingest-token
export VEXLO_INGEST_TOKEN=$(cat "$VEXLO_INGEST_TOKEN_FILE")
export VEXLO_ENVIRONMENT=staging
mkdir -p "$VEXLO_SPOOL_DIR"
vexlo relay run
```

Replace the URL and paths for your deployment. The token file supports later reloads; the
environment variable supplies the startup credential. The file must contain the credential
itself, without the token command's `token:` label. The SDK and relay processes need access to
the selected queue directory. Configure the SDK using [Python SDK](https://docs.vexlo.ai/instrumentation/python.md).
The environment label comes from the relay; the service name comes from the SDK.

The relay health listener stays local to its host by default, at `127.0.0.1:9101`. Check it on
that host. A healthy relay does not establish that a request has reached the shared server;
verify an actual recording as well.

## Connect readers and verify delivery

On a reader's machine, set the shared URL and a read credential:

```sh theme={"system"}
export VEXLO_ENDPOINT=https://vexlo.example.com:8443
export VEXLO_TOKEN='YOUR_READ_TOKEN'
curl --silent --show-error --fail-with-body "$VEXLO_ENDPOINT/v1/whoami" \
  -H "Authorization: Bearer $VEXLO_TOKEN"
```

Open the same base URL in a browser and connect with the read token. No separate UI deployment
is required. Configure agent clients with `VEXLO_API_URL` set to that URL and `VEXLO_TOKEN` set
to a read token; see [Connect an agent](https://docs.vexlo.ai/agents/connect.md).

Record a request from an application host, then [search for it](https://docs.vexlo.ai/guides/search.md) in the shared
UI using its service, environment and identifier. Open the recording and confirm that calls
and captured values are available. This verifies the full path rather than only connectivity.

## Operate the shared instance

Keep server storage and each host's queue under separate capacity monitoring. Server call
metadata, full values and function history have different retention rules; host queues also
have limits during outages. Review [Retention](https://docs.vexlo.ai/deployment/retention.md) before choosing storage.

For a reverse proxy, keep the server's upstream listener on loopback when the proxy runs on
the same host. Forward both UI and API traffic. A TLS-terminating proxy and a loopback HTTP
upstream preserve the server's local transport rule. Header-trust mode is a separate access
configuration: it requires the proxy to authenticate readers and inject the configured trust
secret and team headers. Ingest requests still require ingest tokens.

See [Authentication](https://docs.vexlo.ai/deployment/authentication.md#transport-security) for the trust boundary and
[Configuration](https://docs.vexlo.ai/deployment/configuration.md) for supported settings.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.