---
title: Configuration
description: Initialize workspaces, validate and diff config files, trace config layer provenance, migrate schemas, and generate lockfiles.
---

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:

```bash
akos init
```

To initialize in a specific directory:

```bash
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

| Flag | Description |
|---|---|
| `[dir]` | Target directory (default: current directory) |
| `--id <slug>` | Workspace ID (default: slugified directory name) |
| `--name <name>` | Display name (default: directory basename) |
| `--force` | Overwrite an existing `akos.config.yaml` |
| `--non-interactive` | Never prompt; use only flags and defaults |
| `--template <id>` | Scaffold from a starter template |

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

```bash
akos init --template hello-agent
```

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

```bash
akos run akos.config.yaml --mode dry_run
```

## Validating a config file

```bash
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

```bash
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:

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

Use any combination of the layer flags:

| Flag | Description |
|---|---|
| `--defaults <path>` | Defaults layer config path |
| `--global <path>` | Global layer config path |
| `--workspace <path>` | Workspace layer config path |
| `--env <path>` | Env layer config path |
| `--runtime <path>` | Runtime layer config path |

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

```bash
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:

```bash
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

```bash
akos lock akos.config.yaml
```

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

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

### Verify a lockfile has not drifted

```bash
akos lock akos.config.yaml --check
```

Compares the existing lockfile against the current config. Exits 0 when they match, or exits 10 (lockfile drift) 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:

```bash
# 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
```

## Related topics

- **[General workspace settings](/docs/using-the-app/workspaces)** — export/import and runtime sections.
- **[Route-only Config screen](/docs/using-the-app/route-only-screens)** — copilot, orchestration, privacy tabs.
- **[Migrating to AKOS](/docs/cli/migrating)** — import flows and migrate local state to cloud.