Skip to content

Project file

Keys of ocx.toml, from the published project schema. An unknown key is a parse error (exit 78), so config.toml-only keys such as [shell], [update] and toolchain_dir are refused here.

A [telemetry] table is refused too, with exit 78 (telemetry_section_in_project). Telemetry is configured in config.toml.

activate

Top-level activate mode: how a project’s rendered toolchain reaches a shell — per-prompt environment composition (env, the default), a PATH entry for <home>/toolchain/active/bin (bin), or neither (none). Absent falls through to OCX_TOOLCHAIN_ACTIVATE, then to env.

An unrecognized value is a parse error (exit 78). An edit never invalidates ocx.lock.

  • Type: string
  • Values:
    • env: Compose the toolchain environment on every prompt.
    • bin: Put <home>/toolchain/active/bin on PATH and compose nothing else, so a tool is resolved by its launcher at invocation time.
    • none: Neither.
  • Default: "env"
  • See: Toolchain activation

env.<name>

Environment variables for the default group; [env] in TOML.

A key is a POSIX name and must not start with OCX_ or __OCX_; either is a parse error (exit 78).

Stands to [group.<name>.env] as [tools] does to [group.<name>.tools]. It does not change which packages resolve, so an edit never forces a re-lock.

env.<name>.separator

For list only: the string this contribution is joined to the variable’s existing value with. Omit it to inherit whatever separator another contributor to the same key declared, or a single space if none did.

It must be non-empty and free of =, newline and carriage return. A separator on a non-list entry, an unusable one, or a list value that starts or ends with it is a parse error (exit 78).

env.<name>.type

constant replaces the variable’s value; path prepends to it; list appends to it.

  • Type: string
  • Values:
    • path: Prepended to any existing value of the variable.
    • constant: Replaces any existing value of the variable.
    • list: Appended to any existing value of the variable, joined by its separator.
  • See: Environments

env.<name>.value

The literal value. For path, a relative value resolves against the project root; an absolute one passes through.

A path value containing the platform path separator is a data error (exit 65): declare one directory per entry.

group.<name>

Named additive groups; [group.<name>] in TOML. A name matches ^[A-Za-z0-9][A-Za-z0-9._-]*$ and is at most 64 bytes.

default and all are reserved, ignoring case: declaring [group.default] or [group.all] is a parse error.

Under [group.<name>] only tools, env and lazy-mode are accepted. Anything else, including a binding written directly there, is a parse error (exit 78).

group.<name>.env.<name>

Environment variables applied when this group is selected.

A key is a POSIX name and must not start with OCX_ or __OCX_; either is a parse error (exit 78).

group.<name>.env.<name>.separator

For list only: the string this contribution is joined to the variable’s existing value with. Omit it to inherit whatever separator another contributor to the same key declared, or a single space if none did.

It must be non-empty and free of =, newline and carriage return. A separator on a non-list entry, an unusable one, or a list value that starts or ends with it is a parse error (exit 78).

group.<name>.env.<name>.type

constant replaces the variable’s value; path prepends to it; list appends to it.

  • Type: string
  • Values:
    • path: Prepended to any existing value of the variable.
    • constant: Replaces any existing value of the variable.
    • list: Appended to any existing value of the variable, joined by its separator.
  • See: Project groups

group.<name>.env.<name>.value

The literal value. For path, a relative value resolves against the project root; an absolute one passes through.

A path value containing the platform path separator is a data error (exit 65): declare one directory per entry.

group.<name>.lazy-mode

Group-level lazy-mode override: outranks the top-level setting and is outranked by [package."<id>"] and the CLI flag. Absent inherits from the top-level setting; it does not mean never.

An edit never invalidates ocx.lock.

  • Type: string
  • Values:
    • never: Compose eagerly: content materializes before the tool reaches PATH.
    • always: Compose a shim: content materializes on the first invocation of one of the tool’s declared names.
  • See: Project groups

group.<name>.tools.<name>

Tool bindings for this group. A value is a fully-qualified package reference, validated exactly as [tools] is, or { from = "default" } to reuse the [tools] entry of the same name.

A binding name matches ^[A-Za-z0-9][A-Za-z0-9._-]*$ and is at most 64 bytes.

group.<name>.tools.<name>.from

lazy-mode

Top-level lazy-mode, the least specific setting: outranked by [group.<g>], [package."<id>"] and the CLI flag. Absent falls through to OCX_LAZY_MODE; it does not mean never.

An edit never invalidates ocx.lock.

  • Type: string
  • Values:
    • never: Compose eagerly: content materializes before the tool reaches PATH.
    • always: Compose a shim: content materializes on the first invocation of one of the tool’s declared names.
  • See: Deferred packages

lazy-report

Top-level lazy-report. Absent falls through to OCX_LAZY_REPORT, then to silent.

An edit never invalidates ocx.lock.

package.<name>

Per-package resolve-time settings; [package."<id>"] in TOML, keyed by the canonical author string registry/repo[:tag].

Resolve-time policy, not a tool binding: a no-patches edit never invalidates ocx.lock.

package.<name>.lazy-mode

Package-level lazy-mode override, the most specific setting: only the CLI flag outranks it. Absent inherits from the group and top-level settings; it does not mean never.

