Manage the contexts on a VTA

By the end of this guide, you can see every context a VTA holds, add one under a parent, rename one, and delete a context you no longer need.

A context is the isolation boundary a VTA draws around one application’s keys, secrets, and access rules, and contexts can nest so authority over a branch can be delegated without handing over the whole VTA. For what a context isolates and how the tree shapes authority, see Keys and contexts.

Without this, a VTA only ever accumulates contexts. A decommissioned application leaves its context, keys, and access control list (ACL) entries in place, and the next person to audit the VTA cannot tell which of them are still in use.

Use this guide when:

• You want to see which contexts a VTA already holds before adding another.
• A team or environment needs its own branch of the context tree.
• An application has been decommissioned and its context should go.
• A context’s name or description no longer describes what it holds.

Prerequisites

• A running VTA. See Quickstart.

• pnm installed and connected to the VTA.

  cargo install pnm-cli@0.16.4 --locked --registry crates-io

• Super-admin access to create a top-level context or delete one. Admin of a parent context is enough to create or delete inside that parent’s subtree.

List the contexts

pnm --vta <vta-slug> contexts list

A nested context appears under its full path, so a context created as eng beneath acme is listed as acme/eng. A context-scoped admin sees the contexts it can act in; a super-admin sees all of them.

Inspect one context

pnm --vta <vta-slug> contexts get my-app

This returns the context’s name, description, its parent if it has one, and the DID associated with it if one was set. Use it to confirm a context’s position in the tree before you create anything under it or delete it.

Create a top-level context

pnm --vta <vta-slug> contexts create my-app "My App" \
    --description "Signing keys for the My App service"

Creating at the top level is super-admin only. To hand the context to someone else at the same time, add --admin-did with the DID that should administer it, and --admin-label to say what that entry is:

pnm --vta <vta-slug> contexts create my-app "My App" \
    --admin-did   did:key:z6Mk... \
    --admin-label "my-app owner"

Add --admin-expires 24h when the grant is meant to be temporary, such as a setup credential the holder is expected to replace with a long-lived one. Without it the entry is permanent.

Nest a sub-context under a parent

Pass the parent path, and give the leaf segment as the ID. The stored identifier becomes <parent>/<id>:

pnm --vta <vta-slug> contexts create eng "Engineering" --parent acme

That creates acme/eng. You need admin of acme, or of an ancestor above it, rather than super-admin, which is what makes a branch delegable: whoever owns acme can build inside it without being able to reach anything else on the VTA.

Rename or re-describe a context

Both are metadata, so neither affects the keys or ACL entries inside:

pnm --vta <vta-slug> contexts update my-app \
    --name        "My App (production)" \
    --description "Production signing keys only"

Delete a context

Deleting removes the context and everything below it: its keys, its did:webvh records, its ACL entries, its DID templates, and every sub-context in its subtree.

The VTA refuses a destructive delete unless you ask for it explicitly. A context that holds resources or has sub-contexts fails with a message naming what it found:

pnm --vta <vta-slug> contexts delete my-app

context has 2 sub-context(s) and associated resources; use force=true to delete the whole subtree, or preview first

That refusal is the safety net. Inspect what you are about to lose before overriding it:

pnm --vta <vta-slug> contexts list
pnm --vta <vta-slug> keys list --context my-app
pnm --vta <vta-slug> acl list --context my-app

Once you are satisfied, delete the subtree:

pnm --vta <vta-slug> contexts delete my-app --force

Confirm

Test 1: a new context appears in the listing

pnm --vta <vta-slug> contexts list

The context you created appears. A sub-context appears under its full <parent>/<leaf> path rather than as a bare leaf name.

Test 2: the sub-context records its parent

pnm --vta <vta-slug> contexts get acme/eng

The parent field names acme, which confirms the context was nested rather than created at the top level with a slash in its name.

Test 3: a context with resources refuses a plain delete

pnm --vta <vta-slug> contexts delete my-app

A context holding keys, ACL entries, or sub-contexts is refused, and the message names what it found. Getting this refusal is the expected result, not a failure: it means the safety check is working before you reach for --force.

Troubleshooting

Next steps