Configuration

AKOS workspaces are defined by a single YAML file (akos.config.yaml). The CLI provides a set of commands for creating, verifying, comparing, explaining, and migrating these configuration files, plus a lockfile system for reproducible deployments.

Initializing a workspace

To scaffold a new workspace in the current directory:

akos init

To initialize in a specific directory:

akos init ./my-workspace

This creates:

• akos.config.yaml — the workspace config
• .agentskitos/ — the runtime data directory
• .gitignore — pre-populated to exclude .agentskitos/ and .env files

init options

Available templates: hello-agent (seeds a minimal agent and flow).

akos init --template hello-agent

After scaffolding with hello-agent, you can immediately do a dry run:

akos run akos.config.yaml --mode dry_run

Validating a config file

akos config validate akos.config.yaml

Exits 0 when the file is valid, or exits 1 and prints each validation error with its field path and message. Works with both YAML and JSON config files.

Diffing two config files

akos config diff akos.config.yaml akos.config.new.yaml

Outputs a structural diff:

• + path: value — key added
• - path: value — key removed
• ~ path: old → new — value changed

Exits 0 whether or not there are changes. Useful in CI to detect unexpected config drift between environments.

Explaining config layer provenance

When you run AKOS with multiple config layers (defaults, global, workspace, env, runtime), config explain shows which layer set each leaf value in the merged result:

akos config explain \
  --defaults defaults.yaml \
  --workspace akos.config.yaml

Use any combination of the layer flags:

At least one flag is required. The command prints a table of every leaf value and the layer that supplied it, followed by the fully merged config value.

Migrating a config to a newer schema

akos config migrate akos.config.yaml

Migrates the config to the current schema version. Prints a list of migration steps applied and the resulting config.

To target a specific version:

akos config migrate akos.config.yaml --to 2

If no migration steps are needed (the config is already current), the command exits 0 with (no migrations needed).

Lockfiles

A lockfile (akos.lock) pins the exact versions and content hashes of agents, flows, plugins, and providers in a workspace config. Check it into source control to ensure reproducible deployments.

Generate a lockfile

akos lock akos.config.yaml

Writes akos.lock next to the config file. To write to a different path:

akos lock akos.config.yaml --out /path/to/akos.lock

Verify a lockfile has not drifted

akos lock akos.config.yaml --check

Compares the existing lockfile against the current config. Exits 0 when they match, or exits 5 and lists drift issues. Use this in CI to catch unintended config changes.

Sync installed versions

After verifying the lockfile, use sync to apply any version drift between the lockfile and your installed packages:

# Check for drift (default — no changes made)
akos sync
 
# Apply drift (install/upgrade to match the lockfile)
akos sync --apply
 
# Restrict scope
akos sync --plugins-only
akos sync --core-only
 
# Point to a non-default lockfile
akos sync --lock /path/to/akos.lock