An edit never invalidates ocx.lock.

  • Type: string
  • Values:
    • never: Compose eagerly: content materializes before the tool reaches PATH.
    • always: Compose a shim: content materializes on the first invocation of one of the tool’s declared names.
  • See: Patches

package.<name>.lazy-report

Package-level lazy-report override. Absent inherits from the top-level setting.

An edit never invalidates ocx.lock.

  • Type: string
  • Values:
    • silent: No progress channel is opened for a first-invocation materialization.
    • progress: Render progress for a first-invocation materialization, best-effort.
  • See: Patches

package.<name>.no-patches

Decline the site-tier companion overlay for this base.

A system-required patch still applies (enforcement beats opt-out).

  • Type: boolean
  • Default: false
  • See: Patches

pinned

Top-level pinned: whether composed paths follow the rendered links/<group>/<entry> links (false, the default) or pin to digest roots (true). Absent falls through to OCX_TOOLCHAIN_PINNED.

An edit never invalidates ocx.lock.

tools.<name>

Tools in the reserved default group (the top-level [tools] table in ocx.toml). Values are fully-qualified package references.

A binding name matches ^[A-Za-z0-9][A-Za-z0-9._-]*$ and is at most 64 bytes.

trust

Identity-pinned verification policies; [[trust.policy]] in TOML.

Consumed by ocx package verify. A project policy applies only to targets that no config.toml policy matches; it never pools with them.

Resolve-time policy, not a tool binding: a policy edit never invalidates ocx.lock.

trust.policy

The declared policies. Empty when [trust] is present but lists none.

trust.policy.builder

Expected SLSA provenance builder identity, matched against the provenance predicate during attestation verify.

Ignored in signature mode, without an error.

trust.policy.scope

Which packages this policy applies to: one prefix pattern, or an include/exclude set of them.

A pattern matches on /-separated path-segment boundaries, and an absent scope is a catch-all.

scope = "ghcr.io/acme/*"
scope = { include = ["ghcr.io/acme/*"], exclude = ["ghcr.io/acme/experimental/*"] }

trust.policy.scope.exclude

Patterns carved back out. Beats include wherever both match.

trust.policy.scope.include

Patterns the policy covers. Empty is a catch-all.

trust.policy.signers

The signers this policy accepts: an ANY-of set, each entry tagged kind = "keyless" or kind = "key".

signers = [
{ kind = "keyless", identity = "release@acme.example", oidc_issuer = "https://accounts.google.com" },
{ kind = "key", key = "etc/acme-release.pub" },
]

Every added entry widens what verifies, and an empty set is a configuration error, not a catch-all.

trust.policy.signers.claims.<name>

Fulcio certificate claims that must all match, keyed by claim name or raw OID.

Every listed claim must match, and values compare as exact strings. A key is a known claim name (build_signer_uri, source_repository_identifier, source_repository_owner_identifier, build_trigger, build_signer_digest) or a raw OID under 1.3.6.1.4.1.57264.1.; an unknown name matches nobody.

Alone or beside identity / identity_regexp.

trust.policy.signers.identity

Exact expected certificate SAN (byte-equal).

Mutually exclusive with identity_regexp.

trust.policy.signers.identity_regexp

Regex the certificate SAN must match in full (anchored \A…\z).

Mutually exclusive with identity.

trust.policy.signers.key

A key reference ([scheme://]<rest>), the same spelling --key takes on the command line.

Mutually exclusive with key_pem, and refused in a managed-config payload.

trust.policy.signers.key_pem

Verbatim SPKI PEM.

Mutually exclusive with key.

trust.policy.signers.kind

Selects the variant of this entry; the other fields depend on the value.

  • Type: string
  • Values:
    • keyless: { kind = "keyless", identity | identity_regexp, oidc_issuer }.
    • key: { kind = "key", key | key_pem }.
    • unknown: A kind this build does not know — an entry written by a newer OCX.
  • See: Trust signers with a policy

trust.policy.signers.oidc_issuer

Exact expected OIDC issuer URL (byte-equal).

trust.sigstore

Sigstore trust material for a self-hosted stack ([trust.sigstore]).

Read from the operator config.toml tiers only. The project ocx.toml also accepts a [trust] table, but its sigstore sub-table is never consulted.

trust.sigstore.fulcio_url

Default Fulcio base URL for ocx package sign when --fulcio-url is omitted.

trust.sigstore.rekor_upload

Fleet-wide default for uploading a key-mode signature to the transparency log, when neither --rekor-upload nor --no-rekor-upload is given.

Absent means off; keyless signing always uploads and ignores this field.

trust.sigstore.rekor_url

Default Rekor base URL for ocx package sign / verify when --rekor-url is omitted.

trust.sigstore.trusted_root

Path to a Sigstore trusted-root JSON, or a directory holding trusted_root.json.

A relative path resolves against the directory of the config.toml that declared it. It is rewritten to absolute at load time, so the same value names the same file whatever the working directory.

Mutually exclusive with trusted_root_json.

trust.sigstore.trusted_root_json

The trusted-root document inlined verbatim.

This is the form a fleet receives: ocx config push reads a path-form trusted_root at publish time and inlines it here. Mutually exclusive with trusted_root.