Files
README.md

Daevix #

Execution-time control plane for autonomous AI agents.

Daevix is split into a central controlplane (identity, policy, audit, operator API) and one or more enclaves (the sovereign data plane). Any operation on sovereign data happens inside an enclave and never transits the controlplane. See docs/architecture.md.

An enclave serves a set of orgs, not just its owner. The owning org can mark an enclave shared (dvx enclaves share/unshare); registered tenant orgs then place their agents on it and author their own secrets under their own org coordinate (dvx enclaves tenants add/list/remove). Unregistered orgs get no access. See docs/runbooks/tenant-org-migration.md.

Enclave drivers #

The broker's platform touchpoints (agent placement, registry bookkeeping, egress mediation plumbing) are pluggable behind a driver seam (internal/enclave/cpbroker/driver). The Kubernetes driver is the first implementation; a local micro-VM driver (internal/enclave/vmdriver) is the second, running agents as cloud-hypervisor VMs on the host with satellites as host processes. An enclave runs exactly one driver, and every driver must pass the shared conformance suite (internal/enclave/cpbroker/driver/drivertest). Isolation is a per-enclave isolation class (plain < vm < node-cvm < per-agent-tee) that gates provision fail-closed: an exact-class match or a refusal, never a silent downgrade. SVIDs carry the class as a distinct claim beside the attested assurance tier.

Tool-call inspection and approvals #

When an llm.inspection policy is active, llmproxy buffers LLM responses and inspects them before delivery. A detector finds tool calls in the response, and rule inspectors produce a verdict (allow, reject, redact, or escalate). An escalated tool call is held behind operator approval through the enclave broker; operators decide with dvx approvals (list/get/approve/deny/stream). If no approval arrives before the configured timeout, llmproxy returns a fail-closed error to the agent.

Per-destination token presentation #

The gateway can attach a short-lived bearer token to an agent's egress itself: the agent holds no credential and never observes a token. Operators author a destination presentation table (platform and org scopes, via the operator policy surface) that binds one relying party to one exact host:port destination and one of two modes:

  • present-agent-token — the gateway mints a dvx agent token for the entry's audience (through its SVID -> broker -> CP path) and presents it to the matched destination only.
  • present-exchanged-token — the gateway mints a dvx subject token for the entry's exchange audience and performs an RFC 8693 token exchange against the entry's pinned HTTPS exchange_url, then presents the returned platform bearer to the matched destination only. The subject token carries no sovereign request content; the returned bearer lives only in the gateway's cache (at most 60s and no longer than the token's own expiry).

Fail-closed rules: destinations matching no entry present nothing; the built-in controlplane entry (dvx-operator-api, the operator-API surface) is immutable and always present; an invalid, ambiguous, or stale authored table contributes zero non-CP entries; group/agent scopes cannot author the table.

Minting itself is allowlisted per enclave: the controlplane refuses (with an agenttoken.mint deny audit row, reason audience not allowlisted) any mint for an audience not on that enclave's registered allowlist. Seeded with dvx-operator-api at registration; operators replace it with:

dvx enclaves set-audiences --name <enclave> \
  --aud dvx-operator-api --aud <other-audience> ...

Authoring the presentation table (the value is the whole table for the scope):

cat > /tmp/presentation.json <<'EOF'
{"entries":[
  {"rp_id":"example","host":"api.example.internal","port":8443,
   "mode":"present-agent-token","audience":"example-api"},
  {"rp_id":"velverk","host":"rp.example.internal","port":443,
   "mode":"present-exchanged-token",
   "exchange_url":"https://rp.example.internal:443/token",
   "exchange_audience":"velverk-api"}
]}
EOF
dvx policy presentation --file /tmp/presentation.json              # platform scope
dvx policy presentation --org <org> --file /tmp/presentation.json  # org scope (adds/replaces per rp_id)

An entry's port is the POST-NAT/container destination port the gateway observes, not the agent-dialed Service port. In the dev cluster, agents dial the token-exchange RP's Service on 443, Cilium NATs the connection to the container's 8480, and the matching entry carries port: 8480 (see deploy/enclave/tokenexchange-rp.yaml).

A local RFC 8693 relying-party fixture (dvx tokenexchange-rp, test-only: in-memory grants, no bearer ever logged) stands in for a platform token endpoint in the dev cluster; see deploy/enclave/tokenexchange-rp.yaml for the Deployment/Service and the serving-cert recipe (signed by the echo CA the gateway already anchors). With --deny-exchange it refuses every exchange, so the gateway's fail-closed exchange-failure path can be exercised live.

Documentation #

The product docs live at docs.daevix.com, built from site/docs (Hugo). To work on them locally:

make site-docs-dev    # serve on :1313 (regenerates CLI/OpenAPI/audit references first)
make site-docs-build  # build into site/docs/public

Layout #

cmd/dvx/                 single binary: `dvx serve controlplane` / `dvx serve imds` (+ broker/gateway/llmproxy/relay)
                         plus test fixtures (`echo-verify`, `tokenexchange-rp`)
internal/controlplane/   central management plane (never handles sovereign data)
internal/enclave/        sovereign data plane (broker + imds/gateway/llmproxy satellites;
                         llmproxy `--translate` enables optional cross-format translation;
                         llmproxy routes known inference hosts to governed providers
                         (opencode.ai as opencode-go / opencode-payg, by path) and injects
                         the provider credential per route, fail-closed;
                         llmproxy response inspection (`llm.inspection` policy) buffers
                         and inspects responses, escalating flagged tool calls to
                         operator approval)
