Mantle decides what development session you want and where it runs. Substrate decides nothing about products: it runs processes in confined workspaces on one host and reports what it observed. Mantle depends on Substrate through its SDK; Substrate has no Mantle code in it.
01 / Layers
Four layers, two machines.
The four layers of a Mantle session
Layer
Runs on
Owns in 0.3.1
Laptop: the mantle CLI
Your Linux laptop
Manifest parsing and validation; worker provisioning through the AWS SDK or kubectl; local session and worker records in SQLite (state.db); the SSH key and pinned host key; the SSH tunnel to the Substrate socket; terminal rendering; lifecycle, profile and doctor commands.
Mantle on the worker: three static helpers
Worker host and sandbox
mantle-egress: the CONNECT gateway on 127.0.0.1:3128 with a fixed allowlist, on the host outside every sandbox. mantle-launch: inside the sandbox, holds the agent on a pseudo-terminal and relays attachments through FIFOs. mantle-worker: installs pinned Codex and checks or applies offline helper upgrades under a host lock.
Confined workspaces, guarded file operations, process execution with timeouts and leases, PTY sessions, secret slots, the named egress aperture, cgroup and quota facts, durable operation identity and observed state.
Worker: one VM
AWS EC2 or KubeVirt
Ubuntu 24.04, build pinned by ubuntu_serial. Cloud-init installs build packages, Rust 1.97 under /opt/mantle, Claude Code 2.1.287 by checksum, and the Substrate daemon from its signed release archive, checked against pinned digests (release 0.2.0: from a digest-pinned signed image). Workspaces live on an XFS data volume with project quotas at /var/lib/substrate.
Mantle never reports an isolation guarantee Substrate did not report. When the worker lacks a fact the session needs, the start is refused by name; Mantle does not fall back to an unconfined shell. Requested and applied resources are printed separately, and an execution whose outcome Substrate does not know is shown as unknown.
02 / Diagram
Where the boundaries are.
Substrate turns a Linux host into a service for confined workspaces and processes. Mantle uses that service to place the session, start the agent and connect your terminal.
Inside a Mantle session
Laptop, worker host, sandbox, external services.
Release 0.3.1
01 / Developer laptop
Mantle CLI
Session intent & placement Local records & terminal
A Control + terminal
SSH forwards the Substrate Unix socket through AWS SSM or the KubeVirt virtctl tunnel.
→
The laptop is the control surface. The agent and its tools run on the worker.
mantle-launch → Claude Code, Codex or a declared command + tools
The launcher holds the agent’s PTY. Attachments relay through workspace FIFOs.
Read / write/workspace
Repositories & session state
Read only/opt/mantle
Agent, launcher & toolchain
↳ Direct network egress denied; the named aperture is the way out.
C Network access
Sandbox → egress aperture → host gateway
↓
Mantle CONNECT gateway
Outside the session sandbox · worker loopback
Fixed destination allowlist
↓
04 / External servicesHTTPS · port 443
AnthropicChatGPT / OpenAI authGitHubcrates.io
Ten exact host/port pairs. IP-literal targets are refused; non-public resolved addresses are never dialled.
Trusted hostConfined executionLabels A–C identify the paths across boundaries.
03 / Who owns what
Policy in Mantle, mechanism in Substrate.
From the design, §4, §7 and §8, reduced to what 0.3.1 implements.
Mantle owns
Session intent: the manifest, the agent, the runtime profile, the repositories, requested resources.
Placement and provisioning: one worker per configuration, on AWS or KubeVirt; bootstrap and helper installation.
Environment: the rust-dev toolchain under /opt/mantle, the agent adapters for Claude Code and Codex, the compiler and proxy environment.
Sources: HTTPS repositories at a branch, tag or commit; the checked-out commit is recorded.
Lifecycle: start, attach, detach, stop, restart, destroy, and the local record of each.
The egress allowlist, enforced by its gateway outside the sandbox.
Substrate owns
Creating the confined workspace and guarded file operations in it.
Running processes and PTYs, with output observation, cancellation, timeouts, leases and whole-tree cleanup.
Durable operation identity: an interrupted request can be observed again instead of repeated.
cgroup, quota and egress facts, and the facts each run actually applied.
The secret-slot mechanism and the authenticated host API on a Unix socket.
A session is the unit of placement: Mantle never places single cargo commands remotely. The terminal is not the session: closing an attachment leaves the agent running until its execution ends. Once a session starts, the remote workspace is the source of truth for it; edits do not mirror back to the laptop.
04 / Paths across boundaries
Control, credentials, network.
A. Control and terminal
The CLI opens SSH to the worker through a provider ProxyCommand: aws ssm start-session with AWS-StartSSHSession on EC2, virtctl port-forward --stdio on KubeVirt. The worker has no inbound port either way; the AWS security group has no ingress rule. SSH forwards the daemon’s Unix socket to a private local socket, and the CLI speaks the Substrate SDK over it. mantle attach opens a PTY session running mantle-launch attach, which relays to the agent through FIFOs in /workspace/.mantle/agent; the sandbox refuses Unix sockets, so tmux and screen do not run inside it.
B. Credentials
Claude: worker up writes the token from your laptop to /var/lib/mantle/secrets/claude on the worker; Substrate hands it to the agent execution through the claude secret slot on descriptor 3; the launcher moves it into the agent’s environment. Codex: device login in the agent terminal; the auth file lives in /workspace/.mantle/home/.codex. Details and limits: security model.
C. Network
The sandbox has no network of its own. Substrate declares one aperture, egress, to the host gateway at 127.0.0.1:3128. The gateway admits ten exact host:443 pairs: the list.
05 / Designed, not built
What the design describes and 0.3.1 does not do.
The design document is a proposal; its correction block lists where the first slice differs. These parts are not implemented:
A coordinator service, worker fleets, scheduling, Spot capacity and scale-out. Mantle 0.3.1 manages one worker named default; placement in a manifest is accepted and ignored.
Remote TLS with an identity provider. The CLI reaches Substrate over SSH, not HTTPS.
A Git credential broker, publishing back from Mantle, and starting from a dirty local checkout.
Session-to-session communication, shared build caches, workspace snapshots and recovery of a lost worker or volume.
Per-session network policy. The allowlist is fixed per worker.