Komodo Resource Flows¶

Accurate per-resource workflows based on official Komodo docs (crawled from komo.do, 2026-05-22).

Source: crawl4ai crawl of 20 pages from komo.do/docs

Resource Types Overview¶

Resource	Purpose	TOML Key	Managed via Sync
Server	Connected server running Periphery agent	`[[server]]`	Yes
Swarm	Docker Swarm cluster	`[[swarm]]`	Yes
Deployment	Single container (`docker run`)	`[[deployment]]`	Yes
Stack	Docker Compose project (`docker compose up`)	`[[stack]]`	Yes
Repo	Git repo cloned on server	`[[repo]]`	Yes
Builder	Build runner (server or AWS EC2)	`[[builder]]`	Yes
Build	Docker image build + push to registry	`[[build]]`	Yes
Procedure	Multi-stage workflow (sequential stages, parallel execs)	`[[procedure]]`	Yes
Action	TypeScript script calling Komodo API	`[[action]]`	Yes
Resource Sync	Declarative TOML sync from git repo	`[[resource_sync]]`	Yes
Alerter	Alert routing (ntfy, Slack, etc.)	`[[alerter]]`	Yes
Variable	Shared config/secrets with interpolation	`[[variable]]`	Yes
User Group	Permission groups	`[[user_group]]`	Yes

Server¶

Connect a server running Periphery agent to Komodo Core.

TOML Declaration¶

[[server]]
name = "server-prod"
description = "the prod server"
tags = ["prod"]

[server.config]
address = "http://localhost:8120"
region = "AshburnDc1"
enabled = true

Config Fields¶

Field	Description	Default
`address`	Periphery agent URL	—
`region`	Display region	—
`enabled`	Enable/disable server	`false`

Flow: Add New Server¶

Create onboarding key in Komodo UI or API

Install Periphery on target server:

curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py \
  | python3 - \
  --core-address="https://<core-address>" \
  --connect-as="$(hostname)" \
  --onboarding-key="O-..."

Verify connection status is OK in Komodo
(Optional) Add [[server]] TOML to resource sync for declarative management

Key Locations¶

Component	Method	Path
Core	Container	`/config/keys/core.key`
Periphery	Container	`/config/keys/periphery.key`
Periphery	Systemd	`${root_directory}/keys/periphery.key`

Periphery Config¶

Root install: /etc/komodo/periphery.config.toml
User install: $HOME/.config/komodo/periphery.config.toml
Root directory default: /etc/komodo
Sub-dirs: stacks/, repos/, builds/

Deployment¶

Deploy a single Docker container via docker run on a Server or Swarm.

TOML Declaration¶

[[deployment]]
name = "my-app"
description = "My application"
tags = ["prod"]
deploy = true

[deployment.config]
server = "server-prod"
image.type = "Image"
image.params.image = "ghcr.io/myorg/my-app:latest"
network = "host"
restart = "unless-stopped"

environment = """
DB_HOST = db.example.com
LOG_LEVEL = info
"""

volumes = """
/data/my-app/data:/app/data
/data/my-app/config:/app/config
"""

Config Fields¶

Field	Description	Default
`server`	Target Server	—
`image`	Image source (Build or custom string)	—
`network`	Docker network	`host`
`restart`	Restart policy	`unless-stopped`
`ports`	Port mappings	`[]`
`volumes`	Bind mounts	`""`
`environment`	Env vars (supports `[[VAR]]` interpolation)	`""`
`labels`	Docker labels	`""`
`command`	Override default CMD	`""`
`extra_args`	Extra `docker run` flags	`""`
`send_alerts`	Alert on state changes	`true`
`auto_update`	Auto-redeploy on new digest	`false`
`poll_for_updates`	Check for updates indicator	`false`

Lifecycle Actions¶

Action	Description
Deploy/Redeploy	Destroy + create with current config
Start	Start stopped container
Stop	Stop container (preserves state)
Remove	Destroy container entirely

