Configs

Overview

Configs are the file-backed definition layer for an ArchAgents project.

Use them when you have already proved a setup works and now want to:

• keep it in version control

• review changes before deployment

• sync the live project into local files

• redeploy the same shape without rebuilding it by hand

• direct create commands are fast for exploration

• configs/ is the right home once the shape is real and worth keeping

---

What a config actually is

A config is a versioned project object stored as file content plus a virtual path.

That means:

• the platform still has live objects
• the CLI can pull those objects into local files
• your team can review and redeploy them from the repo

Configs turn agent setup into reviewable code that lives in your repo alongside everything else.

The CLI exposes two related-but-different surfaces, both verb-first:

• Direct config commands (archagent describe config, archagent validate configs, archagent list configs) work with live config objects directly. Use them when you're debugging or inspecting one specific config.
• The local file-backed loop (archagent sync configs, archagent deploy configs) manages a local configs/ directory you can edit, review in source control, and push back. Use it for repeatable, reviewable changes.

Teams use both. They inspect live objects when they need to debug, then use configs/ when they want changes they can review and redeploy.

---

The basic config loop

Start by creating the local config directory:

archagent init --enable-configs

Then inspect the kinds the project supports:

archagent list configkinds
archagent describe configsamples agent
archagent describe configsamples workflow

Use those samples to understand the file shape before you edit anything.

When you want to pull the current project state into local files:

archagent sync configs

When you are ready to push reviewed changes back:

archagent deploy configs

If you keep generated or scratch files inside configs/ that should not ship, add an .aaignore file at the root of the directory. The deploy step honors it the same way Git honors .gitignore:

# configs/.aaignore
**/_generated/
*.draft.yaml

If you need to inspect a single live config while you are debugging:

archagent list configs --kind workflow
archagent describe config <config_id>

describe config shows both the config metadata and its full content. That is often the fastest way to answer "what is the platform actually holding right now?" before you sync anything locally.

---

Validate before you deploy

The safest pattern is:

1. generate or edit the config locally
2. validate the content
3. deploy only after it is readable and intentional

For example:

mkdir -p ./tmp
archagent describe configsamples workflow --to-file ./tmp/workflow.sample.yaml
archagent validate configs -k workflow -f ./tmp/workflow.sample.yaml

That is especially useful when a coding agent is generating config content and you want a quick sanity check before deployment.

When the config already exists on the server, validate the file and then inspect the live object before you deploy:

archagent describe config <config_id>

That keeps the local file and the live platform object in the same review loop, the describe output includes the full content alongside the metadata.

---

When to stay with direct commands

Stay with direct commands when you are:

• proving the first agent loop
• testing one routine
• poking at the data model
• learning the CLI surface

Move to configs when you are:

• keeping an agent or workflow for the long term
• collaborating through code review
• deploying the same setup more than once
• managing a project with several stable objects

---

A realistic team pattern

Teams follow this sequence:

1. create one agent directly
2. test it with an agentsession
3. attach the first routine or workflow
4. once the shape feels right, run configs init
5. sync the live setup into configs/
6. review future changes as files instead of recreating objects manually

That gives you fast learning first, then repeatability.

A workflow-specific example

Suppose the team builds a workflow from a config sample, then iterates on it.

The sequence is:

1. generate a sample with archagent describe configsamples workflow
2. edit the workflow file locally
3. validate before deploy
4. run archagent deploy configs
5. review the result in the portal for a visual overview
6. iterate by editing the file and redeploying

That pattern keeps the CLI and source control as the primary creation path while the portal provides the visual review layer.

---

Best practices

Five rules for working with configs:

1. prove the setup live before you freeze it into files
2. keep paths and kinds readable
3. validate generated content before deploy
4. prefer reviewed file changes over repeated ad hoc recreation
5. use sync to keep the local view honest

---

Where to go next

1. Read CLI for the full terminal workflow.
2. Read Samples for end-to-end examples that move from direct commands into config files.
3. Read Workflows when the file-backed object you are managing is a process definition.