internal/enclave/imdsnode/ IMDS node daemon (`dvx serve imds`)
internal/enclave/imds/   IMDS-like metadata service agents mount (unix socket)
internal/enclave/cpbroker/driver/  broker placement-driver seam + drivertest conformance suite
internal/enclave/vmdriver/  local micro-VM driver (cloud-hypervisor agents on the host)
internal/vmnet/          root-helper-backed bridge/tap/nft datapath for VM agents
internal/isoclass/       isolation class vocabulary (plain < vm < node-cvm < per-agent-tee)
cmd/dvx-init/            static in-VM init (localhost -> vsock bridge to the IMDS)
internal/audit/          first-class audit log stream (separate from app logs)
internal/applog/         application/operational log stream
internal/inspection/     plane-neutral content-inspection pipeline (detectors find,
                         inspectors judge: allow/reject/redact/escalate)
internal/server/         TLS-only HTTP server + graceful shutdown
internal/problem/        RFC 9457 Problem Details
internal/translation/    LLM wire-format translation (Anthropic Messages, OpenAI
                         chat/completions, OpenAI Responses) in all 6 directed
                         pairs; plane-neutral; differential test corpus in
                         internal/translation/testdata/llmcorpus/; benchmarked
                         against litelm 0.5.3 (see internal/translation/
                         BENCHMARKING.md for results and reproduction)
internal/config/         per-component configuration
internal/database/       PostgreSQL connect; sqlc-generated code + goose migrations
docs/architecture.md     boundaries and invariants
docs/reproducible-builds.md  bit-for-bit builds + how CI verifies `go install`

Quickstart #

mise install          # provision Go 1.27.1 + tooling (see mise.toml)
make dev-certs        # local TLS certs into certs/
make build            # -> bin/dvx

make run-controlplane # TLS API on :8443, /healthz
make run-imds         # TLS API on :8444 + IMDS on /tmp/dvx-imds.sock

curl -sk https://127.0.0.1:8443/healthz
curl -s --unix-socket /tmp/dvx-imds.sock http://imds/v1/identity

Both application logs (stream=app) and audit records (stream=audit) go to stdout, differentiated by the top-level stream key. Split them with one field match, e.g. dvx serve imds | jq 'select(.stream=="audit")'.

Development #

make test       # unit tests
make lint       # go vet + golangci-lint (enforces the controlplane/enclave boundary)
make generate   # regenerate sqlc code
make translation-corpus  # regenerate the translation differential test corpus (test-only Python venv)
make opencode-e2e    # full OpenCode cluster proof on daevix-dev (load image, roll, probe, audit assertions)

# Translation acceptance benchmarks (Go vs litelm 0.5.3 reference, run serially):
mise exec -- go test -run '^$' -bench . -benchmem -count 3 ./internal/translation/
/tmp/translation-corpus-venv/bin/python internal/translation/corpus/bench_litelm.py

Live provider e2e tests for translation (make translation-e2e-live) are guarded behind a build tag and a DVX_E2E_OPENCODE_KEY_FILE env var — they call a real provider and are not part of normal verification.


### Local VM enclave (no Kubernetes)

`make vm-enclave-up` brings up a complete local enclave on the host: podman
postgres + clickhouse datastores, the broker/imds/gateway/llmproxy satellites
as host processes, and agents as KVM micro-VMs via cloud-hypervisor. The
enclave registers against the running dev-cluster controlplane through a
`kubectl port-forward` channel. Both targets are idempotent; state lives under
`~/.dvx/vm-enclave`.

```bash
make vm-enclave-up     # bring up (podman stores + host-process satellites + micro-VM agents)
make vm-enclave-down   # tear down (no processes/ports left; state kept)

Prerequisites: /dev/kvm, cloud-hypervisor and the guest kernel under ~/dvx-vm-assets (bin/cloud-hypervisor, share/kata-vmlinuz), a running daevix-dev cluster with a fetched kubeconfig (see CLAUDE.md) plus the dev Zitadel port-forward on :8080, and passwordless sudo — dvx net-helper (internal/vmnet) is the single privileged entry point, invoked as sudo -n dvx net-helper ... by the unprivileged driver to install the bridge/tap/nft egress-mediation datapath.

Issue tracking (bd) on PATH #

Work is tracked with beads (bd), provisioned by mise install per mise.toml. Two non-interactive contexts invoke bd directly and must resolve it without mise exec or interactive shell activation:

  • the Claude SessionStart hook (bd prime), and
  • the git pre-commit / pre-push hooks (core.hooksPath = .beads/hooks), which run bd hooks run … and — via a local augmentation in pre-push — bd dolt push to sync issue data to the remote's refs/dolt/data.

mise's shims directory is only added to PATH by interactive mise activate (~/.bashrc), so non-interactive callers need another route. The reproducible setup on a fresh machine:

mkdir -p ~/.local/bin
ln -sf ~/.local/share/mise/shims/bd ~/.local/bin/bd   # version-independent shim path

Ensure ~/.local/bin is on PATH for the contexts that run the hooks:

  • login shells — ~/.profile already prepends ~/.local/bin;
  • the Claude systemd user service — pin it explicitly, e.g. Environment=PATH=%h/.local/bin:/usr/local/bin:/usr/bin:/bin, so the agent and every hook it spawns resolve bd regardless of dotfiles.

The symlink targets the shim, not a versioned binary, so it survives mise reshim and bd upgrades. Verify with bash -c 'command -v bd' (a non-interactive shell). Note: if bd hooks install ever regenerates .beads/hooks/pre-push, re-add the DVX BEADS SYNC block that runs bd dolt push — it is a local augmentation, not managed by beads.

Licensed under AGPLv3. See CONTRIBUTING.md for the CLA.