Secure Optimized Machine Architecture
Give every agent a body built to be trusted.
The name describes the role. The model is the mind, while SOMA is the disposable machine body that executes its work.
For engineers, SOMA is an open-source sandbox engine for Linux workloads from OCI images. It provides a small CLI, a portable Rust interface, and an MCP server for agents, backed by explicit lifecycle and execution evidence.
| I want to understand or do this | Open this file |
|---|---|
| Learn what the sandbox, VMM, KVM, guest, Template, Generation, and Instance are | Beginner architecture guide |
| Follow one sandbox end to end, from Template to cleanup, as it exists on the Linux KVM path today | How one SOMA sandbox works today |
| Prove the whole flow still works on a host, from setup to a sandbox that left nothing behind | The end to end check |
| See exactly what sits on top of what, what connects, and which pieces are required | What makes one SOMA sandbox |
| Understand the measurable engineering bar for state-of-the-art admission | SOMA engineering standard |
| See every capability against one status vocabulary with its evidence | Claim ledger |
| See the complete machine as plain-text pictures | SOMA visual atlas |
| Understand where Node, Python, shells, and user agent programs come from | Workload selection and execution |
| Build reusable templates for Claude Code, Codex, OSA, Hermes, or another workload | Composable template system |
| Author a Template from a working example and see every field in one table | Templates |
| Write your first Template and learn what the Template compiler accepts, rejects, and locks | Creating a Template |
| Implement the template system in dependency order | Template implementation map |
| Understand vCPUs, overcommit, shared memory, and how 200 sandboxes fit on 80 threads | Host capacity and density |
| Learn capacity incrementally from one sandbox through larger Hosts and overload | Incremental capacity ladder |
| See what limits 100,000 sandboxes and how a fleet reaches that scale | 100,000-sandbox model |
| Find the exact meaning of a SOMA or virtualization term | Glossary |
| Navigate every Rust crate and responsibility | Module map |
| Compare Docker, Apple VMs, and Linux KVM honestly | Local sandbox reality |
| Implement or continue the Linux custom VMM | Linux VMM handoff |
| Follow the remaining VMM work in dependency order | VMM decision map |
| Understand the researched production architecture and credible path to 10 ms | Production sandbox architecture research |
| Understand the custom Rust VMM, KVM ownership, memory, vCPUs, virtio, snapshots, and exact implementation tickets | Rust VMM engineering deep dive |
| Compare hidden Rust VMM repositories and the exact ideas SOMA should borrow or reject | Rust VMM GitHub hidden gems |
| Review the broad GitHub VMM census, mistakes, failure patterns, and resulting SOMA guardrails | Rust VMM GitHub census and failure atlas |
| Compare the newest finds directly with SOMA and decide what to adopt, adapt, or reject | Competitive module adoption audit |
| Integrate Claude Code, Codex, OSA, Hermes, or another agent | Agent integration guide |
| Evaluate isolation and security claims | Threat model and security policy |
| Read the current overall engineering assessment | Dated engineering assessment |
| Review and repair the independently collected Isorun telemetry before relying on it | Isorun evidence review |
| Understand performance measurements and claims | Benchmark contract |
| Contribute code or documentation | Contribution guide |
- One explicitly identified Linux container per local Docker sandbox today, with a custom hardware-isolated VMM planned for Linux hosts.
- Direct argument-vector execution without a host shell.
- Bounded commands, time, output, and control responses.
- User-selected CPU, memory, storage, image, and human-readable Machine metadata.
- Exact OCI manifest identity with explicit observed-only or launch-enforced binding evidence.
- Fail-closed platform selection with no silent downgrade to host processes or namespace-only isolation.
- Evidence-carrying receipts for workload identity, Instance identity, isolation, preparation, shape, timing, command outcome, and cleanup.
- One portable use-case surface for humans, agents, and cloud control planes.
The current working local path uses Docker Desktop on macOS or Docker Engine on Linux.
Docker must be running.
The Docker Backend resolves the Host's own architecture, so an x86_64 Host uses linux/amd64 images and an ARM64 Host uses linux/arm64.
git clone https://github.com/Miosa-osa/SOMA.git
cd SOMA
cargo run --locked -p soma-cli -- doctor
cargo run --locked -p soma-cli -- --backend docker run node:22 -- /usr/local/bin/node --versionThe final command pulls or reuses node:22, creates a constrained Docker container, runs Node directly, returns its exact bytes, and proves cleanup.
Use --backend docker to select Docker explicitly.
Ubuntu, Python, Kali, and other compatible Linux ARM64 OCI images use the same interface.
This local path is a container boundary inside Docker Desktop's Linux VM, not a per-sandbox hardware VM.
The Apple backend creates a Linux VM through Apple Virtualization. The Docker backend creates a Linux container inside Docker Desktop's Linux VM. Both are usable local SOMA sandbox paths, with different isolation guarantees.
The custom Rust KVM VMM and other Linux-KVM VMMs require Linux /dev/kvm and cannot run natively on macOS.
A Docker image can compile the VMM and run KVM-independent tests, but Docker Desktop does not turn the Mac into a reliable nested-KVM host.
Real VMM execution and latency benchmarks belong on a Linux KVM host.
Every run or managed launch carries an explicit Machine shape with vCPU, memory, and writable-storage dimensions. It can also carry a bounded human display name, while a globally unique Instance ID remains the only lifecycle and ownership identity.
OCI layers are the reproducible customization mechanism. Change a Dockerfile or build input, produce a new image digest, and SOMA resolves that digest into a separately identified Generation instead of mutating a shared base VM. Persistent mutable project data will use an explicitly sized workspace volume with its own ownership contract, while disposable Machine state is destroyed after use.
Backends must report each effective dimension independently. If a backend cannot prove that a requested disk, CPU, memory, or network property was enforced, the receipt reports that dimension as unavailable rather than inventing a value. The current Apple development backend enforces requested CPU and memory but reports root writable-storage enforcement as unavailable.
SOMA exposes bounded stdio MCP tools for one-shot execution and managed launch, execute, inspect, stop, and destroy operations. Guest commands are structured argument arrays rather than shell strings, and arbitrary binary output is returned with explicit base64 encoding.
Claude Code, Codex, OSA, Hermes, and other MCP clients can use the same local server. See the agent integration guide for exact setup and tool contracts.
SOMA treats security state as evidence instead of a marketing label. The interface records what was observed, what was enforced, what remained unavailable, and whether owned resources were cleaned up.
The current implementation includes constrained Docker-container execution for local development, direct process invocation, strict input bounds, output and timeout enforcement, ownership checks before lifecycle mutations, redacted diagnostics, typed failures, and dependency and secret scanning.
On the KVM path a reusable Generation carries public identity only: the responder static secret is sampled fresh for every Instance and delivered in the non-snapshot launch page, so retrieving every artifact of a Generation grants no guest authentication authority.
The production design additionally requires authenticated guest readiness, fresh identity repair, private copy-on-write memory and disk state, a constrained VMM process, and certified immutable Generations before stable 1.0.0.
Read the threat model and security policy before evaluating trust claims. Report vulnerabilities privately rather than through a public issue.
Portable clients and local isolation engines earn support independently. An unsupported local engine returns an explicit error and never runs the workload on the host as a fallback. Status words below are the five terms defined in the engineering standard, and the claim ledger lists every capability against them.
| Host | CLI, library, and MCP | Local sandbox engine | Current evidence |
|---|---|---|---|
| macOS with Docker Desktop | Native validation | Linux container per OCI sandbox inside Docker's Linux VM | Live Ubuntu and Node 22 lifecycle, command, and cleanup validation |
| Ubuntu 24.04 and 26.04 x86_64 | Native CI | KVM capability probe; test-only cold boot of a compiled Generation and test-only snapshot capture and restore | Live-proved at 71161ea: a compiled busybox Generation booted on a real host with the five virtio-mmio devices, the static guest agent authenticated over vsock, one bounded command returned its bytes and exit status, and cleanup was proven. Live-proved at 7c1127d: a node:22 Generation was captured at its repair point and restored repeatedly into independent authenticated Instances. Both runs are historical, because the guest authority model changed afterwards, so on current bytes this path is component-tested. No network egress, jail, prepared workers, or sandbox lifecycle process |
| Windows Server 2025 x86_64 | Native CI | None | Portable client only |
| Linux ARM64 | Native development validation | KVM capability probe | Explicit-fixture cold boot and direct command execution exist only as dedicated ignored tests, not a custom sandbox lifecycle |
| Intel macOS, Windows ARM64 | Compile gate | None | Portable client only |
Linux OCI guests are the first workload contract. An authenticated remote engine is planned for clients without a supported local engine, but it is not implemented in this alpha. The deployment portability contract explains how suitable AWS, Google Cloud, other Linux cloud, and on-premises hosts earn engine support while managed function runtimes remain remote callers.
human CLI agent MCP Rust caller
\ | /
portable SOMA use-case facade
|
capability-gated backend seam
/ \
Apple Container 1.3 SOMA KVM path
development backend production target
| |
Linux ARM64 VM soma-vmm + Linux VM
The latency-sensitive production design uses a node-local prepared-worker allocator, one VMM process per Machine, immutable Generation artifacts, private copy-on-write state, and one fused authenticated repair and readiness operation. Provider placement, billing, tenant policy, and public control planes remain outside this repository. The complete architecture diagrams include the one-shot transaction, 100-sandbox burst path, durable managed lifecycle, customization flow, and security boundaries.
These are admission targets for the future certified KVM engine, not current benchmark claims.
| Measured boundary | Target p50 | Target p99 |
|---|---|---|
| Complete server-side create | Below 5 ms | Below 10 ms |
| First bounded command from accepted launch | Below 10 ms | Below 20 ms |
| Exact 100-way ComputeSDK Burst TTI | Below 50 ms median | Below 90 ms |
Every published result must retain raw samples, failures, cleanup outcomes, cache state, and the exact timer boundary described in the benchmark contract.
The source version is 1.0.0-alpha.1.
The first stable release will be 1.0.0 only after the custom Ubuntu 24.04 x86_64 KVM path can build an OCI-derived Generation and complete real launch, authenticated command readiness, execution, cleanup, isolation, and burst-performance gates.
The current custom-VMM tracer bullets are the test-only ARM64 explicit-fixture cold-boot proof and challenge-bound guest-command proof.
Their retained cold-boot and command results are diagnostic evidence, not published performance benchmarks.
The workspace also contains a bounded deterministic OCI-layout importer, a canonical logical rootfs normalizer, a Generation compiler for phases 1 through 3 and 6, a static Linux guest agent, a snapshot format and its live x86_64 capture and restore, a privileged network broker, an XFS reflink storage profile, a VMM jail launcher, and a prepared-worker allocator.
Every one of those is component-tested, and several have live-proved runs whose commits and evidence are named in the claim ledger.
The retained real Node 22 OCI-import verification and Apple hardware-VM one-shot validation document the exact current evidence and its nonclaims.
Nothing is integrated: no end-to-end Instance receipt covering allocation through proven cleanup exists, the proven KVM runs were driven by test processes rather than the soma-vmm binary, and the public KVM Backend still answers every lifecycle call with a typed unavailable failure.
The next implementation boundary is one real KVM Instance through soma-hostd, a real soma-vmm, the jail, prepared storage, TAP networking, authenticated guest execution, and complete cleanup, exposed through the public Backend.
The roadmap lists the evidence required for each phase. The competitor and prior-art ledger separates primary-source facts, external claims, unknowns, transferable lessons, and measured results.
SOMA welcomes contributors in virtualization, Linux systems, Rust, security, OCI tooling, performance engineering, agent protocols, testing, and documentation. Start with the contribution guide, mission, module map, and accepted architecture decisions.
Please use the design issue template for interface, topology, snapshot, trust, or compatibility changes. Security findings follow the private process in SECURITY.md.
SOMA source code is licensed under Apache License 2.0. MIOSA and SOMA names and logos remain subject to the attribution and marks terms in BRAND.md.