DESK BACKEND
EKKA with NVIDIA OpenShell¶
NVIDIA OpenShell is the desk backend EKKA supports today. It isolates each desk and holds its keys. EKKA decides who and what may use a desk, and signs a record of every job.
New to desks? Start with Agent desks, which explains what a desk is and how agents work on one. This page covers what is specific to NVIDIA OpenShell.
What NVIDIA OpenShell does, and what EKKA adds¶
| NVIDIA OpenShell | EKKA |
|---|---|
| Runs each desk as an isolated workspace | Decides which agent may work on which desk, through a Grant |
| Holds each desk to its policy: which programs may reach which hosts, and which folders may be written | Pins each desk's identity and policy, and refuses work on a desk that changed until a person approves it |
| Keeps the company's keys in its gateway and adds them to a request only for that key's own hosts | Changes a desk only through a governed plan run, which the desk backend's adapter verifies before it acts |
| Checks every job step against its Grant before it starts, and signs a record after it ends |
Set up OpenShell with EKKA¶
For OpenShell desk setup, contact EKKA. The commands below apply to a configured desk backend.
Requirements¶
- Linux x86_64 with Linux 6.2 or newer, and Docker.
- NVIDIA OpenShell's isolation uses Landlock, a Linux feature that limits which files a program can touch. It is available on Linux 6.2 and newer.
- An EKKA release that carries desk changes through EKKA. The install and the Enclave upgrade together: the install refuses an older Enclave and names the release to upgrade to.
How is the adapter checked before it runs?¶
The adapter is the program that carries an approved desk change to NVIDIA
OpenShell. It is open source, built from
github.com/ekka-labs/ekka-backend,
and published as the public image ghcr.io/ekka-labs/ekka-backend. It takes a
change only from the Enclave, and only with an authorization Govern signed.
The install pulls the adapter by its digest, with no registry login, and checks its signature before anything runs it. The image must be signed by that repository's release workflow on a version tag. Any other image does not run.
Anyone can make the same check:
cosign verify \
--certificate-identity-regexp '^https://github\.com/ekka-labs/ekka-backend/\.github/workflows/release\.yml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+$' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
ghcr.io/ekka-labs/ekka-backend:v0.1.2
Verification for ghcr.io/ekka-labs/ekka-backend:v0.1.2 --
The following checks were performed on each of these signatures:
- The cosign claims were validated
- Existence of the claims in the transparency log was verified offline
- The code-signing certificate was verified using trusted certificate authority certificates
Keys stay in the gateway¶
Your keys live in NVIDIA OpenShell's gateway, never in a desk. The agent sees a placeholder. The gateway puts the real key into a request only when that request goes to one of the key's own hosts.
A key is set on the desk backend's machine, from a pipe, one key per provider:
up.sh refuses a key typed at a terminal or passed as an argument, so the key
never appears on the screen or in the command line.
A gateway that trusts client certificates is refused¶
NVIDIA OpenShell can be set up so that a caller holding a client certificate,
under a certificate authority the gateway trusts, can read real key values out
of the gateway. That would let keys leave the vault without EKKA knowing. So the
Enclave checks the gateway when it starts and about once a minute after. While
the gateway asks for client certificates, every desk step is refused as
DESK_GATEWAY_TRUSTS_CLIENT_CERTS, naming the setting to remove. Desk work
resumes at the next check after it is removed.
Every ekka desk command is in the CLI reference.