Skip to main content
For a guided workflow, see the Quickstart. relai init initializes an agent project, generates simulator support, and by default bootstraps EvalsWiki from the repository.
After a successful initialization, the installed RELAI coding-agent skill adds RELAI’s shared proactive workflow policy to existing root AGENTS.md or CLAUDE.md files that lack it, without asking. You can manage it directly with relai policy install or relai policy remove; neither command creates instruction files.
relai init can take a while for larger or more complex agents because RELAI inspects the project and generates a simulator harness for it.

​
Before you run it

Run it from the root of a git-tracked agent repository; init refuses to run from your home directory, whose .relai/config.toml is your user-level config. The project should satisfy the project requirements. Run relai setup first to sign in with OAuth device authorization. Interactive init offers setup before creating a session if the machine is not configured.

​
Options

Interactive runs may ask to run setup when credentials are missing, plus permission to inspect selected project files or install dependencies, agent metadata, and task dependencies. RELAI never commits on your behalf. Full simulator validation must pass before RELAI records agent targets.

​
How initialization works

relai init uses one agentic workflow for any repository language. The CLI creates a Harbor task scaffold, then the init agent inspects selected repository files, reports its resolved dependencies and logical agent targets, adapts the seed, and validates the simulator locally. There is no legacy generation path or feature flag. The initial workflow context includes minimal local environment facts and any readable AGENTS.md and CLAUDE.md files on the repository-root-to-working- directory path. Those files are source-labeled, ordered from broadest to most specific (AGENTS.md before CLAUDE.md in one directory), and collectively limited to 32 KiB. They are untrusted repository guidance: they cannot override RELAI permissions or the workflow’s tool contracts. RELAI does not add a repository snapshot; the agent uses bounded searches and reads for discovery. Common Harbor and dependency-inspection guidance is compiled into the CLI. The agent can inspect bounded repository declarations or source for named integration points, then declare the task’s exact dependency inputs and image setup commands. It generates a project-owned adapter with explicit, behaviorally verified capabilities and native ATIF recording. Repository and dependency reads remain bounded, sensitive paths stay unavailable, and external local dependency roots require approval. Before full init validation installs dependencies or starts Harbor execution, RELAI checks the current static harness. A static failure returns its structured stage and diagnostics without starting the expensive stages; a passing static check proceeds into full validation in the same requested action. When repository evidence needs a local toolchain check, the agent may submit run_command with an exact program, argv, and repository-relative working directory. It runs until it exits or the command’s overall timeout ends it, and long output is returned as its head and tail, so the agent does not start long-running servers, watchers, or interactive programs. auto runs an otherwise permitted command, while ask and accept_edits require approval. This is not an OS sandbox: an approved command can have normal filesystem and network effects. Every Harbor task image must provide python3 for the Python bridge used by the launcher, independently of the project agent’s language. Choose a Python-capable base image or add an explicit project-owned runtime setup command; RELAI does not guess a distribution or add a distribution-specific Python installer. By default, init also bootstraps EvalsWiki. With the auto or accept_edits permission profile, the bootstrap starts in the background while init builds the simulator and records agent targets, and init waits for it afterward. Its output goes to a local log under .relai/.internal/runs/ in a project containing .relai/.internal/layout.json; legacy projects without the marker use .relai/runs/. If the background bootstrap pauses, fails, or is stopped, init continues it in the foreground at that point. With ask, init runs the bootstrap after initialization. The bootstrap records grounded requirements and open questions, then a separate curation pass derives typed risk hypotheses from those requirements, the open questions, and permitted repository evidence. Requirements are behavior expectations RELAI considers grounded enough to use for eval design. Open questions are unresolved ambiguities that should not be treated as requirements yet. Risk hypotheses are falsifiable ideas for agent tests that may reveal current-agent limitations; curation stops when it runs out of high-quality evidence rather than filling a quota. Init curates at most 8 risk hypotheses as a starting set, reusing its own project analysis; relai test discover tops up the risk pool later when it needs more. If Wiki work pauses, continue the same parent workflow with relai init --resume. Use --no-wiki only when Wiki bootstrap will be performed separately; relai test discover requires a completed bootstrap. After init, inspect the curated material with:
Use relai wiki list risks --create-test --risk {id} or relai test discover --risk {id} to test one selected risk. Use relai wiki list requirements --create-test --id {id} or relai test create --requirement {id} to create an agent test from one grounded requirement. When a user can answer an open question, resolve it through RELAI’s Wiki update flow (pass --review to approve the patch first):

