Configuration

AKOS workspaces are defined by a single YAML file (agentskit-os.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:

agentskit-os init

To initialize in a specific directory:

agentskit-os init ./my-workspace

This creates:

• agentskit-os.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).

agentskit-os init --template hello-agent

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

agentskit-os run agentskit-os.config.yaml --mode dry_run

Validating a config file

agentskit-os config validate agentskit-os.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

agentskit-os config diff agentskit-os.config.yaml agentskit-os.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:

agentskit-os config explain \
  --defaults defaults.yaml \
  --workspace agentskit-os.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

agentskit-os config migrate agentskit-os.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:

agentskit-os config migrate agentskit-os.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 (agentskit-os.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

agentskit-os lock agentskit-os.config.yaml

Writes agentskit-os.lock next to the config file. To write to a different path:

agentskit-os lock agentskit-os.config.yaml --out /path/to/agentskit-os.lock

Verify a lockfile has not drifted

agentskit-os lock agentskit-os.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)
agentskit-os sync
 
# Apply drift (install/upgrade to match the lockfile)
agentskit-os sync --apply
 
# Restrict scope
agentskit-os sync --plugins-only
agentskit-os sync --core-only
 
# Point to a non-default lockfile
agentskit-os sync --lock /path/to/agentskit-os.lock