> ## 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.

# Install and run Vexlo

> Build the server binary, configure storage and start the server and relay.

A Vexlo deployment includes a server that stores execution data and a relay on each application
host that forwards SDK records. Both processes use the `vexlo` binary. This procedure builds
that binary from source and starts an authenticated local deployment.

```mermaid theme={"system"}
flowchart TD
  A[Application SDK] --> Q[Local queue]
  Q --> R[Host relay]
  R --> S[Vexlo server]
  S --> U[Web UI]
  S --> H[HTTP API]
  H --> M[MCP server]
  classDef component fill:#eff6ff,stroke:#64748b,color:#0f172a,stroke-width:1px;
  class A,Q,R,S,U,H,M component;
```

## Prerequisites

Install Git, Go, npm, curl, Node.js 22.12 or later, and a C compiler for the SQLite driver. The Go
module selects toolchain `go1.27.3` through `go.mod`. The server build includes its web UI.

The SDK and MCP have separate installation instructions under
[Python SDK](https://docs.vexlo.ai/instrumentation/python.md) and [Connect an agent](https://docs.vexlo.ai/agents/connect.md).

The commands below use loopback ports `8080` and `9101`; select different addresses in
[configuration](https://docs.vexlo.ai/deployment/configuration.md) if those ports are occupied.

## Build the binary

From your chosen installation directory:

```sh theme={"system"}
git clone https://github.com/vexlo-ai/vexlo.git
cd vexlo
(cd web && npm ci && npm run build)
CGO_ENABLED=1 go build -o bin/vexlo ./cmd/vexlo
export PATH="$PWD/bin:$PATH"
cd ..
```

The web build must finish before the Go build: the binary embeds `web/dist`. Add the absolute
`vexlo/bin` directory to your shell or process environment when using the binary later.

## Select storage directories

Keep server storage and the SDK's local queue in separate directories. From the installation
parent directory, set:

```sh theme={"system"}
export VEXLO_DATA_DIR="$PWD/vexlo-data"
export VEXLO_SPOOL_DIR="$PWD/vexlo-spool"
export VEXLO_ENDPOINT=http://127.0.0.1:8080
mkdir -p "$VEXLO_DATA_DIR" "$VEXLO_SPOOL_DIR"
```

The server resolves its database and values directory under `VEXLO_DATA_DIR`. Token commands
use the same directory. The SDK and relay must share `VEXLO_SPOOL_DIR` on the application host.
Keep these absolute paths in the environment of the processes you start.

## Create deployment credentials

Create an ingest token for the relay and a read token for the UI and API. This example uses
team `development`; both tokens must name the team whose records you want to read.

```sh theme={"system"}
umask 077
vexlo token create -role ingest -team development > "$VEXLO_DATA_DIR/ingest-token.txt"
vexlo token create -role read -team development > "$VEXLO_DATA_DIR/read-token.txt"
export VEXLO_INGEST_TOKEN=$(sed -n 's/^token:    //p' "$VEXLO_DATA_DIR/ingest-token.txt")
export VEXLO_TOKEN=$(sed -n 's/^token:    //p' "$VEXLO_DATA_DIR/read-token.txt")
```

Each file contains the new token and its ID. The CLI displays the secret once; subsequent
`token list` calls show metadata. See [Authentication](https://docs.vexlo.ai/deployment/authentication.md) for token scope
and revocation.

## Save the process environment

From the installation parent directory, save the selected paths and credential-file locations:

```sh theme={"system"}
cat > vexlo-env.sh <<EOF
export PATH="$PWD/vexlo/bin:\$PATH"
export VEXLO_DATA_DIR="$VEXLO_DATA_DIR"
export VEXLO_SPOOL_DIR="$VEXLO_SPOOL_DIR"
export VEXLO_ENDPOINT="$VEXLO_ENDPOINT"
export VEXLO_INGEST_TOKEN=\$(sed -n 's/^token:    //p' "$VEXLO_DATA_DIR/ingest-token.txt")
export VEXLO_TOKEN=\$(sed -n 's/^token:    //p' "$VEXLO_DATA_DIR/read-token.txt")
EOF
```

The file records absolute paths. Loading it in another terminal restores the environment and
reads the credentials from their saved files. Keep those files with this deployment.

## Start the server and relay

Open a terminal in the installation parent directory, load the environment and start the server:

```sh theme={"system"}
. ./vexlo-env.sh
vexlo serve
```

The server creates and migrates its database on startup. It serves the HTTP API and web UI
at `http://127.0.0.1:8080`. Authentication remains enabled on loopback.

Open a second terminal in the same installation parent directory:

```sh theme={"system"}
. ./vexlo-env.sh
vexlo relay run -environment development
```

The relay reads the local queue and forwards to `VEXLO_ENDPOINT`. Its `development` environment
label is separate from the team supplied by the ingest token. On another application host,
run a relay there with the SDK's queue directory and the destination server's URL. Configure
[TLS](https://docs.vexlo.ai/deployment/authentication.md#transport-security) before using a non-loopback connection.

## Verify access

In a third terminal, load `vexlo-env.sh` from the installation parent directory.
Verify read access:

```sh theme={"system"}
curl --silent --show-error "$VEXLO_ENDPOINT/v1/whoami" \
  -H "Authorization: Bearer $VEXLO_TOKEN"
```

The example read token returned:

```json theme={"system"}
{"role":"read","team_ids":["development"],"service_scope":null,"environment_scope":null}
```

Check the relay's health listener separately:

```sh theme={"system"}
curl --silent --show-error http://127.0.0.1:9101/healthz
vexlo relay status
```

`whoami` verifies the credential and server connection. Relay health and status verify the
forwarding process and queue. They do not prove an application has recorded a request yet.
Complete the [quickstart](https://docs.vexlo.ai/quickstart.md) to send a request through the SDK, or
[instrument your service](https://docs.vexlo.ai/instrumentation/python.md).

Open `http://127.0.0.1:8080`, paste the read token in **Read token**, and select **Connect**.
Use [Search traces](https://docs.vexlo.ai/guides/search.md) to find existing recordings.

## Stop the processes

Press `Ctrl+C` in each process terminal to stop the server and relay. Their data directories
remain at the paths you selected. To restart, load the same `vexlo-env.sh` file and run the
server and relay commands again. For unattended deployment, run both processes under your
process supervisor.

## Plan for capture cost

Measure application latency and CPU with representative inputs and concurrency. Input binding,
value conversion, exception-message formatting and optional log formatting run in the
application process. A local writer performs file work in the background, and the relay
handles the network hop. Measure those boundaries separately as well as end to end.

Log capture formats and stores messages for each recorded attempt. Its cost depends on message
volume and formatting. Custom-object adapters and exception formatting can execute application
code, so measure with the objects and methods your service uses.

Value sampling changes which captured bytes are retained. It does not skip the value-capture
work or remove previews. `capture_values=False` skips input, output and error-value capture;
tags and logs have separate controls.

[Capture controls](https://docs.vexlo.ai/instrumentation/capture.md) documents the settings that affect captured data,
and [Retention](https://docs.vexlo.ai/deployment/retention.md) explains the queue and server capacity limits.


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