Config changes only take effect after Redeploy (not start/stop).

Deploy Ordering¶

Use after to create dependencies:

[[deployment]]
name = "app-02"
after = ["app-01"]  # Deploys only after app-01

Cross-type: Stacks can depend on Deployments and vice versa.

Stack¶

Deploy Docker Compose projects via docker compose up.

TOML Declaration¶

[[stack]]
name = "my-stack"
description = "My compose stack"
tags = ["prod"]
deploy = true

[stack.config]
server = "server-prod"
file_paths = ["compose.yaml"]
run_directory = "/opt/stacks/my-stack"
git_provider = "github.com"
git_account = "my-user"
repo = "myorg/stacks"
branch = "main"

environment = """
DB_HOST = db.example.com
LOG_LEVEL = info
"""

Config Fields¶

Field	Description	Default
`server`	Target Server	—
`file_paths`	Compose files (supports multiple `-f`)	`[]`
`run_directory`	Working directory for compose	—
`project_name`	Override project name	Stack name
`environment`	Env vars written to `.env` file	`""`
`extra_args`	Extra `docker compose up` flags	`""`
`ignore_services`	Exclude from health checks	`[]`
`git_provider`	Git domain	`github.com`
`git_account`	Account for private repos	—
`repo`	Repository `owner/repo`	—
`branch`	Branch to clone	`main`
`auto_update`	Auto-redeploy on new digest	`false`
`poll_for_updates`	Check for updates	`false`
`send_alerts`	Alert on state changes	`true`

Compose File Sources¶

Write in UI — Komodo writes files at deploy time
Files on host — Point to existing files on server
Git repo — Clone repo + auto-redeploy via webhook

Import Existing Project¶

Match by compose project name. If different from Stack name, set project_name.

# Find existing project names
docker compose ls

Build¶

Build Docker images via docker build and push to registry.

TOML Declaration¶

[[build]]
name = "my-app"

[build.config]
builder = "builder-01"
repo = "myorg/my-app"
branch = "main"
git_account = "my-user"
image_registry = [
  { domain = "ghcr.io", account = "my-user", organization = "my-org" }
]

Config Fields¶

Field	Description	Default
`builder`	Builder resource name	—
`version`	Current version (`major.minor.patch`)	`0.0.0`
`auto_increment_version`	Auto-increment patch	`true`
`image_name`	Override image name (uses build name)	`""`
`image_tag`	Tag postfix (e.g. `aarch64`)	`""`
`include_latest_tag`	Push `:latest`	`true`
`include_version_tags`	Push semver tags	`true`
`include_commit_tag`	Push commit hash tag	`true`
`linked_repo`	Komodo Repo resource	`""`
`repo`	Git repo `owner/repo`	`""`
`branch`	Branch	`main`
`build_path`	Build context dir (relative to repo root)	`.`
`dockerfile_path`	Dockerfile path (relative to build_path)	`Dockerfile`
`files_on_host`	Use local files instead of git	`false`
`dockerfile`	Inline Dockerfile content	`""`
`image_registry`	Registry targets	`[]`
`build_args`	Build args (`KEY=value`)	`""`
`secret_args`	Build secrets (not in history)	`""`
`pre_build`	Command before build	—
`use_buildx`	Use `docker buildx`	`false`

Dockerfile Sources¶

Write in UI — Inline Dockerfile with variable interpolation
Files on host — files_on_host = true + absolute paths
Git repo — Clone + build (default mode)

Image Tagging¶

Setting	Tags Produced	Example
`include_version_tags`	Full + minor + major	`:1.2.3`, `:1.2`, `:1`
`include_latest_tag`	Latest	`:latest`
`include_commit_tag`	Short hash	`:a6v8h83`

With image_tag = "aarch64": :1.2.3-aarch64, :latest-aarch64, :a6v8h83-aarch64, :aarch64

Multi-Registry Push¶

