Skip to content

traverse-runtime.md

Latest commit

 

History

History
123 lines (86 loc) · 3.9 KB

traverse-runtime.md

File metadata and controls

123 lines (86 loc) · 3.9 KB
Raw

Traverse Runtime Setup

This document covers how to run the Traverse runtime for local development. For the production target (embedded in-app host), see embedded-runtime-plan.md.

Deployment Models

Model Status Use when
Embedded in-app host (Phase 3) Target — not yet in platform clients Building/shipping reference apps to end users
HTTP sidecar traverse-cli serve (Phase 1/2) Current dev path Local development, CI smoke tests, trace-explorer

End-user apps must not depend on a separately running sidecar. The sidecar exists so developers can iterate before the embeddable host SDK ships in Traverse.

Pinned Version

Phase Minimum version Adds
Phase 1 (HTTP integration) v0.3.0 HTTP/JSON API, /healthz, execute, poll, trace
Phase 2 (CLI app registration) v0.5.0 traverse-cli app validate/register, workspace state
Phase 3 (embedded host) TBD In-app WASM runtime host SDK per platform

Current release: v0.6.0 — recommended for Phase 1/2 dev sidecar.

Requirements: Rust 1.94+

Dev Sidecar — Start the Runtime

git clone https://github.com/traverse-framework/Traverse.git /tmp/traverse
cd /tmp/traverse
git checkout v0.6.0
cargo run -p traverse-cli -- serve

The runtime writes a discovery file on startup:

cat .traverse/server.json
# {
#   "base_url": "http://127.0.0.1:8787",
#   "health_url": "http://127.0.0.1:8787/healthz",
#   "workspace_default": "local-default",
#   "auth_mode": "dev-loopback"
# }

HTTP API Surface (dev sidecar only)

Governed by 033-http-json-api (approved v1.1.0).

Endpoint Method Purpose
/healthz GET Health check
/v1/workspaces/{workspace_id}/execute POST Execute a capability
/v1/workspaces/{workspace_id}/executions/{execution_id} GET Poll execution status
/v1/workspaces/{workspace_id}/traces/{execution_id} GET Fetch public trace
/v1/workspaces/{workspace_id}/capabilities POST Register a capability

Default workspace: local-default

Phase 3 embedded clients use the public host SDK instead of these HTTP endpoints for in-process execution.

Discovery in App Code (Phase 1/2 — dev only)

import fs from 'fs'

const server = JSON.parse(fs.readFileSync('.traverse/server.json', 'utf8'))
const baseUrl = server.base_url          // http://127.0.0.1:8787
const workspaceId = server.workspace_default  // local-default

In the browser (Vite env vars):

const baseUrl = import.meta.env.VITE_TRAVERSE_BASE_URL ?? 'http://127.0.0.1:8787'
const workspaceId = import.meta.env.VITE_TRAVERSE_WORKSPACE ?? 'local-default'

Phase 3 clients load bundled manifests from the app artifact and initialize an in-process workspace — no URL discovery.

App Registration (Phase 2 — dev sidecar)

Governed by 044-application-bundle-manifest and 046-public-cli-app-registration (both approved).

traverse-cli app validate --manifest manifests/<app>/app.manifest.json --json

traverse-cli app register \
  --manifest manifests/<app>/app.manifest.json \
  --workspace local-default \
  --json

Phase 3 production builds embed manifests + WASM at build time; registration into a sidecar workspace is not the shipping path.

Local Development Override

export TRAVERSE_REPO=/path/to/Traverse
cd $TRAVERSE_REPO && cargo run -p traverse-cli -- serve

Do not commit TRAVERSE_REPO references into app code.

CI Environment

TRAVERSE_RUNTIME_URL=http://<host>:<port>
TRAVERSE_WORKSPACE_ID=local-default

scripts/ci/phase1_smoke.sh reads these when .traverse/server.json is absent.

Phase 2:

export TRAVERSE_REPO=/path/to/Traverse
bash scripts/ci/phase2_link_traverse.sh
bash scripts/ci/phase2_smoke.sh

Phase 3 will add scripts/ci/embedded_smoke.sh when the embeddable host is available.