​
Harbor runtime

relai init creates the Harbor scaffold under .relai/harbor and records runtime = "harbor" in .relai/config.toml. Harbor runs registered agent tests and CSV benchmark samples through the normal selectors. --harbor-task selects one explicit unregistered task. Agent tests, global evaluators, benchmarks, and optimization use the same Harbor packages. For each agent run, including a resumed run, RELAI creates a fresh sanitized snapshot of the current project source and mounts that snapshot read-only at /workspace. The snapshot omits sensitive paths (including .env and .env.example), .git, .relai, transient Wiki views, and host dependency roots such as .venv and node_modules. Docker never mounts the checkout or nested masks, and host changes after snapshot creation are not reflected in that run. The generated adapter should import or invoke project source from /workspace, while the task image contains the reusable adapter and task-owned scenario, services, evaluator, and dependencies. During a recording run, project instrumentation writes the complete cumulative canonical ATIF-v1.7 document atomically to RELAI_ATIF_TRAJECTORY_PATH; Harbor only passes that path and validates the document. It records each turn’s user input as a user step along with the actual model and tool events, and is inactive when the path is absent so normal application behavior is unchanged. Validation fails when a turn’s user step is missing; relai simulate and relai optimize warn instead and keep running, so repair an older recorder with relai init --restart. Docker builds do not receive the mount, so Dockerfiles must not copy from or install against /workspace. Install toolchains and external dependencies from staged lockfiles in runtime setup, and do not rely on host .venv, node_modules, or other build output. The project’s own install or build steps that need its source, such as local or workspace packages, editable installs, and compilation, run as workspace setup: once per run, before any trial, with network access and the snapshot writable. Trials then mount the prepared snapshot read-only and see everything setup produced. When an install needs a private registry, the generated packaging names its credentials as install secrets; set their values in .relai/simulator.env, where init adds their names, or the environment. They reach the image build and workspace setup only, never an image layer or the trials. The verifier does not receive the project mount; it uses task-image artifacts and the ATIF trajectory or other task-owned outputs. Credentials are never supplied by the mount. Declare required names in the runtime manifest and add persistent local values to .relai/simulator.env, which RELAI loads automatically. Use the process environment for temporary runs or CI, --env-file for an alternate file, or --env for an invocation-specific override. RELAI forwards every value from env files and --env to the Harbor agent phase; from the process environment it forwards only names the manifest declares. An existing copied source in an older Harbor scaffold is preserved, but a new adapter must not select it or place it ahead of /workspace, where it could shadow the original project source. After updating the adapter, set only command in the [agent] table of .relai/harbor/agent.toml. The generated launcher starts it once per trial and uses one NDJSON request/response frame per turn; Harbor validates canonical ATIF rather than config migration markers before it runs. RELAI does not rewrite or remove copied source. Adapters using the retired RELAI transcript or stdout tool_calls contract must be regenerated with relai init --restart; restart automatically restores the CLI-owned bridge, launcher, task copies, and trajectory verifier. Configure a separate leaf project adapter. Stdout carries the required control assistant_message and the adapter owns ATIF.

​
Repository files

RELAI keeps Harbor tasks, evaluators, benchmarks, and .relai/evals-wiki as ordinary repository files. It adds targeted ignore rules for credentials, simulator environment files, runs, caches, sessions, locks, and optimizer state.

​
Permissions

