Run a coding agent’s session on a remote Linux worker.

A Mantle session is one agent, one workspace with its Git repositories, and one toolchain. Mantle runs the whole session on a remote Linux worker, not single build commands. The source of truth during the session is the remote workspace; publish work with Git from inside the session.

• Laptop. The mantle CLI reads your manifest, provisions the worker, keeps local records and renders the terminal.
• Worker. A Linux VM on AWS EC2 or KubeVirt. It runs the Substrate daemon and Mantle’s egress gateway.
• Substrate. Creates the confined workspace, runs the agent in a sandbox, holds the Claude credential in a secret slot and reports what it observed.

The architecture page shows which layer owns what. The security model lists what the sandbox does and does not protect against.

• A Linux x86-64 laptop with ssh. The release manifest records the glibc the GNU CLI was built against (2.39 for 0.2.0); older glibc, macOS and ARM are not qualified.
• For an AWS worker: the AWS CLI, session-manager-plugin, and an authenticated profile that may create the EC2, IAM and CloudWatch resources worker provisioning uses.
• For a KubeVirt worker: kubectl and virtctl with access to the cluster. The local test bed (task k3d-up) also needs Docker, k3d and nested virtualization.
• For Claude Code: an OAuth token from claude setup-token. For Codex: a ChatGPT account for device login; no API key.
• To install a release: curl, jq, sha256sum and tar. No Rust compiler.

mkdir mantle-0.3.1 && cd mantle-0.3.1
for f in manifest.json SHA256SUMS \
    mantle-0.3.1-x86_64-unknown-linux-gnu.tar \
    mantle-0.3.1-x86_64-unknown-linux-musl.tar; do
  curl -fLO "https://github.com/beyond10x/mantle/releases/download/0.3.1/$f"
done
jq -r .source_commit manifest.json   # must be the commit tagged 0.3.1
jq -r '.artifacts[] | "\(.sha256)  \(.name)"' manifest.json | sha256sum --check
mkdir bootstrap
tar --extract --file mantle-0.3.1-x86_64-unknown-linux-gnu.tar \
  --directory bootstrap --no-same-owner bin/mantle-release
./bootstrap/bin/mantle-release verify --manifest "$PWD/manifest.json"
./bootstrap/bin/mantle-release install --manifest "$PWD/manifest.json" \
  --prefix "$HOME/.local/mantle"
export PATH="$HOME/.local/mantle/bin:$PATH"

This installs mantle, mantle-release and mantle-acceptance. The worker helpers stay in the musl archive; extract them for the first worker up:

mkdir -m 0700 worker-stage
tar --extract --file mantle-0.3.1-x86_64-unknown-linux-musl.tar \
  --directory worker-stage --no-same-owner \
  bin/mantle-egress bin/mantle-launch bin/mantle-worker

These commands have not yet been run against the 0.3.1 assets. The same commands, naming 0.2.0, were run against the published 0.2.0 assets on 2026-10-29: checksums OK, verify and install exit 0, mantle --version printed mantle 0.2.0. What each step proves, and the source build, are on Releases and verification.

1. Configure the worker

   Copy examples/config.toml to ~/.config/mantle/config.toml, choose provider = "aws" or "kubevirt" and replace every placeholder. For Claude Code, set claude.token_command to a command that prints your token. Field reference: configuration.

2. Describe the session

   Save as mantle.yaml. For Codex, set kind: codex and auth: chatgpt-device (agent kinds).

   apiVersion: mantle.beyond10x.dev/v1alpha1
   kind: Session
   metadata:
     name: my-project
   workspace:
     repositories:
       - name: mantle
         repository: https://github.com/beyond10x/mantle.git
         ref: main
         mount: mantle
   agent:
     kind: claude-code
     cwd: /workspace/mantle

3. Bring up the worker and start

   mantle worker up --binaries "$PWD/worker-stage/bin"
   mantle start mantle.yaml

   The first worker up creates the VM, installs Substrate 0.16.1 (release 0.2.0: 0.7.10), the Rust 1.97 toolchain, Claude Code 2.1.287, Codex 0.153.4 and the Mantle helpers, and checks Substrate’s facts. start clones the repositories into the workspace, starts the agent and attaches. Press Ctrl+], then d, to detach.

4. Come back, stop, clean up

   mantle attach my-project
   mantle stop my-project            # agent ends; workspace kept
   mantle destroy my-project --yes   # workspace deleted
   mantle worker down                # VM stopped; data volume kept

   All commands: operations. An AWS worker stops itself after two hours below 2% average CPU unless brought up with --no-idle-stop.

The worker steps are not re-run for each documentation change. The last recorded live runs are listed under what is verified.