Architecture

The monorepo map, the services that carry the loop, and the network topology that makes isolation real.

Utter is a single pnpm workspace of TypeScript packages and Solidity contracts. The whole platform is here: the creator studio, the discovery service, the money path, the sandbox runtime, and the on-chain contracts. This page maps every member and shows how the running services are wired into networks that are themselves part of the isolation model.

The monorepo

The workspace globs apps/*, services/*, packages/*, and contracts. Every member is private, ESM, and named @utter/<dir>. viem is pinned repo-wide to a single version so every chain-touching package speaks the same client.

There is no mainnet. Utter targets Arc Testnet (chain id 5042002) only. USDC 0x3600…0000 is both the 6-decimal ERC-20 and the 18-decimal native gas token, so every package reads decimals() at runtime rather than hardcoding it.

Apps

Member	Package	What it is
apps/studio	@utter/studio	The creator studio. A React Router v7 SSR app on port 3000. Utter a sentence, watch it build, set a price, see earnings, withdraw. Its /discover screen reads the marketplace.
apps/marketplace	@utter/marketplace	A headless Hono JSON discovery service on port 8789, no UI. It serves the public resource index and agent-card lookups that agents read.

Services

Member	What it does
services/deployer	Builds generated bundles, runs them under gVisor, registers them on-chain, publishes them. An authenticated control-plane HTTP server (POST /deploy plus an SSE stream) on port 8788. It runs on the provisioned Linux host, not in the compose stack, because it needs the host Docker daemon and runsc.
services/facilitator	The x402 escrow money path: /verify, /settle, /release, /results, the relayer, and exactly-once settlement.
services/sandbox	The gVisor isolation runtime and the pre-build static gate.
services/orchestrator	The warm pool and scale-to-zero scheduler. This is a scheduler, not an isolation boundary.

Packages

Member	What it does
packages/chain	Pinned Arc constants plus viem and the ABIs.
packages/x402-arc	The escrow scheme, the response gate, and the sidecar.
packages/ai-runtime	Sentence-to-handler generation plus the agent-card builder.
packages/ai-scorer	Probes and strikes.
packages/buyer-sdk	The reference paying agent and the MCP server.
packages/erc8004	On-chain identity.
packages/data-proxy	The egress proxy.
packages/staking	Creator bonds and the staking vault client.
packages/treasury	Platform treasury accounting.
packages/cost	Metering and cost inputs.
packages/observability	Logs, metrics, and traces.

Contracts

contracts is a Foundry/Solidity project: ResourceRegistry, PaymentEscrow, StakingVault, PaymentSplitter, and reference ERC-8004 registries. These are already deployed on Arc Testnet; see Self-hosting the stack for the redeploy caveat.

The network topology

The sandbox is not only runsc. The docker-compose stack splits the running services across several networks, most of them internal: true, so that no container can reach anything it has no business reaching. The untrusted handler and the trusted sidecar are two separate containers per resource: the handler holds no secrets and no facilitator token, and it can only talk outward through the data proxy.

edge

The only externally reachable network. Traefik lives here with external egress and the wildcard TLS certificate for *.resources.<domain>.

ingress (internal)

Traefik to the per-resource sidecar. No gateway, so nothing on this network reaches the internet.

controlplane (internal)

The sidecar to the facilitator. This is where the money path is spoken; the untrusted handler is not on it.

proxynet (internal)

The handler to the data proxy. The handler’s only egress path, and it is deny-by-default.

upstreamnet (internal)

The data proxy to its allowed upstreams, and the facilitator to the Arc RPC endpoint.

redisnet (internal)

Redis and the data proxy.

backendnet (internal)

Postgres, the facilitator, and the marketplace.

The handler and sidecar being two containers is the point. A compromised handler holds nothing worth stealing and has no route to the facilitator, the chain, Postgres, or Redis. The trust boundary is enforced by the network split, not by convention. See egress and the static gate.

Where to go next

The deploy pipeline

The ordered steps a bundle runs through, from auth to a running paid endpoint.

Provisioning a host

The gVisor host, wildcard TLS, durability, and the systemd deployer.

The sandbox

How untrusted generated code is isolated at runtime.

Self-hosting the stack

The practical run shape: install, env, test, compose up.