Agents and environments

An agent is the container for one piece of automated work: a git repository of authored workflows, the environments that branch it, and their settings. Each environment holds a draft, where every edit lands, and a published version, which is what production traffic executes. Content moves from one to the other only by an explicit act: publish, discard, restore or promote.

Agents

An agent belongs to the organization that was active when a member created it. The agent list shows the agents your groups open: every agent when you are in a built-in group, and otherwise the agents your custom groups give a role on (see Roles and groups). Creating an agent needs agents:create — from the Organization Owner, Administrator or Maintainer group, or a custom group giving Create agents — and asks for a name. You become the new agent’s Administrator through a group created with it and named after it. The platform derives the agent’s slug from it, which is what its URLs carry and which is unique within the organization (a colliding name gets a distinct slug rather than an error). It then seeds the agent’s repository from the template and creates a default environment named main, on the branch main.

Agent Settings in the rail has two sections:

Agent holds the agent’s name and the action that deletes it. Renaming the agent regenerates its slug and rewrites the name into every environment’s .archmax/settings.yml. Renaming needs agent:write (a Maintainer). Deleting asks for confirmation, needs agent:delete (the agent’s Administrator), and removes every environment of the agent with its versions, its draft and its sessions’ files.
Environments lists the agent’s environments with their branch and parent. Each row edits the environment’s name, branch and parent (agent:write), or deletes it (agent:delete). The default environment cannot be deleted.

Who can open the agent, and with which role, is managed in the Groups section of Organization & Account settings: the agent’s Administrator gives a group a role on it there, changes it and takes it away (see Custom groups).

What an environment holds

An environment’s files are the agent’s workspace:

