Configs

Overview

Configs are the file-backed definition layer for an ArchAstro 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

The key idea is simple:

• 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.

In practice 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

This is what makes ArchAstro feel like a real developer platform instead of a sequence of one-off clicks or shell commands.

The CLI resource and the local configs/ workflow are related but different:

• archastro config ... works with live config objects directly
• archastro configs ... manages the local file-backed sync and deploy loop

Most 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:

archastro configs init

Then inspect the kinds the project supports:

archastro configs kinds
archastro configs sample agent
archastro configs sample 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:

archastro configs sync

When you are ready to push reviewed changes back:

archastro configs deploy

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

archastro list configs --kind workflow
archastro describe config <config_id>
archastro configs content <config_id>

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
archastro configs sample workflow --to-file ./tmp/workflow.sample.yaml
archastro configs validate -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 compare it to the live object before you deploy:

archastro describe config <config_id>
archastro configs content <config_id>

That keeps the local file and the live platform object in the same review loop.

---

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

Most 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 first designs a workflow in the portal, then decides it belongs in code review.

The useful sequence is:

1. build and test the first version in the portal
2. run archastro configs sync
3. review the generated configs/ files in the repo
4. edit the workflow file locally
5. validate before deploy
6. run archastro configs deploy

That pattern lets the portal stay fast for design while configs/ becomes the durable source of truth.

---

Good config posture

Good config usage usually follows five rules:

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.