Local runtime

Mezair Local runs a built Cell without a cloud provider.

It uses the same handleRuntimeRequest boundary as deployment adapters, then provides local implementations for database, files, env, auth, logs, events, jobs, workflows, and supervised services.

The runtime binds to 127.0.0.1 by default. Use --host <address> only when a native device or another machine must connect. Lens and the /_mezair/* management actions are development controls, so do not expose that port to an untrusted network.

What starts with `mezair cloud dev`

mezair cloud dev runs a build first. If the build passes, it imports the server bundle, loads the manifest, and starts:

local runtime HTTP server
local client asset server
local agent runtime with the deterministic stub provider registered by default
JSON database adapter
local file adapter
local environment adapter
local auth adapter
local log adapter
local event adapter
local job adapter
local workflow adapter
local service supervisor

When capabilities.outboundFetch.allow is declared, local request handlers and workflow steps run with the same outbound host guard as AWS preview. Calls to undeclared hosts fail with OUTBOUND_FETCH_NOT_ALLOWED.

Default ports:

Surface	Default
Runtime	`8787`
Client	`5173`

Options:

Terminal

mezair cloud dev --port 8787 --client-port 5173
mezair cloud dev --json
mezair cloud dev --agent --json

Local routes

The local runtime exposes:

Text

POST /_mezair/query/:name
POST /_mezair/mutation/:name
ANY  /api/*
GET  /_mezair/health
GET  /_mezair/manifest
GET  /_mezair/inspect
GET  /_mezair/lens
GET  /_mezair/agents
POST /_mezair/agents/:name
GET  /_mezair/approvals
GET  /_mezair/approvals/audit
POST /_mezair/approvals/:id/approve
POST /_mezair/approvals/:id/reject
GET  /_mezair/traces
GET  /_mezair/traces/:traceId
POST /_mezair/agents/:name/sessions
POST /_mezair/agents/sessions/:sessionId/messages
GET  /_mezair/agents/sessions/:sessionId/stream?after=:token
POST /_mezair/channels/simulate
POST /_mezair/workflows/run/:name
GET  /_mezair/workflows
GET  /_mezair/workflows/:runId
GET  /_mezair/schedules
POST /_mezair/schedules/:name/run
GET  /_mezair/services
POST /_mezair/services/:name/start
POST /_mezair/services/:name/stop

Endpoint requests under /api/* are translated into endpoint runtime requests and matched against declared Cell endpoints.

Agent requests under /_mezair/agents/:name invoke mounted Cell Agents through the same provider-neutral AgentRuntime used by tests and provider mode. The local stub inference provider is registered automatically for provider: "local".

Approval-gated tool execution records pending requests in local state and returns a pending approval id instead of executing the gated action. Use /_mezair/approvals, Lens, or mezair-cloud approvals ... --json to inspect, approve, reject, and audit those requests.

Session routes add resumable event history around mounted agents. Create a session, send messages to it, then reconnect to the SSE stream with the last continuation token to replay missed events.

Channel simulation routes normalize local Slack/GitHub/Discord-style inbound messages and map them to mounted agent sessions. They are for local development and tests; real provider credentials and webhook verification stay outside Cell code.

Local state

Local state lives in .mezair/local by default:

Text

.mezair/local/
  auth.json
  approvals.json
  agent-sessions.json
  dev.db
  events.json
  files/
  jobs.json
  logs.ndjson
  schedules.json
  services.json
  traces.json
  workflows.json

The current database adapter stores JSON records in dev.db. It is intentionally simple, inspectable, and suited to alpha local development.

Local database branches snapshot that JSON store for previews, tests, and agent experiments. main maps to .mezair/local/dev.db; named branches live under .mezair/local/db-branches with metadata in .mezair/local/db-branches.json. Cell code still sees the same ctx.db contract regardless of the selected branch.

Scheduled jobs declared with job({ schedule }) are tracked in schedules.json. Local scheduling supports rate(1 hour), @every 5m, and five-field cron expressions. Missed runs while the dev runtime is stopped are skipped rather than replayed. Use Lens or mezair-cloud schedules list|run --json to inspect and manually trigger schedules.

Database behavior

ctx.db.<table> supports table operations through the local JSON adapter:

all
get
insert
update
delete
where(...).all
where(...).first
where(...).count

Inspection commands:

Terminal

mezair cloud db list --local --json
mezair cloud db dump notes --local --json
mezair cloud db branch preview --from main --ttl 3600 --json
mezair cloud db use preview --json
mezair cloud dev --db-branch preview --json
mezair cloud db diff preview --against main --json
mezair cloud db promote preview --json
mezair cloud db delete preview --yes --json
mezair cloud db cleanup --expired --json

Files

ctx.files stores local file data under .mezair/local/files.

Supported operations:

get
put
delete

Deployment adapters map the same capability to their own backing store.

Auth

Local auth state is stored in .mezair/local/auth.json.

Handlers can use ctx.auth.requireUser() to require a current local user. Local auth is a development emulator; production auth belongs behind configured OIDC providers.

Logs

Local logs are NDJSON in .mezair/local/logs.ndjson.

Read them with:

Terminal

mezair cloud logs --local --json

Runtime errors include request id, handler kind, handler name, message, and error metadata.

Workflows

Local workflows persist state to .mezair/local/workflows.json. The runtime records each step transition so a running workflow can resume when the local server starts again.

Useful commands:

Terminal

mezair cloud workflows list --json
mezair cloud workflows show <runId> --json
mezair cloud workflows run <name> --input '{"example":true}' --json

Services

Local services run under the runtime service supervisor. Service state snapshots are written to .mezair/local/services.json.

Terminal

mezair cloud services list --json

For live state while the dev server is running, use the local Lens UI or GET /_mezair/services.

Inspection

Use:

Terminal

mezair cloud inspect --local --json

The local inspection payload includes:

build status
manifest
current auth user
table row counts
recent runtime errors
declared workflows and recent run state
service state when recorded

The value of local runtime is not that it perfectly mimics a provider. The value is that the app contract can be executed and inspected before adapter behavior enters the conversation.

Suggest an edit to this page on GitHub