AGENTS.md                           # the system prompt, with optional frontmatter
icon.png                            # the agent icon
workflows/<slug>/workflow.yaml      # one workflow per directory
workflows/<slug>/WORKFLOW.md        # optional prose the agent also reads
workflows/<slug>/hooks/<name>.js    # the workflow's lifecycle hook scripts
workflows/<slug>/tests/*.test.yaml  # the workflow's cases
skills/<slug>/SKILL.md              # skill bundles
.archmax/settings.yml               # settings the platform maintains
.archmax/connections/<slug>.yml     # one file per connection
.archmax/mounts/<slug>.yml          # one file per remote mount

A session’s agent sees only part of it: AGENTS.md, skills/, its own session folder and the mounts its state is granted. The workflows/ directory is routed into no agent’s workspace, so an agent cannot read its own workflow, the hooks and rubrics that check its work, or the cases that grade it. Entries whose names begin with a dot, such as .archmax/, are the platform’s own and are edited through the surfaces that own them.

Storage, the folders a workflow mounts, sits beside the environment and is not versioned: publishing, discarding and restoring never touch it. See Files and mounts.

The Agent page

The Agent rail entry configures the agent in the open environment. Its header Save writes every card at once:

System prompt is stored as AGENTS.md. A session’s agent reads the whole file. The file may open with a YAML frontmatter block between two --- lines; the card edits the document below it and leaves the frontmatter as it was.
Icon is stored as icon.png beside AGENTS.md. Pick a PNG, JPEG, WebP or GIF; the page crops it to a centred square and saves a PNG of at most 512 × 512 px. The icon is always drawn as a circle, with white behind any transparent area.
Description is at most 500 characters, stored as the description key of the frontmatter of AGENTS.md. It is shown under the agent’s name when a chat starts on the Chat page, and the agent reads it with the rest of the file.
LLM picks the model provider connection (Agent connection) and the model ID (Agent model ID) the environment’s workflow turns use. Any llm connection of the environment, or one it inherits from its parent, can be chosen. When the connection declares no rate for the model, the card warns that its spend cannot be measured and that a spend cap is not enforced for it; the selection still saves. See Connections and tools.
Recursion limit, a field of the LLM card, bounds each workflow turn (LangGraph’s recursion limit), from 1 to 1000, 100 by default. It is stored on the environment rather than in its files.

The prompt, icon, description and model are ordinary draft changes: Publish makes them permanent, Discard brings back what was published, and Promote carries them into the parent.

The model selection is written to .archmax/settings.yml, which the platform maintains:

version: 1
agent:
  name: Billing Agent
environment:
  name: main
  branch: main
workflowsDir: workflows
model:
  agent:
    connection: openai
    model: gpt-6.1-sol

A turn in an environment with no model: block fails before any model call, saying that no model is configured.

Environments

An environment is a named branch of the agent’s repository with its own draft, its own published version, its own sessions, its own connections and credentials, and its own Storage. It may name a parent environment, from which it inherits connections and credentials (see Connections and tools) and into which it can be promoted.

Creating one

Choose New environment in the top bar’s environment selector, then give it a name, a branch and a parent environment:

None (empty environment) starts the branch from an empty commit. The environment holds only the scaffolding the platform writes, its Storage is empty and it has no parent.
A parent forks the branch from the parent’s last published state, never from its unpublished draft. When the parent has pending changes, the dialog says they will not be copied; publish them first to include them. The parent’s connections appear in the new environment as inherited rather than as copies, and its model selection is kept, so the model resolves through the inherited connection without setup. Storage is copied as it is at that moment. Workflow spend caps are not copied.

The environment shows Provisioning… until it is Ready, or Failed with the reason.

The environment-creation API can also start an environment at an earlier version of its source (fromEnvironmentId with fromCommit); the commit must belong to the source’s branch history. The app offers no control for this.

Renaming, changing the branch, deleting

The environment editor in Agent Settings changes the name (unique within the agent, and mirrored into .archmax/settings.yml), the branch (the draft is re-seeded from the new branch’s content) and the parent. Deleting an environment takes its trigger deployments down, then removes its draft, its published versions, its Storage and its sessions’ files.

The draft and the published version

Every edit made in the app writes the draft without a commit: the editor, the Agent page, the Skills page and the design agent alike. The environment’s pending changes are the difference between the draft and its current published version, file by file. While there are any, the top bar’s button reads Publish; afterwards it reads Published.

Which content a session executes depends on how it was opened:

Session	Executes
production: a deployed trigger’s firing outside a listen window, a call through an MCP endpoint, a chat a member starts on the Chat page	the version that was current when the session opened, on every one of its turns
testing: a session started from the editor or the Sessions page, a chat through an AG-UI endpoint, a firing a listen window observes, a replay, an evaluation case	the draft, read afresh on every turn

A production session keeps its version for its whole life. Publishing while it is parked on a decision does not change what its next turn executes, even if the publish removed the state it waits in, and nothing moves an open session onto a newer version. The recourse for a session stuck on a defective version is to cancel or delete it; the next firing opens a new session on the current version.

A testing session sees an edit on its next turn, which is what makes the editor’s edit-and-try-again loop work. An environment that has never been published cannot serve production traffic: a firing for it fails before any session opens.

Publishing, discarding, restoring, promoting

These four act on the environment’s branch. Open Environment in the rail and choose Versioning: its header offers Discard and Publish while there are pending changes, and Promote to the parent when the environment has one.

Publish asks for an optional description and commits every pending change as one version, authored by you. The new version becomes current, production sessions opened from then on execute it, and the environment’s trigger deployments are reconciled (see Triggers).

Discard returns the draft to the current published version. It creates no version and cannot be undone, and it leaves Storage and session files alone.

Restore is offered on every version but the current one. It creates a new version whose content equals the chosen one; nothing in the history is deleted. Restore is refused while the environment has pending changes, so publish or discard first. The restored content becomes both the draft and the published version, and trigger deployments are reconciled.

Promote replaces the parent’s content with this environment’s, as one new version in the parent’s history that names this environment as its source. Files deleted here are deleted there too, with one exception: connection files are merged. A connection this environment holds replaces the parent’s of the same slug, one only the parent holds is kept, and one only this environment holds is added. Credentials never move; making one available in the parent is an act in the parent.

The promote dialog shows what will happen before anything does:

blockers: pending changes in either environment, or a parent that is not ready. Pending changes here can be published from the dialog with Publish now;
the connections after the promote, each added, replaced or kept;
credentials the result needs that the parent’s credential chain does not hold, which also block the promote;
Storage folders the promoted workflows mount that the parent lacks, since Storage is not promoted, and remote mounts whose connections the parent lacks;
the file changes between the two.

After a promote, Undo restores the parent’s previous version as a new version. A promote reconciles the parent’s trigger deployments and leaves its spend caps as they were.

Versions and their history

A version is a published snapshot of the environment, written by a publish, a promote or a restore. The Versioning table lists them newest first: the kind (Publish, Promote naming its source, Restore naming the version it restored), the description, the author, when, and the short commit id, with Current marking the one new sessions open on. Versions are never edited or pruned, so a production session pinned to an old one keeps working.

The Environment page

Environment in the rail opens the open environment’s own concerns in three sections: Connections (see Connections and tools), Versioning (above) and Model Spending (see Spend and spend caps). Choosing another environment in the top bar keeps the section you are on.