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.23.1 --locked --registry crates-io

• Super-admin access to create a top-level context, or to rename or re-describe any context. Admin of a context, or of one of its ancestors, is enough to delete it or to create sub-contexts inside it.

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 full ID, which includes its parent path, its name, its DID ((not set) if none), its description, its base derivation path, and when it was created and last updated. 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 --id my-app --name "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 --id my-app --name "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 --id eng --name "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. Updating a context is super-admin only:

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

Delete a context

Deleting removes the context, every sub-context in its subtree, and their keys, did:webvh DIDs, DID templates, and the ACL entries scoped only to that subtree. Vault entries stored against those contexts stay, so archive or delete them first. An ACL entry that also names other contexts stays, and only loses this one. Each did:webvh DID is also removed from its hosting server, the credentials the VTA issued naming it are revoked, and its sessions end.

The whole delete is refused before anything changes if a DID in the subtree is the VTA’s own, if another context acts as it, or if its hosting server is no longer registered on this VTA. A VTA running without a DID resolver also refuses to delete a context holding did:webvh DIDs, since it has no way to remove them from their hosting server. If a registered host does not confirm removal, the delete still completes, and pnm prints a warning naming the DIDs whose published logs may still resolve.

pnm shows what the delete will remove and asks before doing anything:

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

Deleting context 'my-app' will remove the following resources:

  Sub-contexts (2):
    - my-app/a
    - my-app/b
  ACL entries removed (1):
    - did:key:z6Mk...

Proceed with deletion? [y/N]

Answering anything but y or yes prints Aborted. and changes nothing. A context holding nothing is deleted without a prompt, and a successful delete prints Context deleted: my-app.

That preview is the safety net. Inspect what you are about to lose before you confirm:

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

To skip the prompt, for example in a script, pass --yes:

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

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 ID: line reads acme/eng, which confirms the context was nested under acme.

Test 3: a context with resources asks before deleting

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

The preview lists the keys, ACL entries, DIDs, DID templates, and sub-contexts the delete would remove, followed by Proceed with deletion? [y/N]. Answer n: pnm prints Aborted. and nothing changes, which confirms the safety check runs before anything is deleted.

Troubleshooting

Next steps