Workspace Layout - ChainBot

Root Layout

When you run chainbot init, it creates this canonical layout:

<root>/
|- chainbot.toml
|- workflows/
|  `- <workflow_id>/
|     |- config.toml
|     |- scripts/
|     `- assets/
|- triggers/
|  `- <trigger_id>/
|     |- config.toml
|     |- scripts/
|     `- assets/
|- plugins/
|  `- <plugin_id>/
|     |- config.toml
|     |- bin/
|     `- assets/
|- secrets/
`- state/

The root directory defaults to ~/.chainbot. Set CHAINBOT_CONFIG_DIR to use a different path.

Loading Order

Manifests are loaded in this fixed order:

chainbot.toml (root config)
workflows/<workflow_id>/config.toml
triggers/<trigger_id>/config.toml
plugins/<plugin_id>/config.toml

Root Config: `chainbot.toml`

The root config defines paths, runtime defaults, secret references, and storage mode.

manifest_version = "2.0.0"
chainbot_version = "2.2.0"
profile = "basic"

[paths]
workflows_dir = "workflows"
triggers_dir = "triggers"
plugins_dir = "plugins"
secrets_dir = "secrets"
state_dir = "state"

[runtime_defaults]
timezone = "UTC"

[storage]
mode = "local"

[storage.local]
database_path = "state/runtime.sqlite3"

All path overrides must stay within <root> and use root-relative paths.

Workflow Packages

Canonical entrypoint: workflows/<workflow_id>/config.toml The directory name must match workflow.id exactly. Workflows define a DAG of nodes, runtime defaults, and optional subflow calls.

[workflow]
manifest_version = "2.0.0"
id = "wf-alpha"
name = "alpha"
description = "Normalize a quote payload"

[runtime.defaults]
symbol = "BTCUSDT"

[[nodes]]
manifest_version = "2.0.0"
id = "normalize"
kind = "plugin"
plugin = "quote-plugin"
operation = "normalize"
depends_on = []

Trigger Packages

Canonical entrypoint: triggers/<trigger_id>/config.toml The directory name must match trigger_id exactly. Triggers bind an event source to a workflow and do not contain DAG or node definitions. Builtin trigger example:

manifest_version = "2.0.0"
trigger_id = "tr-market"
kind = "builtin"
source = "market_tick"
workflow_id = "wf-alpha"
enabled = true

[params]
symbol = "BTCUSDT"

[input_mapping]
symbol = "payload.symbol"
price = "payload.price"

Builtin sources include manual, market_tick, and cron.

Plugin Packages

Canonical entrypoint: plugins/<plugin_id>/config.toml The directory name must match plugin_id exactly. Plugins declare an entrypoint, capabilities, and an executable path.

manifest_version = "2.0.0"
plugin_id = "quote-plugin"
kind = "external_node"
entrypoint = "node.exec.v1"
capabilities = ["normalize"]
executable = "bin/quote-plugin.sh"

Package Constraints

All relative paths within a package resolve from the package root.
Workflow IDs, trigger IDs, and plugin IDs must be globally unique within a workspace.
Triggers must reference an existing workflow_id.
A workflow can run without any triggers via chainbot run.
The legacy plugins/manifests/ shared layout is not created by chainbot init and is not part of the stable bootstrap contract.

​Root Layout

​Loading Order

​Root Config: chainbot.toml

​Workflow Packages

​Trigger Packages

​Plugin Packages

​Package Constraints