Tacy

Tacy runs AI agents in confidential VMs. Your requests are encrypted to a key that exists only inside a VM whose code you can check, so nobody else can read them, us included.

What this is

The code inside Tacy's trust boundary: everything the agent VM runs, how its definition is built reproducibly, and the verifier that checks a running VM before anything is sent to it. Everything outside the boundary (the web app, the relay, the control plane) only sees ciphertext and metadata, and isn't here (What's not here).

What it proves

Attestation proves which code a VM runs. It proves nothing about what that code does. So the code has to be public, rebuildable, and every release signed in a public log. Together:

• The key is the VM's. An Intel TDX quote binds the VM's per-boot encryption key to its measured boot chain and to the hash of its compose.yaml (How it works).
• The VM runs a release from this repository. That compose hash must be signed by this repository's release workflow on a version tag, logged in Sigstore's public Rekor log (Releases and signing).
• The release is this source. Anyone can rebuild a release and get the same compose, binary hashes and image digests (Reproduce).
• Underneath is a known OS on a known VM shape. The firmware, kernel, initramfs and root filesystem are pinned measurements (Boot measurements).

What it doesn't prove, and what you still have to trust, is listed under What's not here.

How to verify a release

1. The signature. Check that a release's compose.yaml was signed by this repository's release workflow on its tag (needs the GitHub CLI):

   gh release download v0.19.1 --repo tacyhq/tacy --pattern compose.yaml
   gh attestation verify compose.yaml --repo tacyhq/tacy \
     --signer-workflow tacyhq/tacy/.github/workflows/release.yml --source-ref refs/tags/v0.19.1
   

2. The build. Rebuild the tag and compare it with its release.json and with the images ghcr.io serves (needs docker, git, curl and jq):

   scripts/reproduce.sh v0.19.1
   

3. A running VM. The browser checks the VM's attestation before every request: 16 checks, in the same Go code as verifier/ and release/ (How the browser verifies a VM).

Release history is in CHANGELOG.md. To report a vulnerability, see SECURITY.md.

What's here

How it works

1. Boot. The VM (Intel TDX, dstack 0.6.1) runs compose.yaml: four processes, each in its own container with its own uid, linked only by unix sockets (docs/21, docs/22): agentd (front door and runtime), runnerd (service runner: runs the brain, the agent loop, untrusted, in a gVisor sandbox), gatewayd (service agentvm, the only one with a network) and vaultd (the keys). Each container runs one image from ghcr.io/tacyhq/tacy/<name>, named by digest in the compose (no tag, nothing built on the VM); a one-shot setup container (root, no network) first gives the processes their directories. agentd makes a fresh HPKE key in memory.
2. Attest. GET /attest?nonce=<64 hex> returns a TDX quote whose report_data is sha512("sealed-agent-vm/v1" || 0x00 || nonce || hpke_public_key), plus the event log and the app compose.
3. Verify. The client checks the quote (Intel signature chain, collateral, revocation, TCB, debug off), the key binding, the event log replay to RTMR3 and the compose hash, a production OS image, pinned boot measurements (MRTD, RTMR0-2: firmware, kernel, initramfs, root filesystem and VM size), the pre-launch script, no init script, that the compose is a signed release, and that it names every image by digest (16 checks).
4. Run. Requests and responses are encrypted to the verified key. No request logs; a run's task and journal sit in the queue on the VM's encrypted disk while it runs and are deleted when it ends. What the run did (calls, hosts, sizes, leases, codes; no content) goes on a signed activity record sealed to the person's own key (docs/24).

How the browser verifies a VM

The web app loads the WebAssembly verifier (wasm/, built with scripts/build-wasm.sh; JavaScript entry point globalThis.sealedAgentVM). For each VM it:

1. asks the VM for /attest with a fresh random nonce;
2. fetches the Sigstore bundle for the attested compose's sha256 from GitHub's attestations API (through a relay, which can't forge one);
3. runs verifyRelease: every check above, in the same Go code as verifier/ and release/;
4. only if all checks pass, encrypts the request to the HPKE key the quote binds.

The release check accepts a compose only if this repository's release workflow signed it on a version tag at or above the pinned minimum (below).

Reproduce the compose, binary hashes and image digests

mise exec -- go run ./cmd/compose --check

It builds the six binaries (agentd, brain, gatewayd, runnerd, vaultd, setup) for linux/amd64 (CGO_ENABLED=0, -trimpath, no VCS stamp, Go 1.27.2) and makes one image per process: the pinned base gcr.io/distroless/static-debian13 (by its linux/amd64 manifest digest) plus one layer holding only /tacy/<name> (owner 0:0, mode 0555, time 0, gzip from Go's standard library), entrypoint the binary, every time in the config 0. The brain has no image of its own: it runs inside runnerd's sandbox, so runnerd's layer also holds /tacy/brain, and runnerd's image has one more layer below it with gVisor (/tacy/gvisor, from Google's release tarball, downloaded once into the user's cache and checked by SHA-256, then each binary by its pin, with gVisor's Apache-2.0 LICENSE next to them; docs/22 section 4). Same binaries and base, same image digests, on any machine. It checks that compose.yaml matches this tree byte for byte, then prints the compose sha256, each binary's sha256 and each image's digest (--oci DIR also writes the images as OCI layouts). CI runs the same check on the runner and in the pinned Go container and fails on any difference.

The rule the verifier adds (verifier.ComposeImages, the 16th check): the attested compose is one YAML document whose every service has image: <registry>/<path>@sha256:<64 hex> with no tag, no service has build: or extends:, and there's no top-level include:. So the compose hash covers exactly the images that run, and the images' digests cover the binaries.

The compose hash is sha256(compose.yaml). dstack copies the file unchanged into app-compose.json (docker_compose_file), whose own hash is the attested compose-hash. The verifier hashes that attested copy, so the signed value and the measured value are the same bytes.

To rebuild a published release and compare it with its manifest and with what the registry serves:

scripts/reproduce.sh v0.2.0            # in the pinned Go container (cmd/compose's image, by digest); needs docker
scripts/reproduce.sh --native v0.2.0   # with your own Go (must be 1.27.2, e.g. through mise)

It clones the tag, rebuilds, compares with the release's release.json (compose sha256, binary sha256s, image digests), then fetches each image's manifest from ghcr.io anonymously by digest and checks it hashes to that digest and is the rebuilt one. Needs git, curl and jq. .github/workflows/reproduce.yml runs both after every release. Releases before v0.2.0 (tacy-release/v1) built the binaries on the VM and have no images.

Releases and signing

A release is a tag vMAJOR.MINOR.PATCH (no suffixes). .github/workflows/release.yml builds it, pushes the images to ghcr.io/tacyhq/tacy/<name> (tagged with the version for people; the compose uses only the digests) and publishes a GitHub Release with three files:

Signing uses GitHub artifact attestations (actions/attest-build-provenance) on Sigstore's public-good instance: the release job gets a short-lived Fulcio certificate for its GitHub Actions OIDC identity (no long-lived keys), signs one in-toto statement (SLSA provenance v1) whose subjects are compose.yaml, release.json and each image (named ghcr.io/tacyhq/tacy/<name>, with its manifest digest), and the signature is logged in Rekor. The workflow has two jobs: build (read-only token, tests and build, in the pinned Go container and again on the runner, which must agree) and release (checks out nothing, runs no repository code; only it can push packages or get the OIDC token), so test or build code can't push or sign anything. Before it signs, the release job pushes the images and pulls each one back without credentials (manifest, config and every layer, each checked against its digest), because a VM pulls anonymously; if one doesn't pull (a new ghcr package starts private), nothing is signed or published, an org owner sets the package public, and the job is re-run for the same tag.

The verifier (release/) accepts a bundle only if all of these hold:

Sigstore's trusted root is embedded (release/trusted_root.json, from Sigstore's TUF repository); refresh it with RECORD=1 go test ./release -run TestRecordTrustedRoot and review the diff.

Getting the bundle: GET https://api.github.com/repos/tacyhq/tacy/attestations/sha256:<compose sha256> (no auth for a public repo). GitHub often answers with "bundle": null and a short-lived bundle_url to Azure blob storage serving the bundle Snappy-compressed; release.FetchBundles follows it (https to *.blob.core.windows.net only, no redirects, size and time limits). GitHub may also list its own attestation for immutable release assets ("initiator": "github", no Rekor entry), which the verifier refuses; try each bundle (release.VerifyAny). The release asset compose.sigstore.json is the same bundle. By hand:

gh attestation verify compose.yaml --repo tacyhq/tacy \
  --signer-workflow tacyhq/tacy/.github/workflows/release.yml --source-ref refs/tags/v0.2.0

Rollback protection: a relay could serve an older, validly signed release with a known bug, so the verifier refuses releases older than release.MinVersion (release/release.go, currently v0.2.0: the first release with images), raised when a release must stop being used. A caller can raise the minimum further but never lower it, and can pass the newest version it has accepted before (release.Policy.LastSeen; the optional last argument of the browser's verifyRelease and verifyReleaseBundle)