- docs
- Look things up
- Look things up
- Reference
- Project file
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:
- 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.
- Type:
string or table - See: Environments
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).
- Type:
string - See: Environments
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.
- Type:
string - See: Environments
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).
- Type:
table - See: Project groups
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).
- Type:
string or table - See: Project groups
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).
- Type:
string - See: Project groups
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.
- Type:
string - See: Project groups
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 reachesPATH.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.
- Type:
string or table - See: Project groups
group.<name>.tools.<name>.from
- Type:
enum - Values:
default - See: Project groups
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 reachesPATH.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.
- 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: Deferred packages
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.
- Type:
table - See: Patches
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 reachesPATH.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.
- Type:
boolean - Default:
false - See: Toolchain activation
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.
- Type:
string - See: ocx.toml in depth
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.
- Type:
table - See: Trust signers with a policy
trust.policy
The declared policies. Empty when [trust] is present but lists none.
- Type:
array - Default:
[] - See: Trust signers with a policy
trust.policy.builder
Expected SLSA provenance builder identity, matched against the provenance predicate during attestation verify.
Ignored in signature mode, without an error.
- Type:
string - Default: unset
- See: Trust signers with a policy
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/*"] }- Type:
string or table - Default: unset
- See: Trust signers with a policy
trust.policy.scope.exclude
Patterns carved back out. Beats include wherever both match.
- Type:
array - See: Trust signers with a policy
trust.policy.scope.include
Patterns the policy covers. Empty is a catch-all.
- Type:
array - See: Trust signers with a policy
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.
- Type:
array - Default:
[] - See: Trust signers with a policy
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.
- Type:
string - See: Trust signers with a policy
trust.policy.signers.identity
Exact expected certificate SAN (byte-equal).
Mutually exclusive with identity_regexp.
- Type:
string - Default: unset
- See: Trust signers with a policy
trust.policy.signers.identity_regexp
Regex the certificate SAN must match in full (anchored \A…\z).
Mutually exclusive with identity.
- Type:
string - Default: unset
- See: Trust signers with a policy
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.
- Type:
string - Default: unset
- See: Trust signers with a policy
trust.policy.signers.key_pem
Verbatim SPKI PEM.
Mutually exclusive with key.
- Type:
string - Default: unset
- See: Trust signers with a policy
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: Akindthis 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).
- Type:
string - Default: unset
- See: Trust signers with a policy
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.
- Type:
table - Default: unset
- See: Trust signers with a policy
trust.sigstore.fulcio_url
Default Fulcio base URL for ocx package sign when --fulcio-url is
omitted.
- Type:
string - Default: unset
- See: Trust signers with a policy
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.
- Type:
boolean - Default: unset
- See: Trust signers with a policy
trust.sigstore.rekor_url
Default Rekor base URL for ocx package sign / verify when
--rekor-url is omitted.
- Type:
string - Default: unset
- See: Trust signers with a policy
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.
- Type:
string - Default: unset
- See: Trust signers with a policy
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.
- Type:
string - Default: unset
- See: Trust signers with a policy