image_registry = [
  { domain = "ghcr.io", account = "user", organization = "org" },
  { domain = "docker.io", account = "user" },
]

First registry is default for connected Deployments.

Builder¶

Defines where builds run. Can be a Server or AWS EC2 spot instance.

Server Builder¶

Points to existing Server with Periphery:

[[builder]]
name = "builder-01"

[builder.config]
type = "Server"
params.server = "development"

AWS EC2 Builder¶

Launches temporary instance per build:

[[builder]]
name = "aws-builder"

[builder.config]
type = "Aws"
params.region = "us-east-2"
params.instance_type = "c5.2xlarge"
params.ami_id = "ami-xxxxxxxx"
params.subnet_id = "subnet-xxxxxxxx"
params.key_pair_name = "ssh-key"
params.assign_public_ip = true
params.use_public_ip = true
params.security_group_ids = ["sg-xxxxxxxx"]
params.user_data = """
#!/bin/bash
curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py | \
  HOME=/root python3 - --version=v2.X.X
"""

Procedure¶

Multi-stage workflow. Stages run sequentially, executions within stage run in parallel.

TOML Declaration¶

[[procedure]]
name = "build-and-deploy"
description = "Builds then deploys"
tags = ["prod"]

[[procedure.config.stage]]
name = "Build"
executions = [
  { execution.type = "RunBuild", execution.params.build = "my-app" },
]

[[procedure.config.stage]]
name = "Deploy"
executions = [
  { execution.type = "Deploy", execution.params.deployment = "app-01" },
  { execution.type = "Deploy", execution.params.deployment = "app-02" },
]

Stage Config¶

Field	Description	Default
`name`	Display name	—
`enabled`	Active stage	`true`
`executions`	Parallel execution list	`[]`

Scheduling¶

config.schedule = "Every day at 01:00"
config.schedule_format = "English"  # or "Cron"
config.schedule_enabled = true

Batch Executions¶

Match multiple resources by name using wildcard and regex:

executions = [
  { execution.type = "BatchDeployStackIfChanged", execution.params.pattern = "foo-* , \\^bar-.*$\\" },
]

Action¶

TypeScript scripts with pre-initialized Komodo client. No API key needed.

Example: Restart deployments matching tags¶

const deployments = await komodo.read("ListDeployments", {
  query: { tags: ["backend"] },
});

for (const deployment of deployments) {
  await komodo.execute("RestartDeployment", {
    deployment: deployment.name,
  });
  console.log(`Restarted ${deployment.name}`);
}

Example: Run command on server terminal¶

await komodo.execute_server_terminal({
  server: "server-prod",
  command: "df -h",
  init: { command: "bash" },
}, {
  onLine: (line) => console.log(line),
  onFinish: (code) => console.log("Exit code:", code),
});

Resource Sync¶

Declarative resource management from TOML files in git repos. Core diffs TOML vs existing resources and applies updates.

TOML Declaration¶

[[resource_sync]]
name = "my-sync"

[resource_sync.config]
git_provider = "github.com"
git_account = "my-user"
repo = "myorg/infra"
branch = "main"
resource_path = ["stacks/", "repos.toml"]
include_resources = true

How It Works¶

Core polls configured files for changes
Diffs TOML declarations against existing resources
Displays pending actions in UI
Executes on manual confirm or auto via webhook

Managed Mode¶

When sync points to single file, enable managed mode to let Core write UI changes back to the file. Creates git commits for repo-based files.

Match Tags¶

Filter which resources each sync manages. Multiple syncs can manage resources independently on a "per-project" basis.

Repo¶

Git repo cloned on a server. Can run scripts after pull.

TOML Declaration¶

[[repo]]
name = "my-repo"
description = "Build binary from source"
tags = ["build"]

[repo.config]
server = "server-01"
git_provider = "github.com"
git_account = "my-user"
repo = "myorg/my-app"
branch = "main"

on_pull.path = "."
on_pull.command = """
cargo build --release
cp ./target/release/app /usr/local/bin/app
"""