Permissions combine a global profile, optional global path rules, and optional repository path rules. They control which workspace paths RELAI may read or write; path protection is enforced even when a profile would otherwise allow an action. The global selected profile and optional global rules live in ~/.relai/config.toml. When no profile exists, relai setup materializes profile = "auto"; it preserves an explicit existing profile and rules. The repository .relai/config.toml can contain only path rules. It cannot select a profile. For compatibility, a legacy profile = "default" in a repository config is ignored; remove it when you update that file. Other repository profiles are invalid. The only profiles are: Use --permissions {auto|accept_edits|ask} on an agentic command to override the global profile for that run. The precedence is the command-line override, then the profile in ~/.relai/config.toml, then built-in auto. Every resumed invocation resolves that precedence again; repeat --permissions with --resume when the same override is required. Under ask, session-scoped approval or denial choices persist in the resumable session, but they do not pin the profile for later invocations. Routine backend metadata and sync operations are not command execution. The shared option is available on init; agent test create, update, suggestion generate, and suggestion accept; benchmark register and update; evaluator create and update; and wiki bootstrap, wiki update, and wiki reconcile. For example, configure a global profile and global rules in ~/.relai/config.toml:
Then add repository-specific restrictions in .relai/config.toml; do not add [permissions] profile there:
Rules use Gitignore-style patterns. An omitted allow permits the whole workspace; a present allow is a complete allowlist, and allow = [] permits no paths. Global and repository allowlists intersect, while their deny rules are combined. Deny rules and hard protections always win, so repository rules can further restrict global access but cannot weaken it. RELAI always blocks .env and .env.* files (except that workflow agents may read, but never write or mount, a .env.example template), .npmrc, .pypirc, .netrc, known credential and SSH key filenames, .pem, .key, .p12, and .pfx files, cloud credential directories, paths containing service-account, and .relai/config.toml or .relai/simulator.env. Other secret-bearing paths should be added to permissions.read.deny. An agent can never write .relai/config.toml, so it cannot change its own permissions. After validation, RELAI asks you to select any discovered logical targets, records the selected target-to-agent mappings, and registers them with the backend. RELAI never commits on your behalf: it reports the generated .gitignore and .relai/ files and prints the git add and git commit commands to run if you want to track them.

​
Pause, resume, or restart

Initialization checkpoints its progress in .relai/init-session.json whenever it needs an answer, approval, an external action, or recovery from an interruption. Run relai init --resume to continue the same session. Resume restores earlier model and tool progress, permission decisions, validation progress, selected options, and completed phases; it cannot be combined with --agent-target. If a model stops before validation, RELAI runs the workflow’s deterministic validation once. A failed check becomes repair feedback in the same bounded session; a missing external prerequisite remains paused for --resume. After an external action, resume checks the current state. The CLI workflow agent can repair image errors within the remaining timeout. If user action or approval is still needed, RELAI shows the current reason. For example, after an API key is fixed, a missing Python interpreter is reported as an image error. If full validation fails with the same failure three times in a row, RELAI stops repairing and pauses as a stalled repair. The pause shows the latest failure, its evidence, and whether you likely need to change the project, task, or host, or report a RELAI CLI issue. relai init --resume re-runs validation with a fresh count, so resuming without a change will likely stall again. Before initialization completes, a resumed init revalidates the current Harbor runtime. Target selections and any pending name-conflict answer remain in the session. If init reaches its timeout, it saves the session and exits with status 124; run relai init --resume to continue, optionally with a larger --timeout. Run relai init --restart to discard an unfinished checkpoint and begin again. Restart does not roll back generated files or source changes; inspect the existing diff before starting over. If an unfinished session exists, interactive init offers to resume, restart, or cancel; non-interactive init requires one of those flags. A completed init removes the checkpoint. Each session also writes a metadata-only diagnostic record under .relai/.internal/runs/. It contains action names, statuses, request IDs, timings, and token usage, but not prompts, source bodies, diffs, or raw command output.

​
Agent targets

