Project modules¶

Quarshell is split across 20 independent Go module repositories plus client, documentation, deployment, and workspace repositories. Go APIs are pre-stable: module tags stay in 0.x until the project declares an API stable. The list below describes each repository's responsibility; it does not claim complete OpenShell parity. See compatibility status for implementation gaps.

Go modules¶

Module	Responsibility
`quarshell-cli`	`cautem` command line, gateway selection, sandbox lifecycle, policy commands, interactive terminal, completions, installer and bundled local Gateway.
`quarshell-core`	Shared domain types, defaults, policy schema and evaluation primitives, host matching, resource admission, and OpenShell compatibility helpers.
`quarshell-policy`	Bounded policy parsing, validation, typed evaluation inputs and policy composition for sandbox/runtime components.
`quarshell-prover`	Symbolic and solver-backed policy containment and risk analysis.
`quarshell-providers`	Built-in provider profile catalog and composition of provider requirements into effective policy.
`quarshell-credentials`	Credential storage backends and token grant/refresh primitives; secret values stay outside sandbox filesystems.
`quarshell-proto`	Pinned OpenShell protobuf schemas and generated Go, gRPC, Connect and TypeScript bindings.
`quarshell-spi`	Public service-provider contracts for compute, credentials, isolation and extensions.
`quarshell-driver`	Compute `Backend` SPI plus Docker, Podman and experimental Kubernetes implementations.
`quarshell-driver-vm`	MicroVM lifecycle, worker, guest agent, image import, networking, terminal and recovery. Some OpenShell VM behaviors remain partial.
`quarshell-driver-mxc`	Reserved independent boundary for the Windows MXC driver. Its OpenShell behavior has not yet been ported.
`quarshell-gateway`	Gateway API and RPC server, authentication, sandbox/workspace orchestration, state, policies, providers, service routing and backend composition.
`quarshell-sdk`	Go client for Gateway RPC: typed resources, sandbox operations, streaming, identity and session helpers.
`quarshell-proxy`	Sandbox egress enforcement, CONNECT and application-layer mediation, credential rewriting, policy advisor and audit events.
`quarshell-runtime`	Sandbox/guest init, hardening, secrets support, runtime helpers and sandbox image sources.
`quarshell-isolation`	Host-side Linux process isolation and admission primitives, including supported cgroup/seccomp/Landlock paths.
`quarshell-supervisor`	Host-side process execution, PTY sessions, lifecycle state and supervisor reporting.
`quarshell-display`	GUI sandbox and password-protected noVNC helper integration.
`quarshell-slogx`	Structured logging helpers for `log/slog`, trace correlation, redaction, live level control and bounded payload dumps.
`quarshell-telemetry`	Independent telemetry module boundary. The OpenShell telemetry pipeline is not implemented there yet.

Other repositories¶

Repository	Responsibility
`quarshell-python`	Python client SDK for Gateway operations over the OpenShell RPC contract.
`quarshell-ui`	Browser console for OIDC login and Gateway workspace, sandbox, policy and provider management.
`quarshell-deploy`	Helm chart and platform packaging assets for deployments.
`sandbox.dev`	English and Russian user guides, architecture, compatibility and migration status, built with MkDocs.
`quarshell-workspace`	Cross-module checkout, version pins, task orchestration, integration checks and migration plans. It does not contain the product module source.

How a request flows¶

flowchart LR
    cli["cautem CLI"] --> sdk["Go / Python clients"]
    ui["Browser UI"] --> api["Gateway API / OpenShell RPC"]
    sdk --> api
    api --> gw["Gateway orchestration and state"]
    gw --> spi["Compute SPI"]
    spi --> docker["Docker / Podman"]
    spi --> vm["MicroVM"]
    gw --> providers["Providers and credentials"]
    gw --> policy["Core policy and prover"]
    docker --> proxy["Egress proxy"]
    vm --> runtime["Guest runtime and supervisor"]
    proxy --> policy

The dependency direction is intentional: clients call the Gateway; Gateway maps protocol requests to domain contracts and registered backends; backends use their engine/runtime integrations. UI code does not import CLI internals, and Gateway does not import the CLI or browser UI.

Current implementation status¶

Docker and Podman are the primary container backends; Podman support depends on the host socket and feature set described in the provider guide.
Kubernetes is experimental and must be validated against a target cluster.
VM support is in active OpenShell parity work; consult the remaining-work register before relying on a specific lifecycle path.
MXC and telemetry are independent module boundaries with unported behavior.
Public Go module APIs are pre-stable and versioned v0.x.y.