Configuration reference

Workflow manifest

The workflow manifest accepts YAML (.octonode.yaml or .octonode) and JSON (.octonode.json). Use --config to select a file explicitly.

Direct CLI commands read and write the manifest. In Studio/server mode, saved environments, node configuration, and workflow topology live in the project store; the manifest is an import/export artifact. Use Studio's save and export flows to retain changes made there.

octonode scan refreshes code-owned signatures. It preserves configuration-owned runtime settings and topology, and does not rewrite source files.

octonode scan --config .octonode.yaml
octonode scan --check --config .octonode.yaml
octonode validate --config .octonode.yaml

scan --check reports drift without writing. validate checks schema and structure. Use octonode schema to print the workflow JSON Schema for editor tooling.

Runtime settings

Set these under an existing node's runtime block:

runtime:
  timeout_ms: 5000
  retries: 2
  retry_backoff_ms: 250

timeout_ms is the deadline for one attempt. retries counts attempts after the initial invocation. retry_backoff_ms is the base retry delay. The async: true option waits for running nodes and executes that node alone within the workflow run.

Environments

environments:
  dev:
    vars:
      LOG_LEVEL: debug
  prod:
    inherits: dev
    vars:
      LOG_LEVEL: warn

Select an environment with octonode run total --env dev --config .octonode.yaml. Keep actual service credentials in the workspace's variables or appropriate runtime secret configuration, outside committed examples and public documents.

Human-owned settings

octonode.yml, octonode.yaml, or octonode.json (without the leading dot) is a separate settings document. It supports appearance, overrides, layers, views, and defaultView. A section can be inline or reference a local YAML/JSON file using $file; referenced files must remain inside the settings directory.

apiVersion: octonode.dev/settings/v1
appearance:
  nodeDefaults:
    style: { density: comfortable, radius: soft }

Validate and inspect settings with:

octonode settings validate --file octonode.yml
octonode settings show --file octonode.yml

Both commands are read-only. show prints resolved JSON. Use --file for settings and --config for the workflow manifest. Include referenced section files in Git alongside the root settings file.

The settings contract, loader, and CLI are available. Studio appearance resolution, layer filtering, and settings editing are not yet connected to this document; declaring a view does not currently hide Studio content. YAML and JSON are supported; TOML is not supported.