Variable¶

Shared config/secrets with [[VAR]] interpolation across all resources.

TOML Declaration¶

[[variable]]
name = "DB_PASSWORD"
value = "secret123"

Interpolation¶

Use [[VAR_NAME]] in environment blocks:

environment = """
DB_PASSWORD = [[DB_PASSWORD]]
API_KEY = [[API_KEY]]
"""

Secret Variables¶

Created via API or Python script:

python3 .claude/skills/komodo/scripts/komodo.py create-variable SECRET_NAME value --secret

Alerter¶

Route alerts to endpoints (ntfy, Slack, etc.) with resource and alert type filters.

Alert Routing¶

Resource whitelist/blacklist
Alert type filter
Multiple alerters for different teams/channels

Variable Interpolation¶

All resource environment fields support [[VAR_NAME]] syntax. Variables are resolved from Komodo Variables (managed in UI or TOML).

Interpolation Patterns¶

# In any resource environment
environment = """
DB_HOST = [[DB_HOST]]
DB_PASSWORD = [[DB_PASSWORD]]  # resolved from Komodo Variable
 hardcoded_value = something  # literal
"""

Cross-Resource Dependencies¶

Deploy Ordering with `after`¶

Any resource with deploy = true can use after to create ordering:

[[deployment]]
name = "app-02"
deploy = true
after = ["app-01"]

[[stack]]
name = "frontend"
deploy = true
after = ["app-02"]

Cross-type: Stacks, Deployments, and Builds can all depend on each other.

Resource Attachments¶

Resource	Can Attach To
Deployment	Server, Swarm, Build
Stack	Server, Swarm
Build	Builder, Repo
Repo	Server
Builder	Server

Our Project's Sync Architecture¶

Per komodo/stacks/root_syncs/resource_sync.toml:

Sync Name	Path	Resources
`root-syncs`	`./komodo/stacks/root_syncs`	Servers, alerter, procedures
`applications`	`./komodo/stacks/applications`	App stacks
`database`	`./komodo/stacks/database`	DB stacks
`development`	`./komodo/stacks/development`	Dev stacks
`llm`	`./komodo/stacks/llm`	LLM stacks
`monitoring`	`./komodo/stacks/monitoring`	Monitoring stacks
`networking`	`./komodo/stacks/networking`	Network stacks
`orchestration`	`./komodo/stacks/orchestration`	Workflow stacks
`storage`	`./komodo/stacks/storage`	Storage stacks
`builds`	`./komodo/builds`	Custom image builds

All syncs use managed: false → run-sync auto-applies, no UI confirm needed.

Komodo Resource Flows¶

Resource Types Overview¶

Server¶

TOML Declaration¶

Config Fields¶

Flow: Add New Server¶

Key Locations¶

Periphery Config¶

Deployment¶

TOML Declaration¶

Config Fields¶

Lifecycle Actions¶

Deploy Ordering¶

Stack¶

TOML Declaration¶

Config Fields¶

Compose File Sources¶

Import Existing Project¶

Build¶

TOML Declaration¶

Config Fields¶

Dockerfile Sources¶

Image Tagging¶

Multi-Registry Push¶

Builder¶

Server Builder¶

AWS EC2 Builder¶

Procedure¶

TOML Declaration¶

Stage Config¶

Scheduling¶

Batch Executions¶

Action¶

Example: Restart deployments matching tags¶

Example: Run command on server terminal¶

Resource Sync¶

TOML Declaration¶

How It Works¶

Managed Mode¶

Match Tags¶

Repo¶

TOML Declaration¶

Variable¶

TOML Declaration¶

Interpolation¶

Secret Variables¶

Alerter¶

Alert Routing¶

Variable Interpolation¶

Interpolation Patterns¶

Cross-Resource Dependencies¶

Deploy Ordering with after¶

Resource Attachments¶

Our Project's Sync Architecture¶

Deploy Ordering with `after`¶