Quickstart

This page takes a fresh clone of the repository to a first session on your machine: the platform in dev mode without sign-in, one agent, a workflow with a human state, a decision, and a published version you chat with. To run the published image instead, see installation.

Before you start

Check the tools:

node --version           # v22: what CI and the image run
corepack enable          # provides the pnpm version package.json pins
docker compose version   # for MongoDB, Redis and MinIO

You also need a model the agent can call, with its key: any OpenAI-compatible API, AWS Bedrock or Azure OpenAI.

Start the platform

From the repository root:

pnpm install
cp .env.example .env
cp config.yaml.example config.yaml

Then edit .env:

• Set MASTER_KEY to the output of openssl rand -base64 32. In the database store a local setup uses, every credential is sealed with it, the model key you add below included, and saving one fails without it.
• For the design agent, set ARCHMAX_DESIGN_AGENT_API_KEY to a key for the endpoint and model config.yaml names under designAgent (https://api.openai.com/v1 and gpt-6.1-sol in the example). Left empty, that section is left out with a [config] line on the log, and a design-agent turn is refused as not configured.

Leave ARCHMAX_SIGN_IN unset, so the app signs you in as the dev user. Start MongoDB, Redis and MinIO, then the web app, the API and the dispatcher:

docker compose up -d mongo redis minio minio-init
pnpm dev
curl -s http://localhost:3001/api/health   # in a second terminal
# {"status":"ok","version":"dev"}

minio-init creates the bucket .env names (archmax-workspaces) in MinIO once; the platform does not create it.

Open http://localhost:5173; its dev server passes /api to the API on port 3001. With ARCHMAX_SIGN_IN unset the API resolves the fixed local dev user, the web app follows it, and the profile menu reads Dev mode (no sign-in).

Create an agent

On the Overview page choose New agent, enter an Agent name and Create. The platform provisions the agent’s git repository and a default environment, and opens the agent. It starts with one workflow, Example workflow: a single state with a manual trigger.

The icon rail on the left holds the agent’s pages: Sessions and Chat, then Workflows, Agent, Skills, Files and Environment.

Give it a model

Every turn calls a model through a model provider connection. Open Agent on the rail; its LLM card reads No model provider connection yet.

1. Choose Add model provider and pick Generic Model Provider (any OpenAI-compatible API), AWS Bedrock or Azure OpenAI.
2. Fill in its fields (for the generic provider a Base URL, the key, and the API: Chat Completions or Responses) and the model’s prices under Rates in USD per 1M tokens. Without rates a session still runs, but its spend cannot be measured.
3. Choose Connect. Then pick the connection as the Agent connection, enter the Agent model ID (such as gpt-6.1-sol), and Save.

A model on your machine

Owner-supplied URLs on localhost, on private networks or over plain http are refused. For a local model server, set ARCHMAX_ALLOW_PRIVATE_URLS=true in .env and restart pnpm dev; production ignores the setting.

Write a workflow

Save this as haiku-review.yaml: an agent state that writes, a human state where you decide, and a terminal state.

title: Haiku review
instructions: You write short poems for a reviewer. Keep every reply under six lines.
runtime:
  engine: archmax-harness
  version: "2"
states:
  write:
    instructions: Write a haiku about the sea and show it in your reply, then move to review.
    triggers:
      manual:
    transitions:
      - to: review
        description: The haiku is written and shown in the reply.
  review:
    type: human
    instructions: A person reads the haiku and approves it or sends it back.
    transitions:
      - to: done
        type: approve
        description: "Approve: the haiku can stay as it is."
      - to: write
        type: refine
        description: "Send back: write a different haiku."
  done:
    instructions: Say in one sentence that the haiku was approved.

Open Workflows and import the file with the upload button (Import workflow). The file name becomes the workflow’s identifier, haiku-review, and the editor opens on it. Every key is the harness’s machine spec, explained in the workflow machine.

The same workflow can be made two other ways:

• In the editor. New workflow asks for a title and an identifier. Add state adds a state card; select it to edit its Instructions and set its Kind to Human. Drag from one card’s handle to another to draw a transition, and give it the Description the agent reads when it chooses one. See workflows and the editor.
• With the design agent. AI in the top bar opens the Design agent panel; describe the workflow and it writes the draft. See the design agent.

Every edit is saved to the environment’s draft as you make it.

Start a session

On the canvas, the write card has a ▶ beside it, Start session. Press it: the editor switches to its session view with the new session selected, and the agent writes its haiku. A session started here, or with Start session on the Sessions page, is a testing session: it runs the draft as it stands, unpublished edits included.

Decide

When the agent moves to review, the session parks and raises a decision. Open Sessions on the rail: its card sits in the Needs you column. Activate the card to open the decision, with one row per transition naming the state it leads to, and a Note to agent field.

A decision is a hold, not a click: keep the pointer, or Enter or Space, down on Approve: the haiku can stay as it is. for three seconds while the bar fills. The parked turn continues into done. Send back instead returns the session to write.

Look at the session

The Sessions page is a board of four columns, Planned, Needs you, Running and Finished, with a Table view beside it and filters for the workflow, the origin (Production or Testing), tags and the last activity. Activating a card outside Needs you opens the session in its workflow’s session view: a rail of sessions, the graph with the selected turn’s path, and a detail panel with the turn summary, what happened in each state, the variables and the files. In the editor, the mode bubble switches between Show sessions and Back to editor.

Publish and chat

Everything so far ran the draft. Production sessions run a published version, which is what the Chat page and trigger deployments read.

1. In the editor, select write, choose Add trigger in the inspector’s Trigger section, tick Chat and add it, so the Chat page can start the workflow.
2. The top bar’s Publish carries a dot in the attention colour while the draft has unpublished changes. Choose it, describe the change in Publish changes, and Publish. The draft becomes a version, and the button reads Published.
3. Open Chat on the rail, pick the workflow if it asks, and send a message. This chat is a production session that pins the version current when it started, and its decision waits under Needs you like the first one.

Where to go next

• Sessions and decisions: the board, the session view, evidence and notes.
• Triggers: schedules, webhooks and a collection’s events, and the trigger deployments a publish reconciles.
• Evaluations: cases that drive a workflow through its states with mocks and grades.
• Agents and environments: versions, restoring one, and promoting from one environment into its parent.