Skip to main content
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:
  1. Install the CLI in your agent repo.
  2. Add a tiny harness that calls your real agent.
  3. 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 onboard; 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_...). Workspace keys are bound to one workspace, do not expire when a team member leaves, and are the recommended auth for CI: 
export ARCHAL_TOKEN=archal_ws_<your-key>
Create via CLI (requires owner or admin role): 
archal workspace api-key create ci-runner --scope sessions:write --scope workspaces:read
Or from the dashboard: Settings > API Keys > Create Key. Recommended scopes for CI: sessions:read, sessions:write, workspaces:read. Workspace keys are already bound to a workspace, so ARCHAL_WORKSPACE_ID is usually unnecessary. If you set it and it targets a different workspace, the request fails with workspace_key_scope_mismatch. Workspace keys are runtime and CI credentials, not governance credentials. They can run clones, upload and read traces, and read usage for their bound workspace. They cannot manage workspace API keys or audit events. Use an owner/admin user credential, either archal login or a dashboard-issued user API key, for workspace administration. For local development, archal login (browser OAuth) is the easiest path. You can also set a personal token (arc_...) from the dashboard tokens page: 
export ARCHAL_TOKEN=arc_<your-personal-token>

​
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), so a bare run is all you need: 
npx archal run
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.
The command above runs your harness against a hosted clone session - which works when your harness calls the clone URL directly (as the minimal example does). To transparently route unmodified SDKs pointed at real domains like api.github.com, add sandbox or Docker mode (--sandbox, or --docker with a Dockerfile): only those give Archal the DNS/TLS control that bare runs can’t.

​
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
npx archal run scenarios/close-stale-issues.md --runs 5