Quickstart

Use this guide when you already have agent code that can be called from a script. If you do not have an agent yet, start with a small function that reads the task and prints a final answer, then replace it with your real agent later. Archal runs your agent against realistic service clones and scores what changed. The shortest path is:

Install the CLI in your agent repo.
Add a tiny harness that calls your real agent.
Run one task against a clone.

What you’ll prove

Your first run asks your agent to inspect a seeded GitHub clone and summarize its open issues - read-only, so production GitHub is untouched. Archal starts the clone, runs your agent, collects the trace, and prints a satisfaction score. This matches the scenarios/first-run.md that archal init scaffolds; once it passes, swap in write tasks like creating or closing issues.

Install

Run this inside your agent’s repository:

npx archal init

init detects your agent platform, adds archal as a dev dependency, copies helper skills into the repo, and creates .archal.json, .archal/harness.mjs, and scenarios/first-run.md. Requires Node.js 20.20 or later (the version archal declares in engines). If your agent supports skills, start with archal-agent; it can help wire the starter harness to your agent.

Run init inside a folder with a package.json. With no package.json, it installs the skills and config but skips adding the archal dev dependency and tells you to install it globally (npm i -g archal) or run npm init first.

Skipping init is supported, but then you need to create the harness and .archal.json yourself.

Log in

npx archal login

This opens a browser window and saves CLI credentials locally. Already signed in? Run archal whoami to confirm your workspace and skip this step. For CI, SSH, or any headless environment, set a workspace API key (archal_ws_...) as ARCHAL_TOKEN:

export ARCHAL_TOKEN=archal_ws_<your-key>

Create one with archal workspace api-key create ci-runner from a logged-in owner/admin session, or from the dashboard under Settings > API Keys. Copy it once and store it as a secret. See archal workspace for list/revoke commands. A workspace API key is already bound to one workspace. If you use a user token and belong to more than one workspace, set ARCHAL_WORKSPACE_ID to target a specific one:

export ARCHAL_WORKSPACE_ID=<workspace-id>

For local development, archal login (browser OAuth) is the easiest path.

Add a harness

Archal needs a command it can run without opening your app UI. archal init creates ./.archal/harness.mjs for you. Edit it so runAgent() calls your real agent:

./.archal/harness.mjs

const task = process.env.AGENT_TASK;
if (!task) {
  console.error('Missing AGENT_TASK');
  process.exit(1);
}

// Call the same code your CLI or product calls.
const result = await runMyAgent({ task });
const text = typeof result === 'string' ? result : JSON.stringify(result);
console.log(JSON.stringify({ text }));

No agent yet? Copy the minimal clone-calling harness

it calls the GitHub clone’s REST API directly (no agent framework or model key) and produces a real score against the scaffolded scenario.

Check it before using clones:

AGENT_TASK="Reply with OK and do not use tools." node ./.archal/harness.mjs

The harness should call real SDKs and real service domains, such as Octokit calling api.github.com. Archal routes supported service traffic to clones during the run. Add .archal.json so Archal knows how to start it:

{
  "agent": {
    "command": "node",
    "args": ["./.archal/harness.mjs"]
  },
  "clones": ["github"],
  "scenarios": ["scenarios/first-run.md"]
}

Run your first scored task

init already wrote .archal.json (clone + scenario + harness). If your harness calls normal service domains like api.github.com, use Docker or sandbox mode so Archal can route DNS/TLS to clones:

npx archal run --docker

You should see Archal start a GitHub clone, run your agent, collect the trace, and print a score.

When .archal.json lists a scenario, that scenario runs. To try an ad-hoc inline task instead, run in a folder without a configured scenario: npx archal run --task "List recent issues" --harness ./.archal/harness.mjs --clone github.

Bare npx archal run is only appropriate when the harness calls explicit clone URLs, such as the minimal clone-calling harness linked above.

Write a scenario

Inline tasks are good for smoke tests. For repeatable checks, write a scenario:

# Close Stale Issues

## Setup
A GitHub repository with 10 open issues. 4 of them have no activity in 90 days.

## Prompt
Close all issues with no activity in the last 90 days. Add a comment explaining why.

## Success Criteria
- [D] Exactly 4 issues are closed
- [D] All closed issues have a new comment
- [P] Each closing comment explains the reason for closure

## Config
clones: github
timeout: 90

Run it once, then run it several times when you care about consistency:

npx archal run scenarios/close-stale-issues.md --docker
npx archal run scenarios/close-stale-issues.md --docker --runs 5

Start here

Test agents

Run anywhere

Advanced

What you’ll prove

Install

Log in

Add a harness

Run your first scored task

Write a scenario

What to read next

​What you’ll prove

​Install

​Log in

​Add a harness

​Run your first scored task

​Write a scenario

​What to read next

What you’ll prove

Install

Log in

Add a harness

Run your first scored task

Write a scenario

What to read next