Deploy VEX on Railway#

This is the minimum public setup for running the current vex-api service on Railway so an external evaluator can test the live HTTP surface without needing internal walkthroughs.

What This Solves#

Brings up a single evaluatable HTTP service.
Exposes a safe health check path.
Preserves the current authenticated API contract.
Makes the main deployment caveats explicit before evaluation starts.

Current Railway Fit#

Concern	Current behavior
Web port	`vex-api` reads `VEX_PORT`, not `PORT`
Public health check	`GET /health` is public and does not require auth
Persistence	`DATABASE_URL` defaults to `sqlite::memory:` if not set
LLM provider	If `DEEPSEEK_API_KEY` is missing, the server falls back to `MockProvider::smart()`
HTTPS mode	Setting `VEX_ENV=production` enables HTTPS enforcement and fails startup unless `VEX_TLS_CERT` and `VEX_TLS_KEY` are present

TLS behavior matters on Railway

Railway terminates TLS at the edge. The current server process still expects in-process certificate files when HTTPS enforcement is enabled. For a standard Railway evaluation deployment, leave VEX_ENV unset or set it to development unless you are supplying VEX_TLS_CERT and VEX_TLS_KEY to the process itself.

Recommended Service Commands#

Use these commands for a single-service evaluation deployment:

Bash

# Build command
cargo build --release -p vex-api

Bash

# Start command
VEX_PORT=$PORT ./target/release/vex-api

These commands work with the current server contract because the binary binds to VEX_PORT and defaults to 8080 if that variable is missing.

Required Variables#

Variable	Required	Why
`VEX_JWT_SECRET`	Yes	Required at startup; must be at least 32 characters
`DATABASE_URL`	Recommended	Prevents the API from falling back to in-memory SQLite
`DEEPSEEK_API_KEY`	Optional	Enables a real LLM provider instead of the built-in mock provider
`VEX_ENV`	Optional	Leave unset or set to `development` for a normal Railway edge-TLS deploy
`VEX_TLS_CERT`	Only for in-process TLS	Required if you intentionally enable HTTPS enforcement inside the process
`VEX_TLS_KEY`	Only for in-process TLS	Required if you intentionally enable HTTPS enforcement inside the process

First Smoke Test#

Once Railway assigns a public domain, verify the public health endpoint first:

Bash

curl -sS https://your-service.up.railway.app/health

Expected response shape:

JSON

{
  "status": "healthy",
  "version": "0.1.7",
  "timestamp": "2026-04-04T10:15:32Z"
}

The exact version and timestamp values will differ, but the response fields are stable.

Evaluation Flow After Deploy#

Run the public health check above.
Use Agent Execution Queue if you want to evaluate the authenticated API path.
Use Verifiable Pipeline Audit Trail if you want an offline verification workflow.
Use Proof Anchoring Receipt Flow if you want a receipt-level proof example.

Current Limitations#

There is no public token-minting endpoint. Authenticated API evaluation requires a locally signed JWT using the same VEX_JWT_SECRET.
GET /health is the safest unauthenticated health check. GET /health/detailed is not the public evaluation path.
POST /api/v1/agents/{id}/execute returns a queue acknowledgement. The actual job identifier is embedded in the response string rather than returned as a dedicated job_id field.
A Railway deploy only works cleanly if you map PORT into VEX_PORT in the start command.

Deploy VEX on Railway#

What This Solves#

Current Railway Fit#

Recommended Service Commands#

Required Variables#

First Smoke Test#

Evaluation Flow After Deploy#

Current Limitations#

Railway References#