Repositories with several logical agents can register each one as a named agent target. During interactive initialization, RELAI shows the discovered targets with their code entrypoint and, when available, runtime selector. Use Space to toggle each target and Enter to confirm the selection. RELAI creates one backend agent for every selected target and records the target-to-agent mapping in .relai/config.toml. To select targets non-interactively, repeat --agent-target with discovered target names:
When a project has multiple registered targets, commands that create learning environments, benchmarks, or evaluators let interactive users choose one target at a time. In non-interactive runs, pass --agent-target {target} explicitly.

​
What it creates

  • project registration with the RELAI backend.
  • Harbor adapter and smoke-task files under .relai/harbor/.
  • the project runtime under .relai/harbor/runtime/: the validated base image, locked dependencies, runtime setup, adapter, and launcher that later behavioral tests and benchmarks share.
  • the runtime manifest.
  • .relai/simulator.env.example, listing the variable names.
  • local-only .relai/simulator.env with an empty placeholder for each declared variable, so you only fill in values. Init creates it when it pauses for missing values and when it completes, and only appends names an existing file does not mention.
  • a temporary local init checkpoint while initialization is paused or in progress; it is removed after completion.
  • a metadata-only local diagnostic record under .relai/.internal/runs/.
  • an interactive offer, or non-interactive instructions, to commit changed .gitignore and .relai/ files.
As you use RELAI, the other objects live alongside these under .relai/, each created by its own command:
  • .relai/harbor/agent-tests/ for agent tests, from relai test.
  • .relai/harbor/evaluators/ for evaluators, from relai evaluator.
  • .relai/harbor/benchmarks/ for benchmarks, from relai benchmark.
  • .relai/.internal/runs/ for simulation and optimizer run artifacts.

​
Task dependencies and components

Describe the calls and services a task should exercise or replace when creating an agent test. Harbor stores task-local mocks and component descriptors inside the task package. The adapter must preserve real agent behavior and record actual model/tool events; it must not invent trajectory events.

​
Example

​
Project input controls

To keep project files away from RELAI agents, list Gitignore-style patterns in permissions.read.deny in .relai/config.toml. RELAI does not read a .relaiignore file.
The permissions rules apply to project files only. RELAI-managed state under .relai/ follows the selected profile and built-in secret protections. Use a root-level .relai-snapshotignore file when a file should remain available in the optimizer worktree at runtime but should not be sent as optimizer source context. This is useful for bulky fixtures, logs, examples, visualizer artifacts, or reference material that the agent can import or read locally but the optimizer does not need to inspect. relai optimize captures at most 8 MiB of source text, so projects with large benchmark corpora or generated references should use snapshot-ignore patterns to keep the optimizer context focused.
.relai-snapshotignore uses Gitignore-style patterns, but it only affects relai optimize code snapshots. Matching files are not deleted from the optimizer worktree. Required RELAI-managed inputs, such as active simulator harness files and manifests, remain protected by RELAI’s built-in snapshot rules even when a broad snapshot-ignore pattern matches them.

​
Common failures

  • not running inside a git repository.
  • missing RELAI credentials.
  • missing required local tools.
  • init model or local validation failure.
  • an action that requires approval in a non-interactive terminal.
  • an unfinished init session; resume it with relai init --resume or discard it with relai init --restart.
  • missing runtime environment values required by the smoke test.
  • tracked generated paths already have local changes.
  • the project cannot expose a runnable local simulator surface.
This command writes files. Review generated files before committing them.

​
Legacy SDK projects

Legacy SDK configurations and unfinished SDK init sessions are unsupported. Preserve existing artifacts and run evidence. If .relai/config.toml explicitly sets [simulator] runtime = "sdk", change it to "harbor" (or remove that retired setting), then run relai init --restart. Restart explicitly discards the old init checkpoint and generates Harbor scaffolding; it does not convert or delete legacy artifacts. Recreate agent tests, evaluators, and benchmarks with their owning commands. Alternatively, initialize a fresh checkout with relai init. --resume cannot continue an SDK init session.