Agent Guidelines
On this page
- Project Overview
- Project Structure
- Key Patterns
- Commands
- Contribution Guidelines
- Code Style
- Documentation
- Architecture
- Cost Observability
- Local Development
- Docker Image Caching
- Gateway Configuration
- OpenClaw Config Schema
- Common Tasks
- R2 Backup Encryption (F4E1)
- R2 Storage Notes
- Cloudflare Tunnel (removed)
- Active Technologies
- Change History
Guidelines for AI agents working on this codebase.
Project Overview
This is a Cloudflare Worker that runs OpenClaw (formerly Moltbot/Clawdbot) in a Cloudflare Sandbox container. It provides:
- Proxying to the OpenClaw gateway (web UI + WebSocket)
- Admin UI at
/_admin/for device management - API endpoints at
/api/*for device pairing - Debug endpoints at
/debug/*for troubleshooting
Note: The CLI tool and npm package are now named openclaw. Config files use .openclaw/openclaw.json. Legacy .clawdbot paths are supported for backward compatibility during transition.
Paso4 Extensions (moltlazy/)
The moltlazy/ module is fully owned by the Paso4 developers and provides two systems:
- Config Module (
config/+moltlazy/index.ts) — filesystem patcher used bystart-openclaw.shat container startup to writeopenclaw.jsonbefore the gateway launches. - Features Module (
sdk/) — RPC-based config applied to a running gateway via the Admin HTTP API. Supported feature packs: Knowledge Graph, CF Unified Billing.
Project Structure
src/
├── index.ts # Main Hono app, route mounting
├── types.ts # TypeScript type definitions (AUTOGENERATED by `bun run types`, do not apply changes directly here, instead re-run the command after implementing the rest of the features)
├── config.ts # Constants (ports, timeouts, paths)
├── auth/ # Cloudflare Access authentication
│ ├── jwt.ts # JWT verification
│ ├── jwks.ts # JWKS fetching and caching
│ └── middleware.ts # Hono middleware for auth
├── gateway/ # OpenClaw gateway management
│ ├── process.ts # Process lifecycle (find, start)
│ ├── env.ts # Environment variable building
│ ├── r2.ts # R2 bucket mounting
│ ├── sync.ts # R2 backup sync logic
│ └── utils.ts # Shared utilities (waitForProcess)
├── routes/ # API route handlers
│ ├── api.ts # /api/* endpoints (devices, gateway)
│ ├── admin.ts # /_admin/* static file serving
│ └── debug.ts # /debug/* endpoints
└── client/ # React admin UI (Vite)
├── App.tsx
├── api.ts # API client
└── pages/
moltlazy/ # Paso4 proprietary configuration utilities
├── cli.ts # CLI entry point for patching config
├── index.ts # Main logic for config patching
├── types.ts # Type definitions for OpenClaw config
├── config/
│ └── include.ts # per-section $include injection (session/tools/logging)
├── config/
├── config/ # Configuration templates
├── agents/ # Agent configuration templates
│ ├── defaults.ts # Default agent settings
│ └── premade/ # Pre-configured agent definitions
├── models/ # Provider-specific model configurations
├── sdk/ # SDK Module — typed RPC client over the Admin HTTP API
│ ├── client.ts # Typed RPC client
│ └── (agents, channels, config, cron, devices, models, gateway, update, …)
└── tests/ # Tests for configuration utilitiesKey Patterns
Environment Variables
DEV_MODE- Local-dev switch: skips CF Access auth AND bypasses device pairingOPENCLAW_DEV_MODE- Explicit override for the dev-agents flag. Normally derived by the Worker from the instance’s own-devhostname suffix (seesrc/dev-mode.ts), which enables the Fouria Builder/Q&A agents, client-doc materialization, and the opencode-credits automation without bypassing auth. Forwarded to the container asOPENCLAW_DEV_MODE; falls back toDEV_MODEfor local developmentDEBUG_ROUTES- Enables/debug/*routes (disabled by default)- See
src/types.tsfor fullMoltbotEnvinterface - See
docs/schemas/secrets-manifest.schema.jsonfor the secrets manifest
CLI Commands
On OpenClaw 2026.8.2 the CLI no longer accepts --url ws://localhost:18789
(and most local commands reject --token too). Commands run inside the container
(the gateway host) either operate on local state or auto-connect to the local
Gateway — auth resolves from the OPENCLAW_GATEWAY_TOKEN env SecretRef, so no
connection flags are passed. Commands that require an owner on a multi-agent
roster take --agent <id>. Never hardcode the id: resolve it at runtime via
openclaw agents list --json (prefer main when present, else the first
configured agent — e.g. the dev-only fouria-builder/fouria-qa premades when
running with DEV_MODE=true; see
resolveAgentFlag() in src/routes/api/shared.ts and resolveCliAgentId()
in moltlazy/sdk/cli.ts):
// Sandbox SDK 1.0: exec takes argv and resolves on launch, not completion.
startShell(sandbox, 'openclaw devices list --json');
// multi-agent commands need an explicit, dynamically-resolved owner:
startShell(sandbox, `openclaw models list --json${await resolveAgentFlag(sandbox)}`);
Gateway-connecting commands (devices, cron, secrets reload) may still accept
--url/--token when given together, but the 2026.8.2 guidance is to drop --url
and let the CLI use the configured local target.
CLI commands take 10-15 seconds due to WebSocket connection overhead. Use waitForProcess() helper in src/routes/api.ts.
Success Detection
The CLI outputs “Approved” (capital A). Use case-insensitive checks:
stdout.toLowerCase().includes('approved');Commands
bun run lint # Run linting (oxlint)
bun run test # Run tests (vitest)
bun run test:watch # Run tests in watch mode
bun run test:client # Run SPA component/page tests (jsdom, vitest.client.config.ts)
bun run test:ui # Run the Playwright UI suite (Vite dev server + mocked API)
bun run test:ui:headed # Same, with a visible browser
bun run test:ui:render:local # Local-only plwr admin-UI component render timings
bun run test:fuzz:sandbox-v1 # Seeded F4E1 codec fuzz harness ([iterations] [seed])
bun run test:gateway:boot # Local gateway boot smoke test (Docker)
bun run test:gateway:boot:ai # Same, with real AI Gateway onboard path (.dev.vars.e2e)
bun run test:software:smoke # Declared-software manifest → skills → restore smoke (Docker)
bun run build # Build client (vite)
bun run build:all # Build client + moltlazy
bun run build:docker # Build all + install deps (pre-Docker build)
bun run deploy # Build all and deploy to production
bun run deploy:dev # Build all and deploy to dev
bun run dev # Admin SPA Vite dev server (port 8787)
bun run dev:worker # Worker dev server (Cloudflare Vite plugin, port 8788)
bun run start # Build all + Worker dev server
bun run typecheck # TypeScript checkContribution Guidelines
Validation Requirements
Before submitting any contribution:
-
Run lint and tests - All builds must pass:
bun run lint bun run test -
Environment variable changes - If your contribution adds, updates, or deletes an environment variable, you MUST update it in all three locations:
README.md- Add to the secrets reference tablesrc/gateway/env.ts- Add tobuildEnvVars()function if passed to container.dev.vars.example- Add to the mapping comments and example
Testing
Tests use Vitest. Test files are colocated with source files (*.test.ts).
Current test coverage:
auth/jwt.test.ts- JWT decoding and validationauth/jwks.test.ts- JWKS fetching and cachingauth/middleware.test.ts- Auth middleware behaviorgateway/env.test.ts- Environment variable buildinggateway/process.test.ts- Process finding logicgateway/r2.test.ts- R2 mounting logicgateway/sync.test.ts- R2 backup sync logicmoltlazy/tests/index.test.ts- per-section $include injection and config generation
When adding new functionality, add corresponding tests.
The admin SPA also has a Playwright UI suite (test/ui/, config
playwright.config.ts) run with bun run test:ui. It serves the real dashboard
via the Vite dev server (bun run dev) and mocks every /api/* call per test,
so it needs no Worker, container, or Cloudflare credentials. It covers the app
shell, role-based navigation/redirects, every admin page’s render, and the
notification bell. On NixOS the browsers come from PLAYWRIGHT_BROWSERS_PATH
(see flake.nix); playwright.config.ts selects the newest chromium-* there
so the Nix bundle can lag the npm playwright version without breaking the run.
A separate local-only cctr+plwr suite (test/e2e/ui_components_render.txt,
bun run test:ui:render:local) validates the admin (root) UI components against
the local worker and records their render times (openMs/componentMs/waitMs
plus Navigation Timing/FCP) via fixture/ui-render-measure; it self-skips
outside E2E_LOCAL=true. See docs/TESTING.md.
Code Style
- Use TypeScript strict mode
- Prefer explicit types over inference for function signatures
- Keep route handlers thin - extract logic to separate modules
- Use Hono’s context methods (
c.json(),c.html()) for responses
Documentation
README.md- User-facing documentation (setup, configuration, usage)AGENTS.md- This file, for AI agents
Development documentation goes in AGENTS.md, not README.md.
Architecture
Browser
│
▼
┌─────────────────────────────────────┐
│ Cloudflare Worker (index.ts) │
│ - Starts OpenClaw in sandbox │
│ - Proxies HTTP/WebSocket requests │
│ - Passes secrets as env vars │
└──────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Cloudflare Sandbox Container │
│ ┌───────────────────────────────┐ │
│ │ OpenClaw Gateway │ │
│ │ - Control UI on port 18789 │ │
│ │ - WebSocket RPC protocol │ │
│ │ - Agent runtime │ │
│ └───────────────────────────────┘ │
└─────────────────────────────────────┘Key Files
| File | Purpose |
|---|---|
src/index.ts | Worker that manages sandbox lifecycle and proxies requests |
src/metrics.ts | Cost and usage metrics instrumentation for Analytics Engine |
Dockerfile | Container image based on cloudflare/sandbox with Node 22 + OpenClaw |
start-openclaw.sh | Startup entry point: start is the production cold-start (acquire the container-wide startup lock before setup, hold fd 9 through the Gateway exec — a single owner covers setup and launch), post-start (dev automation + boot-log reset), setup/launch (standalone smoke/manual modes only), or full (legacy: setup + background gateway launch). The Worker drives production cold-start as one start-openclaw.sh start call then a detached post-start (never awaited, so it cannot block readiness); it no longer invokes setup/launch separately. setup/post-start must stay child-free (no tail -f) — the Worker waitForExits on them. start/setup/full serialize the slow setup body on the exclusive /tmp/openclaw-setup.lock, and start holds it through the Gateway exec (no release before launch); the standalone launch takes the dedicated /tmp/openclaw-gateway-launch.lock, held for the gateway’s whole lifetime (fd inherited by the exec’d gateway). Either way exactly one openclaw gateway run owner can exist — losers poll /health and exit 0 without launching a duplicate; the serial test/e2e/ac_gateway_startup_concurrency.txt asserts one owner and the absence of the migration-input-change and SQLite offline-maintenance errors. When the Worker passes OPENCLAW_RESTORED=true (a backup was restored), the setup body is skipped entirely and the restored state is launched directly. See docs/WORKER-DEVELOPMENT.md |
wrangler.jsonc | Cloudflare Worker + Container configuration |
Cost Observability
The Worker instruments cost metrics using Cloudflare Analytics Engine for per-client cost tracking:
| Event Type | Dimensions | Metrics |
|---|---|---|
ai-query | model, provider, customer, actionType | tokensIn, tokensOut, costUsd |
container-active | customer, instanceType, action | heartbeat count |
r2-operation | customer, opType, opClass | bytesTransferred, durationMs |
cron-trigger | customer, triggerReason | wokeContainer flag |
ws-session | customer, sessionId | durationSeconds, messagesCount |
Analytics Engine Configuration
The ANALYTICS binding writes to dataset fourai_cost_metrics. Query via GraphQL:
query CostMetrics($accountTag: String!) {
viewer {
accounts(filter: { accountTag: $accountTag }) {
analyticsEngineDatasets(filter: { name: "fourai_cost_metrics" }) {
data(
query: "SELECT blob1 as event_type, blob2 as customer, blob3 as model, SUM(double1) as tokens_in, SUM(double2) as tokens_out FROM fourai_cost_metrics WHERE timestamp > NOW() - INTERVAL 1 DAY GROUP BY blob1, blob2, blob3"
) {
result
}
}
}
}
}Cost API Endpoint
GET /api/admin/costs returns pricing constants and query examples for cost dashboards.
Local Development
npm install
cp .dev.vars.example .dev.vars
# Edit .dev.vars with your CLOUDFLARE_AI_GATEWAY_API_KEY + CLOUDFLARE_API_TOKEN + CF_AI_GATEWAY_ACCOUNT_ID + CF_AI_GATEWAY_GATEWAY_ID
npm run startEnvironment Variables
For local development, create .dev.vars:
CLOUDFLARE_AI_GATEWAY_API_KEY=your-provider-api-key
CLOUDFLARE_API_TOKEN=your-ai-scoped-api-token # REST transport; use the same AI-scoped credential locally
CF_AI_GATEWAY_ACCOUNT_ID=your-account-id
CF_AI_GATEWAY_GATEWAY_ID=your-gateway-id
DEV_MODE=true # Skips CF Access auth + device pairing
DEBUG_ROUTES=true # Enables /debug/* routesWebSocket Limitations
Local development with the Vite dev server has issues proxying WebSocket connections through the sandbox. HTTP requests work but WebSocket connections may fail. Deploy to Cloudflare for full functionality.
Docker Image Caching
The Dockerfile includes a cache bust comment. When changing start-openclaw.sh, bump the version:
# Build cache bust: 2026-02-06-v28-openclaw-upgradeGateway Configuration
OpenClaw configuration is built at container startup:
- R2 backup is restored if available (with migration from legacy
.clawdbotpaths) - If no config exists,
openclaw onboard --non-interactivecreates one based on env vars - Feature flags come from the per-customer
MOLTLAZY_FEATURE_FLAGSbinding (managed via the FourIA API) start-openclaw.sh startrunsmoltlazy patch(after the restore/onboard above) which generates per-section include files (moltlazy-session/tools/logging.json) and injects them as per-section$includedirectives (no root$include);gateway.*/agents.*are written inline and the gateway token is an env SecretRef- The Worker calls
/usr/local/bin/start-openclaw.sh startonce: that mode acquires the container-wide startup lock before running the setup body, runs the patch while holding it, thenexecs the supervised Gateway under the same lock (theexecreplaces the wrapper, so the tracked process is the gateway) and runsstart-openclaw.sh post-startafterward once the port is ready. The Worker no longer invokessetupthenlaunchseparately; those remain standalone smoke/manual modes only.
Feature Flag Configuration
Feature flags are managed via the FourIA API and applied as a per-customer binding (MOLTLAZY_FEATURE_FLAGS, a JSON string). The Worker reads the binding and passes it to the container via buildEnvVars(). The legacy CONFIG_BUCKET / config-cache.ts (R2 + ETag) mechanism was removed.
Feature Flags Example:
{
"knowledgeGraph": true,
"unifiedBilling": false,
"softwareProvisioning": false
}
The container consumes MOLTLAZY_FEATURE_FLAGS at startup (moltlazy patch generates the per-section include files and injects them as per-section $include into openclaw.json). There is no worker-side cache — the binding is read directly.
Software provisioning (softwareProvisioning)
Software that agent skills install at runtime (plugins, apt/npm packages,
downloaded binaries) lives in the container filesystem only, so it is lost on a
container-version upgrade (fresh image) or idle-sleep (container destroyed).
The per-customer softwareProvisioning flag fixes this:
- The tenant’s manifest (
customers/<slug>/software.jsonin theBACKUP_BUCKET) declares each package with its actual install command:{ id, check, install, verify?, timeoutSec? }. Operators write it viaPUT /api/admin/software/manifest(Access-protected); the dev-only Fouria Builder writes it through the sandboxsoftware.r2.internalbridge (src/sandbox-software-bridge.ts) instead, because/api/admin/*answers302to the Access login when called from the container. Bridge writes are dev-only; reads work everywhere. - On cold start,
ensureGatewayImplmaterializes the manifest into/home/openclaw/.openclaw/software.jsonand — only when the flag is on — spawnsmoltlazy software provisionas an independent supervised process through the Sandbox SDK (void spawnSoftwareProvision(...)), not a step instart-openclaw.sh. It runs in parallel with the gateway boot, never blocks readiness, and is non-fatal (per-package timeouts; failures recorded, not raised). - It writes live ticks to
/tmp/software-progress.log(read byGET /api/startup-progress//api/startup/wsassoftwareLog) and a structured report to/tmp/software-report.json(surfaced byGET /api/admin/software/reportas the homepage Software widget). Each run truncates the progress log first (resetProgressLog), because/tmpsurvives an in-place restart (/debug/restart-openclaw), which would otherwise interleave ticks from earlier boots. POST /api/admin/software/provision(ADMIN/ROOT) reconciles the manifest on demand, so a manifest uploaded or corrected mid-life does not need a restart. It re-materializes the current R2 manifest, runs the same CLI to completion bounded bySOFTWARE_PROVISION_RUN_TIMEOUT_MS(5 min), and returns the fresh report;409when the flag is off (disabled) or nothing is declared (no_manifest),502when the run fails.- Both
GETendpoints carryenabled(the flag), so the dashboard can tell “switched off”, “asleep”, “not run yet” and “nothing declared” apart instead of showing one empty state. The widget exposes a Run provisioning button to ADMIN/ROOT when the flag is on.
The manifest is arbitrary shell executed inside the tenant container, so the
upload endpoint is ADMIN/ROOT-only (never exposed to readers), timeoutSec is
per package, and the on-demand run is bounded by the route.
A runnable example ships with the repo:
test/e2e/fixture/software/gog-goplaces.json declares the gogcli (gog) and
goplaces binaries that the openclaw/openclaw/gog and .../goplaces skills
(listed on skills.sh, published on ClawHub as @steipete/gog /
@steipete/goplaces) need, and test/e2e-backup/zzz_software_binaries_restore.txt
(local-only) proves the whole loop: upload the manifest → openclaw skills install @steipete/{gog,goplaces} --global → backup → destroy the container →
restore, after which the binaries are back on PATH because the next
provisioning cycle re-installed them (the report startedAt advances) while the
skills come back from the snapshot. scripts/software-restore-smoke.sh
(bun run test:software:smoke) proves the same contract directly against the
sandbox image, without workerd/Miniflare, and is the fallback when the local
container runtime is unavailable.
Key modules: src/gateway/software-provisioning.ts (flag + spawn + on-demand
run + report parsing), src/services/software-manifest/ (R2 store +
materialization), src/routes/api/software.ts (manifest read/upload, report,
on-demand provision), packages/moltlazy/src/software/ (the CLI).
AI Provider
Cloudflare AI Gateway is the only provisioned AI provider path. The startup script configures auth when all of these env vars are set:
- Cloudflare AI Gateway (native):
CLOUDFLARE_AI_GATEWAY_API_KEY+CF_AI_GATEWAY_ACCOUNT_ID+CF_AI_GATEWAY_GATEWAY_ID
Container Environment Variables
These are the env vars passed TO the container (internal names):
| Variable | Config Path | Notes |
|---|---|---|
CLOUDFLARE_AI_GATEWAY_API_KEY | (env var) | Native AI Gateway key |
CLOUDFLARE_API_TOKEN | (env var) | AI Gateway REST API Bearer token; tenant binding is derived from the AI key |
CF_AI_GATEWAY_ACCOUNT_ID | (env var) | Account ID for AI Gateway |
CF_AI_GATEWAY_GATEWAY_ID | (env var) | Gateway ID for AI Gateway |
OPENCLAW_GATEWAY_TOKEN | --token flag | Mapped from MOLTBOT_GATEWAY_TOKEN |
OPENCLAW_DEV_MODE | (dev-agents flag) | Derived from the -dev hostname or an OPENCLAW_DEV_MODE override; DEV_MODE local |
FOURIA_DOCS_CHANNEL | (docs channel) | latest on production, staging on the staging platform / -dev; selects channel-matched docs + release notes |
FOURIA_DOCS_BASE_URL | (docs channel) | https://fouria.io/<channel> |
FOURIA_DOCS_FALLBACK_URL | (docs channel) | https://fouria-docs.pages.dev/<channel> (public mirror) |
FOURIA_VERSION | (build identity) | The Worker bundle’s component CalVer (src/build-info.ts) |
OPENCLAW_RESTORED | (zero-data-loss signal) | true when the launch runs on a container that already holds tenant state (hasRestoredTenantState); makes start-openclaw.sh skip the setup body |
TELEGRAM_BOT_TOKEN | channels.telegram.botToken | @deprecated — E2E only. Use integrations dashboard in production. |
DISCORD_BOT_TOKEN | channels.discord.token | @deprecated — E2E only. Use integrations dashboard in production. |
SLACK_BOT_TOKEN | channels.slack.botToken | @deprecated — E2E only. Use integrations dashboard in production. |
SLACK_APP_TOKEN | channels.slack.appToken | @deprecated — E2E only. Use integrations dashboard in production. |
OpenClaw Config Schema
OpenClaw has strict config validation. Common gotchas:
agents.defaults.modelmust be{ "primary": "model/name" }not a stringgateway.modemust be"local"for headless operation- No
webchatchannel - the Control UI is served automatically gateway.bindis not a config option - use--bindCLI flag
See OpenClaw docs for full schema.
Common Tasks
Adding a New API Endpoint
- Add route handler in
src/routes/api.ts - Add types if needed in
src/types.ts - Update client API in
src/client/api.tsif frontend needs it - Add tests
Adding a New Environment Variable
- Add to
MoltbotEnvinterface insrc/types.ts - If passed to container, add to
buildEnvVars()insrc/gateway/env.ts - Update
.dev.vars.example - Document in README.md secrets table
Debugging
# View live logs
npx wrangler tail
# Check secrets
npx wrangler secret list
Enable debug routes with DEBUG_ROUTES=true and check /debug/processes.
R2 Backup Encryption (F4E1)
When BACKUP_ENCRYPTION_KEY (base64 32-byte secret) is set, the Worker post-encrypts every
snapshot after sandbox.createBackup(): backups/<id>/data.sqsh is replaced by
data.sqsh.enc (chunked AES-256-GCM, per-object HKDF key) and meta.json is flagged
encrypted: true (kept readable — the SDK needs it). Restores decrypt transiently and delete
the plaintext in a finally block. Config versions under configs/ are encrypted with
customMetadata.encrypted='true'. Legacy plaintext backups remain restorable.
Set BACKUP_ENCRYPTION_REQUIRED=true to fail closed. Crypto lives in src/crypto/.
workerd’s R2Bucket.put() rejects ReadableStream bodies of unknown length, so uploads wrap
the ciphertext/plaintext stream in a FixedLengthStream whose size is computed from the source
object (encryptedLength) or the F4E1 header (decryptedLength). This keeps backup/restore
memory-bounded (no whole-archive buffering) while satisfying R2. See src/crypto/r2-backup.ts.
See docs/plans/r2-encryption-at-rest.md.
R2 Storage Notes
Persistence uses the Sandbox SDK createBackup() / restoreBackup() API with
the BACKUP_BUCKET binding. The snapshot root is /home/openclaw; it is not an
s3fs mount and there is no /data/moltbot runtime path.
Never delete tenant backup objects outside the retention or decommission procedure. Hard restarts must checkpoint before killing the gateway.
-
Process status: The sandbox API’s
proc.statusmay not update immediately after a process completes. Instead of checkingproc.status === 'completed', verify success by checking for expected output (e.g., timestamp file exists after sync). -
R2 prefix migration: Backups are now stored under
openclaw/prefix in R2 (wasclawdbot/). The startup script handles restoring from both old and new prefixes with automatic migration. -
Snapshot lease + admin snapshot mode (F5): the shared R2
backup-lockTTL isSTEP_DEADLINE_MS(12 minutes), with a serialized heartbeat every quarter-TTL and explicit renewals around slow snapshot/restore boundaries. Renewal events are structured; renewal failure is best-effort and does not abort work. The longer TTL intentionally favors avoiding false expiry during a live durable step, at the cost of a longer stale-holder takeover window.POST /api/admin/storage/syncenqueues a durable job by default whenACTIVITYis available; use?inline=1only when synchronous completion is required (?async=1keeps its prior behavior). WithoutACTIVITY, the route falls back to inline work.
Cloudflare Tunnel (removed)
Tenant Cloudflare Tunnel support was removed. start-openclaw.sh no longer
starts cloudflared, no tenant Worker receives a CLOUDFLARE_TUNNEL_TOKEN
binding, and Lerma no longer provisions one. The obsidian-sync skill still
runs a local sync server on port 18790; exposing it publicly is an operator
decision outside the platform.
FourIA offers Private Cloud only (Business On Premise is not offered at this time). Pricing is credit-based: Credits are the exclusive billable unit, consumed by completed messages and automations. Credits do NOT include AI costs — AI expenses are managed separately via BYOL or AI Gateway billing. Reader users are unlimited and free. Builder seats (users who can create and edit agents) are plan-limited. The v1.0-beta is delivered through the Design Partner Program with a single engaged partner. Partners pay a fixed credit fee negotiated with sales. See docs/VISION.md for the full pricing definition.
Active Technologies
- OpenTofu 1.6+ (HCL) +
cloudflareprovider (Terraform/OpenTofu) (001-opentofu-deploy) - Cloudflare R2 (for FourIA data), OpenTofu Local/Remote State (for infrastructure tracking) (001-opentofu-deploy)
Change History
AGENTS.md documents how to work on this project, not what changed. Every change
is recorded in the owning product’s changelog:
-
The Agent Garage is now an all-in-one, RPC-only Agent Studio.
/_admin/agentsreplaced the character builder with a workbench (roster + Overview, Capabilities, MCP, Memory, Automations, Connections, Health). Every read goes through Gateway RPC —config.get,agents.list,agents.files.*,agents.workspace.*,tools.catalog/tools.effective,skills.*,plugins.list,hooks.status,cron.*,sessions.*,memory.status,system.info— with noopenclawCLI and no shell. Core reads prefer Admin HTTP RPC; the richer surfaces share onewithGatewayRpcClientconnection per request, and each call is guarded so one unsupported method only degrades its pane. Reads are non-waking: the route boundsisRuntimeActive()(3 s, same as the passive health probe) and returns{ available: false, reason: "sleeping" }before opening a socket. Writes useagents.files.setwith theagents.files.gethash (409 agent_file_conflicton stale content),config.patchfor bindings (noopenclaw agents bind),cron.run/cron.updatefor automations, andplugins.setEnabled/plugins.refresh(admin scope). RPC gaps are explicit: there is no MCP probe or binary-presence method, so MCP health is the lasttools.effectiveinventory + notices and the Health pane listsskills.bins/missing requirements instead of claiming presence. Tests:src/agents/studio.test.ts,src/routes/api/agent-studio.test.ts,src/client/pages/__tests__/role-isolation.test.tsx,test/ui/agent-studio.spec.ts; corpusdashboard-api-contract.txt,operational-modes.txt,tenant-isolation.txt,agent-visibility.txt; docsapps/fouria/docs/WORKER-DEVELOPMENT.md§ Agent Studio,apps/fouria/README.md,docs/TESTING.md. -
OpenClaw migrated to 2026.11.3 (
catalog.openclaw+ the@openclaw/gateway-client/@openclaw/gateway-protocolpins in the rootpackage.json; the plugin repo tracks and publishes the same release). The tracked range (2026.10.9 → 2026.11.3: 2026.10.10, 2026.11.1, 2026.11.2, 2026.11.3) has no config-schema changes — 2026.11.3’s notes state “No new configuration options or features” — so the moltlazyopenclaw config validatecctr contract passes unchanged and nopackages/moltlazysource change was needed. The release does lower the Node engine floor from>=24.22.1 <25 || >=26.12.1to>=24.16.0 <25 || >=26.1.0(2026.10.10); the container keeps the pinned Node v24.22.1, which satisfies the wider range, so no image change. Relevant runtime fixes for a tenant: Gateway startup loads fewer module files and no longer stalls on long punctuation runs in abort-command detection, cron storage failures no longer exit the Gateway, plugin results stay scoped to their connection credentials, and Signal daemons/bundled language servers stop inheriting unrelated Gateway secrets. The gateway boot smoke (boot=0 health=ok) and the full verification gate are green against 2026.11.3. No component CalVer bump — the release train handles that. -
Local containers no longer look like a platform bug, and the memory watchdog never races a boot. A local restore failed with
Container failed to startwhiledocker psshowed only a…-proxysidecar churning every ~20 s; the app container was never created. That isnet.ipv4.conf.all.src_valid_mark=1(which Tailscale sets) making workerd’s egress sidecar drop its own marked handshake (cloudflare/workerd#6860), not a FourIA defect. The dev server now warns before it builds images —src/dev-container-preflight.ts(puredescribeContainerNetnsProblem+readContainerNetnsSettings, unit-tested) reads the two relevant sysctls and prints the fix (preferred:net.core.devconf_inherit_init_net = 2, which keeps Tailscale working; one-session alternative:src_valid_mark=0) plus the stale-sidecar cleanup;FOURIA_SKIP_CONTAINER_PREFLIGHT=1silences it for CI hosts. The same investigation exposed a real race: the durable memory watch sampled/procwithsandbox.exec— which auto-starts a stopped container — while a restore was probing it, producinggateway.memory-read failed (launch-failed)and a workerdjsgInternalErrorthat abortedcontainer.start().checkGatewayMemoryHealth()now takes the bounded non-wakingisRuntimeActive()read first and returns{ action: 'skipped', reason: 'runtime-inactive' }when the runtime is off, andActivityScheduler.runMemoryWatch()returns before sampling while a boot/backup/maintenance job is active (queued/running/retrying), so observability never participates in a boot. The persistence lease acquire is now bounded too: a conditionalbackup-lockwrite that never settles is reported aspersistence.lock.write-timeoutand treated as a lost acquire, instead of holding the durable step (6 min of silence, thenjob-step.interrupted) — observed locally when taking over an expired lease. Tests:src/dev-container-preflight.test.ts,src/gateway/memory.test.ts,src/activity/scheduler.test.ts,src/persistence.test.ts; corpustest/business-rules/operational-modes.txt; docsdocs/DEVELOPMENT.md§ “Local containers never start”,docs/TESTING.md§ “E2E Tests (Local)”,apps/fouria/docs/WORKER-DEVELOPMENT.md§ memory watchdog. -
apps/fouria/CHANGELOG.md— tenant Worker (CalVer) -
workers/fouria-dispatch/CHANGELOG.md— dispatch Worker (CalVer) -
apps/lerma/CHANGELOG.md— customer dashboard (semver, Changesets) -
packages/moltlazy/CHANGELOG.md— config patcher and SDK (semver, Changesets) -
packages/cost-calculator/CHANGELOG.md— pricing helpers (semver, Changesets)
Add a changeset in every pull request (see the root AGENTS.md, “Semver
Releases”), and do not add a change log to this file.