- integrations
- Dev Containers
- Concepts
- What the feature trusts
What the feature trusts
This page explains which sources the ocx Dev Container Feature trusts, what the defaults allow and how to tighten them. It matters when the repositories you open are not all yours, or when a build must be reproducible.
What activates without a prompt
A new interactive shell puts a project’s tools on PATH only when the project directory lies under one of the consentPaths entries.
Activation also applies the [env] table of the project’s ocx.toml, so the project file decides what a shell gets.
The default entry is /workspaces/*, so every project under the workspace mount activates without a prompt.
The dev container already runs the workspace repository’s own lifecycle commands, so this grants that repository nothing new.
It also covers any other repository you clone below /workspaces.
Its ocx.toml then shapes every new shell that starts inside it.
Outside the listed paths nothing activates, and you run tools with ocx exec -- <command> or open a shell with ocx shell.
Tighten activation
Three settings narrow the grant, from a smaller list to none:
- A narrower
consentPathslist names only the projects you trust. - An empty
consentPathsactivates nothing. shellActivation: falsewrites no activation code at all.
A plain path matches that directory only, and dir/* matches dir and everything below it.
Any other use of * matches nothing.
This example trusts one project directory and nothing else under /workspaces.
{ "image": "mcr.microsoft.com/devcontainers/base:ubuntu", "features": { "ghcr.io/ocx-sh/devcontainer-features/ocx:1": { "consentPaths": "/workspaces/app" } }}A tool that stays off PATH for this reason is the subject of Error: the tool is not on PATH outside consentPaths.
What the install trusts
The default version: "pinned" verifies the archive against a checksum bundled in the feature.
The trust anchor is the feature package you pulled, so the next section says how to pin it.
The bundled manifest also carries its own digest, but that digest ships in the same package.
It detects corruption and cannot detect a swapped package.
Two options move the trust anchor to a web server:
version: "latest"reads the live manifest fromhttps://setup.ocx.sh/dist.json.- A plain
distUrlreads the manifest from the URL you give.
Both trust the HTTPS endpoint that serves the manifest, because the archive checksum comes from that manifest.
A mirrorUrl changes only where the archive comes from, and the checksum still comes from the manifest.
How the install works lists the checks the build runs on every download.
Pin the supply chain
Where the supply chain matters, remove every moving part:
- Pin the feature by an exact version such as
ocx:1.0.0, or by digest withocx@sha256:<digest>. - Name a
distUrlmanifest after its own SHA-256 digest, as Use a version outside the baked list shows. - Pin
managedConfigto a digest with@sha256:<digest>, as Apply organisation-managed configuration shows.
Related pages
- Options describes every setting named here.
- How the install works lists what the build does and never does.
- Files, environment and exit codes shows the generated shell profile.