System architecture

This page explains how Capsem’s clients, shared service, and per-VM workers work together to run agents and tools in Linux VMs on your computer. It follows VM creation, traffic handling, record storage, and shutdown so you can identify which component owns each part of the work.

Control and data

Legend

• Components, inputs and outputs
  No host-permission level assigned by this diagram.
• Control and processing
  Components or stages that manage and process operations.
• Per-VM ownership
  Dashed boundary groups components assigned to one VM.
• VM hardware boundary
  Separates the Linux VM and its workload from host processes.

From	Connection	To
@capsem/mcp	SDK	CLI · TUI · Capsem UI · SDKs
CLI · TUI · Capsem UI · SDKs	authenticated API	Gateway
Gateway	HTTP over Unix socket	Service
Service	lifecycle / grants · control	VM owner
Service	policy / capabilities · control	Security engine
Service	producer / reader grants · control	Log writer
OCI container	terminal / traffic / tools · bidirectional	Guest helpers
VM owner	vsock control · bidirectional	Guest helpers
Guest helpers	vsock traffic	Security engine
Security engine	audit records	Log writer
VM owner	VM records	Log writer
Security engine	allowed traffic on granted connections	Upstream services

Create and operate a VM

The CLI, TUI, Capsem UI, and SDKs send VM requests through the gateway. The gateway authenticates the caller; the service selects the VM and sends typed commands to its owner. Clients cannot connect to VM-owner control sockets.

For creation, the service admits the image and settings, prepares the VM’s storage, and starts its workers. The VM owner boots Linux and connects guest helpers over vsock, a host–VM transport. Terminal input, commands, and file operations follow these channels. Image creation returns after the workload reports readiness.

Process traffic

Guest networking sends supported HTTP, HTTPS, and DNS traffic to the VM’s security engine. It parses traffic, evaluates rules, requests authorized credentials, and forwards allowed operations over service-granted connections. Required audit records go to the log writer before the operation proceeds.

Private networks connect guest interfaces through a separate switch process. Published ports use a separate relay. Neither path passes through HTTP inspection. See the network boundaries.

Run model requests without a VM

capsem proxy creates a separate security engine and log writer for a model client running on your computer. The CLI controls the lease through the authenticated gateway; the model client sends requests to a separate HTTP listener. The service accepts connections and passes connected sockets to the confined engine. No VM owner, guest helper, or container is started.

Legend

• Limited host permissions
  Assigned files, credentials, or upstream connections.
• Maximum host permissions
  Launching-user permissions or trusted coordinator authority.
• Components, inputs and outputs
  No host-permission level assigned by this diagram.
• Per-VM ownership
  Dashed boundary groups components assigned to one VM.

From	Connection	To
capsem proxy	authenticated control	capsem-gateway
capsem-gateway	HTTP over UDS	capsem-service
Model client on host	model API requests	Service data listener — HTTP · unauthenticated
capsem-service	bind / accept · control	Service data listener — HTTP · unauthenticated
Service data listener — HTTP · unauthenticated	connected sockets	capsem-proxy — Security engine
capsem-service	policy / capabilities · control	capsem-proxy — Security engine
capsem-service	ledger grants · control	capsem-ledger — Temporary records
capsem-proxy — Security engine	audit records	capsem-ledger — Temporary records
capsem-proxy — Security engine	allowed requests service-granted connections	Configured model provider

The provider configuration fixes the upstream destination and wire protocol. The engine applies policy, credential processing, and logging through the same pipeline used for VM traffic. The listener is unauthenticated HTTP, so keep it on loopback. This mode cannot restrict the host client’s other activity. Follow Use model APIs through the proxy to connect a client, or use the Proxy reference to implement lease control.

State and ownership

Scope	Owners and state
Shared	Service, gateway, credential store, installed runtime assets, image cache, and settings.
Per VM	VM owner, security engine, log writer, native MCP workers, guest filesystem, and ledger.
Per proxy lease	Security engine, log writer, provider routing, and temporary records; no VM.
Per private network	Switch process, member cables, and network audit records.
Per published connection	Granted host and guest connections passed to the VM’s expose relay.

Named VMs retain their files when stopped. Suspending also saves running VM state; forking copies a VM’s files into another persistent VM. A fork starts programs afresh. The log writer owns ledger access for both live and retained VMs.

Stop and retire

The service revokes the original worker generation and waits for its processes to exit before retiring its resources. Managed SDK jobs renew a finite lease; lost renewal lets the service clean up after a client crash.

The security architecture describes process permissions, grant authentication, revocation, and the trusted components.