Skip to main content
Ask your coding agent to inspect the host, install RELAI, connect the right integration, and guide you through sign-in. Each step also shows the exact CLI commands in a Terminal tab.

​
Set up RELAI

Open your coding agent in the root of the agent repository, then paste:

Follow https://cli-docs.relai.ai/installation to check this machine, install and set up RELAI for this coding agent, and guide me through browser sign-in. Keep provider keys out of chat, stop before project initialization, and tell me when I need to restart or reload this coding agent.

The agent should explain missing prerequisites, pause for any required approval or browser step, and report the active account and workspace when setup succeeds.
For terminal-only setup, run relai setup without --agent. relai setup --agent <host> installs the bundled guidance for that host as part of setup. Restart Codex or Cursor, run /reload-plugins in Claude Code, or start a new interactive Copilot session before checking for RELAI skills. Use relai plugins install later only to add or refresh host integrations.

​
Supported platforms

​
Host prerequisites

Your coding agent checks these tools before initialization and explains any missing dependency:
  • curl to run the standalone installer
  • Git and a project repository with at least one commit
  • Bash on macOS/Linux
  • uv to launch the CLI-pinned Harbor runtime
  • Docker with the Compose plugin and a running daemon that can run Linux containers
Optional: GitHub CLIInstall and authenticate gh only when you want Agent Optimizer to open pull requests. It is not required for local optimization with --no-pr.

​
Container runtimes

RELAI works with Docker-compatible daemons: Docker Desktop, Docker Engine, Colima, Lima, OrbStack, and Rancher Desktop (dockerd engine). Podman is not supported. VM-based runtimes such as Colima and Lima share only your home directory by default, so keep the project under it.
  • gh authenticated with gh auth login when you want the optimizer to open a GitHub pull request.
  • Docker BuildKit, so that docker buildx version succeeds. Image rebuilds use it to reuse downloaded packages, and installing from private registries with install secrets requires it. Docker Desktop includes it; on Linux, install the docker-buildx-plugin package from Docker’s repository or your distribution’s docker-buildx package.

​
Sign in to RELAI

Setup uses OAuth device authorization. Your coding agent will present the verification link and short code, then wait while you complete the browser step. On SSH or a browserless machine, open the link on another device.
Protect the machine-level credential filesRELAI stores OAuth access and refresh tokens as plaintext in the machine-user file ~/.relai/credentials.json. It restricts that file to the current user—mode 0600 on Unix and a user-only access control list on Windows—but anyone who can read files as your operating-system user can read the tokens. Never share or commit this file. Keep ~/.relai/config.toml private too, because it stores machine preferences and can contain an API key.
RELAI authentication and your model-provider key are separate credentials. OAuth tokens do not appear in project configuration or CLI logs.

​
Keep provider keys outside chat

.relai/simulator.env

Add the required KEY=value entries, such as OPENAI_API_KEY=… or ANTHROPIC_API_KEY=…, directly on your machine. RELAI loads this ignored local file automatically; never paste its contents into chat.

Shell or secret store

Use your shell environment or CI secret manager. Never paste a secret into a coding-agent prompt, commit it, or include it in a copied command.
Know which steps repeatInstall and setup are machine-level steps you normally complete once. Initialization creates the project runtime and can be rerun later to repair or regenerate it. Creating tests, simulating, and optimizing form the learning loop you repeat.

​
Before project initialization

Confirm that your project has a runnable local agent boundary and repository-visible dependency metadata. Host virtual environments and node_modules are not mounted into the Linux task image. Check compatibility or manage coding-agent plugins.

Machine ready?

Use the sample agent for the easiest first learning loop, or initialize your own repository.