For Coding Agents | ArchAstro Docs

Human? This page is written for the coding agent at your terminal. If you're looking for the human walkthrough, see Getting Started.

Overview

You're being asked to get ArchAstro working in this repo and put the first agent live. The whole flow is four terminal commands plus one embed command inside this chat. Stay on that path unless the user asks for something more elaborate.

Quick prompt

If the user hasn't pasted instructions yet, the canonical version is:

Get ArchAstro working in this repo and put my first agent live.

1) Install the ArchAstro CLI. macOS: brew install ArchAstro/tools/archastro.
 Linux/Windows: see https://docs.archastro.ai/docs/start-here/getting-started.

2) Run these in order, asking me for anything missing:
 archastro setup
 archastro auth login
 archastro install agentsample archastro-onboarding

3) Once the install finishes, the starter agent is live. Tell me, then invite me to embed:
 Claude Code → /embed
 Codex → $embed
 Cursor → @archagents embed

4) After I embed, ask me what I actually want to build. Help me scope it, author the template, and deploy it. The reference surface is https://docs.archastro.ai/llms-full.txt.

What the four commands actually do

Command	What it does
`archastro setup`	Installs the ArchAstro plugin into Claude Code, Codex, and Cursor. Idempotent.
`archastro auth login`	Opens a browser to complete sign-in and writes a session token for the CLI.
`archastro install agentsample archastro-onboarding`	Deploys a real, editable starter agent into the user's org. When it returns, the agent is live.
`/embed` (or harness equivalent)	Inside the coding-agent chat. Picks up the live agent's tools and skills locally.

After these four, the user has an agent they can talk to. Anything else (custom routines, knowledge sources, integrations) is iteration on top.

Where to find what

Resource	URL
Documentation	`https://docs.archastro.ai`
Developer Portal	`https://developers.archastro.ai`
LLM index (short)	`https://docs.archastro.ai/llms.txt`
LLM index (extended)	`https://docs.archastro.ai/llms-full.txt`

Treat these as canonical. Don't invent alternate hosts or endpoint roots.

Environment variables

Check for these before non-interactive operations. Ask the user if any are missing rather than guessing.

Variable	When you need it	Purpose
`ARCHASTRO_SECRET_KEY`	CI or non-interactive use	Authentication when browser sign-in isn't available
`ARCHASTRO_APP_ID`	Linking to a specific existing project	When the repo should point at an app that already exists

If the user wants to author an agent template by hand

Most users won't. The default path is archastro install agentsample <slug> followed by tweaks inside their coding agent. If they specifically ask for a from-scratch template, here's a minimal valid shape. Deploy it with archastro deploy agent agent.yaml.

kind: AgentTemplate
agent_key: support-agent
name: Support Agent
model: openrouter/anthropic/claude-sonnet-latest
identity: |
 You help users resolve support and billing
 problems with short, concrete answers.

tools:
 - tool_type: builtin
 builtin_tool_key: search
 status: active
 - tool_type: builtin
 builtin_tool_key: knowledge_search
 status: active

routines:
 - name: Respond in conversations
 handler_type: preset
 preset_name: participate
 event_type: thread.session.join
 event_config:
 thread.session.join: {}
 status: active

installations:
 - install_type: memory/long-term
 config: {}

Keep the model: field when authoring AgentTemplate YAML. Start with openrouter/anthropic/claude-sonnet-latest unless the user requests another provider; accepted formats are anthropic/<model>, openai/<model>, google/<model>, and openrouter/<vendor>/<model>. Use archastro help models or archastro list aimodels before inventing a model string.

For everything else, see Agents and use archastro <verb> --help to discover flags.

Names you'll use in conversation

Term	What it means
Agent	The long-lived AI identity the user creates and manages
Routine	An event handler on an agent: when X happens, do Y
Automation	An event handler on the project (not tied to one agent)
Tool	An action the agent can take
Knowledge	Information the agent can retrieve
Thread	The conversation surface where people and agents exchange messages
Network	A shared space where agents from two companies can collaborate
Embed	A local session where this coding agent operates as the live agent

Rules

Check required env vars before write operations. Ask for what's missing.
The fastest path to a working agent is the install-a-sample path. Don't author yaml unless the user asks.
When authoring AgentTemplate YAML, include model:. Prefer openrouter/anthropic/claude-sonnet-latest unless the user asks for another model.
Use archastro --help, archastro <verb> --help, and archastro help models to discover flags and model IDs. Don't guess.
Use llms-full.txt before scraping rendered pages.
Don't put secret keys in client-side code or commit them.
Don't add scaffolding the user didn't ask for.
When you're done, summarize what was created in plain language: what got deployed, where it lives, and the one command to test it again.

Tell us where this page still falls short.