Install and run Vexlo

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.

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 and Connect an agent. The commands below use loopback ports 8080 and 9101; select different addresses in configuration if those ports are occupied.

Build the binary

From your chosen installation directory:

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:

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.

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 for token scope and revocation.

Save the process environment

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

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:

. ./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:

. ./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 before using a non-loopback connection.

Verify access

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

curl --silent --show-error "$VEXLO_ENDPOINT/v1/whoami" \
  -H "Authorization: Bearer $VEXLO_TOKEN"

The example read token returned:

{"role":"read","team_ids":["development"],"service_scope":null,"environment_scope":null}

Check the relay’s health listener separately:

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 to send a request through the SDK, or instrument your service. Open http://127.0.0.1:8080, paste the read token in Read token, and select Connect. Use Search traces 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 documents the settings that affect captured data, and Retention explains the queue and server capacity limits.

Getting started

AI agents

Instrumentation

Web UI

Using execution data

Deployment and administration

Examples

Reference

Install and run Vexlo

Prerequisites

Build the binary

Select storage directories

Create deployment credentials

Save the process environment

Start the server and relay

Verify access

Stop the processes

Plan for capture cost

​Prerequisites

​Build the binary

​Select storage directories

​Create deployment credentials

​Save the process environment

​Start the server and relay

​Verify access

​Stop the processes

​Plan for capture cost

Prerequisites

Build the binary

Select storage directories

Create deployment credentials

Save the process environment

Start the server and relay

Verify access

Stop the processes

Plan for capture cost