Agent runtime: current deployment reference

Agent runtime: current deployment reference

The migration from the Rust zeroclaw runtime to the TypeScript agent runtime is complete. This doc records the final deployment state and how to operate it going forward.

The runtime source lives at agent-runtime/ (git submodule → github.com/myascendai/meshi-agent-runtime).

What’s running

Component	Details
Chat backend (staging)	meshi-runtime-ts-staging Fly app, single shared instance (Deno + Hono), port 42617
Chat backend (prod)	meshi-runtime-ts-prod Fly app (same shape)
/v1/chat/completions	Hono + Vercel AI SDK agent loop, tools dispatched server-side via callTool
MCP relay to platform	HTTP Streamable transport; config via MCP_CONFIG_PATH or MCP_CONFIG_JSON env
Auth to runtime	MESHI_RUNTIME_API_KEY bearer (service-to-service) + x-meshi-runtime-user-id JWT (per-user)
Database	Shared Neon instance, isolated to agent-runtime Postgres schema (Drizzle migrations)

Fly secrets required on meshi-api-staging / meshi-api-prod

fly secrets set -a meshi-api-staging \
  MESHI_RUNTIME_BACKEND=local \
  MESHI_RUNTIME_URL=http://meshi-runtime-ts-staging.internal:42617 \
  MESHI_RUNTIME_API_KEY=<value matching runtime's GATEWAY_API_KEY>

MESHI_RUNTIME_BACKEND=local routes getBackend() in packages/api/src/agent-runtime.ts to LocalBackend — one HTTP roundtrip to the shared runtime instance over Fly’s private IPv6 mesh.

Legacy fallbacks: ZEROCLAW_BACKEND, ZEROCLAW_URL, and ZEROCLAW_API_KEY are still accepted for older config, but MESHI_RUNTIME_* is the primary naming.

Deploying the runtime

The runtime has no auto-deploy. To deploy after changes to the agent-runtime/ submodule:

# Update the local submodule to latest main
git submodule update --remote agent-runtime

# Deploy to staging
cd agent-runtime
fly deploy -c fly.staging.toml -a meshi-runtime-ts-staging

See agent-runtime/docs/migration-ramp.md for the traffic-split runbook (10 → 50 → 100%) used when graduating to production.

DB migrations

The runtime manages its own schema (agent-runtime) via Drizzle. Migrations do not run automatically on deploy (the release_command in fly.staging.toml is disabled — see the comment in that file). Run manually after a schema change:

fly ssh console -a meshi-runtime-ts-staging --command 'deno task db:migrate'

Verification

Run the integration test from the submodule against staging:

cd agent-runtime
PLATFORM_URL=https://meshi-api-staging.fly.dev \
RUNTIME_URL=https://meshi-runtime-ts-staging.fly.dev \
DATABASE_URL='<neon staging url>' \
PLATFORM_DEV_USER_ID='<existing test user id>' \
  deno run -A scripts/integration-platform.ts

The script mints a temporary api_key row in the platform DB, drives a chat turn through /api/v0/conversations and /api/v0/coach, verifies the round-trip, and cleans up the key.

Rollback

To roll back the runtime to a prior Fly release without touching platform secrets:

fly releases -a meshi-runtime-ts-staging
fly releases rollback <prior-version> -a meshi-runtime-ts-staging

The FlyBackend (legacy per-user Rust machines) codepath is still present in packages/api/src/agent-runtime.ts but the Rust app (meshi-zeroclaw-jobs) is decommissioned. Do not flip MESHI_RUNTIME_BACKEND=fly.