Umbra

August 20, 2026 ยท View on GitHub

Umbra runs AI coding agents in attested cloud sandboxes with governed network and secret access. Developers use a CLI to create and enter Dev CVMs; all sandbox egress is forced through an entity Security CVM for policy enforcement, secret scanning, proxy-time credential injection, and traffic logging.

Umbra is pre-1.0 software. Interfaces, deployment requirements, and compatibility may change between minor releases. Only the latest pre-1.0 release is supported; see versioning.

Architecture

Umbra v0 architecture: the umbra CLI talks HTTPS REST + OIDC to the Console control plane (Postgres-backed, provisioning CVMs through TDX and DNS providers); developer SSH, editor, and agent sessions reach the Dev CVM over a locally verified aTLS tunnel; all sandbox egress is forced through the dev-egress-forwarder to the entity Security CVM's mitmproxy, which enforces policy, scans for secrets, injects credentials, and emits traffic logs before re-encrypting traffic to the internet; the Security CVM pulls policy from and sends traffic logs to the Console.

ModulePathRole
CLIcli/Authentication, local state, CVM lifecycle, verified tunnels, SSH/editor/agent sessions, profiles, audit, and traffic logs.
Consoleconsole/HTTPS control plane for OIDC, sessions, RBAC, resource state, orchestration, policy, audit, and reconciliation.
Dev CVMcvms/dev/Per-developer TDX sandbox with SSH, persistent sessions, Docker, and fail-closed egress forwarding.
Security CVMcvms/security/Per-entity egress proxy for policy, DLP, credential injection, CA export, and traffic-log emission.

The Console is a conventional HTTPS control plane. The attested Dev and Security CVMs are the confidential-compute boundary. The trust model and component contracts are described in the v0 plan, the supply-chain threat model, and the documents under docs/specs/.

Try the CLI

If an operator has already provisioned your account and assigned a profile:

After the first approved release and its provenance are published, install the CLI with the SLSA-verified procedure in the developer quick start. A source build is the documented path before that launch gate. Then:

umbra auth login https://console.example.com
umbra cvm launch
umbra ssh

See the developer quick start for SSH keys, editors, Claude Code, Codex, and common troubleshooting.

Self-host

A live deployment currently requires a Linux host plus accounts or credentials for an OIDC provider, DNS, a supported TDX CVM provider, a container registry, and persistent Postgres. These services may be paid and their cost depends on region and instance size.

Start with:

The committed environment files contain reserved examples only. Put secrets in the gitignored layers described by the setup guide, never in a tracked file.

Develop

The normal contributor gates are local and do not require maintainer cloud credentials:

make build
make check
make test

Read the module README before changing a component:

Specs are the behavioral contract. A behavior change should update its spec, implementation, tests, and affected README together. See CONTRIBUTING.md and AGENTS.md for repository conventions.

Security boundary

Umbra governs traffic opened by processes inside the Dev CVM network namespace. Local workstation tools and provider-hosted editor or browser tools may open their own network connections outside that boundary. Use an agent or shell running inside the Dev CVM when Security CVM egress enforcement is required.

Do not use an attestation bypass in a production or release-verification path. The temporary Security CVM image-policy deviation is documented openly in docs/sc-policy-check-disabled.md.

Report vulnerabilities privately as described in SECURITY.md.

Project information

Licensing terms are in LICENSE.txt.