Skip to content

quick-start.md

Latest commit

 

History

History
229 lines (170 loc) · 7.77 KB

quick-start.md

File metadata and controls

229 lines (170 loc) · 7.77 KB

AgentRail Five-Minute Quick Start

This is the default local/self-hosted onboarding path for the current source-available runtime. It is CLI-first: use agentrail init, start the local API, create or connect a local agent, then use agentrail doctor --agent-id <agentId> as the success gate.

This setup path closes the routing setup work described in AGEA-95 and keeps the integration-doc cleanup from AGEA-93 focused on the current CLI instead of older manual bootstrap commands.

The examples below use the installed agentrail binary.

Prerequisites

  • Node.js 24 or newer.
  • npm.
  • Optional provider credentials for live integrations:
    • GITHUB_TOKEN for GitHub.
    • CIRCLECI_TOKEN for CircleCI.
    • LINEAR_API_KEY for Linear.

1. Install The CLI

npm install -g @agentrail-core/cli

If you do not want a global install, you can use npx @agentrail-core/cli for single commands.

2. Initialize AgentRail

Run the interactive setup:

agentrail init

Or with npx:

npx @agentrail-core/cli init

agentrail init writes local setup state under ~/.agentrail, creates a local operator bootstrap for this machine, and can create the first agent profile and agent env file. Accept the prompt to create the first agent if you want the shortest path to a passing doctor check.

AgentRail also enables anonymous product telemetry by default to improve setup, provider reliability, and agent lifecycle behavior. It uses an anonymous install ID. AgentRail does not send source code, issue text, prompts, logs, env vars, secrets, tokens, diffs, or raw provider payloads. Check or change it with:

agentrail telemetry status
agentrail telemetry off
agentrail telemetry on

If you are running in a non-interactive shell, provide explicit defaults:

agentrail init --mode server --repo /path/to/target-repo --yes

Non-interactive setup writes config and operator state. You can create the agent in step 4.

3. Start The Local API

Keep this running in one terminal:

agentrail server start

For local/self-hosted setups, this runs the AgentRail API, starts provider delivery for configured polling or webhooks, and keeps valid managed local agents from ~/.agentrail/agents/*.env awake.

You normally do not need to run agentrail agent run yourself. Keep it for manual debugging, one-off validation, or cases where you intentionally want to run a single agent outside the server supervisor.

Expected output includes:

Starting AgentRail API.
✓ AgentRail API ready at http://127.0.0.1:3000

4. Create Or Update The First Agent

If agentrail init already created your first agent, skip to doctor.

Otherwise, in a second terminal:

agentrail agent create

The agent wizard creates scoped local agent credentials, writes the managed agent env file, creates or updates the agent profile, and can configure starter routing for the selected repo.

Use --role-template <id> for a built-in or previously installed template. Use --role-template-file <path> when you want to install a custom YAML template for that agent role; AgentRail validates it and stores a copy under ~/.agentrail/agent-role-templates/.

AgentRail creates editable repo maps under ~/.agentrail/repo-maps/ during init and repo add. These maps connect template areas like frontend_source, tests, and ci_configuration to the actual paths in your repo. The starter map is generated deterministically. During interactive setup you can optionally improve it with a local Codex, Claude Code, or Cursor runner. No hosted model API key is needed; AgentRail validates the proposal, shows a summary before saving it, and falls back to the starter map when the local runner is unavailable or uncertain.

Agent role templates are used at run time. When a managed agent starts work, AgentRail combines the selected role template with the repo map for that repository and passes a compact role brief to the runner. The brief points the agent at relevant repo areas and validation expectations, while AgentRail still owns lifecycle actions such as PR creation, CI watching, review handling, and shipping. If a repo map is missing or incomplete, AgentRail still runs the agent and includes a warning in the run context. Run agentrail doctor --agent-id <agentId> to check repo-map coverage.

Use this later to change permissions, routing, or repo allowlists:

agentrail agent update --agent-id agt_example

5. Run Doctor

agentrail doctor --agent-id agt_example

Success means:

  • The local API is reachable.
  • The selected agent env file is usable.
  • The agent profile is active.
  • Routing state exists for the current repo.
  • /tasks/mine?status=in_progress&limit=1 returns assigned work when setup verification work is present.

If doctor fails, fix the reported missing piece before starting a coding agent. Do not treat setup as complete until doctor passes.

6. Connect Providers

Provider connections are optional. Add them when you want live issue intake, CI, review, or outbound mutation behavior.

agentrail provider connect github
agentrail provider connect circleci

# Paste the full CircleCI project slug when prompted:
# circleci/<org-id>/<project-id>
agentrail provider connect linear

Provider setup stores secrets locally and masks prompt input. Environment variables are still supported for CI/non-interactive automation. Each provider connect command ends with readiness checks, applies safe local fixes when it can, and prints exact next steps for anything only the provider account or repo owner can change. provider test <provider> runs the same readiness check as provider doctor <provider>, so a passing test means the provider is ready for AgentRail's lifecycle, not merely that a token exists. GitHub setup also asks whether AgentRail should wait for PR review before shipping: follow GitHub rules, always require approval for AgentRail PRs, or do not require approval once CI is green. Explicit requested changes still block ship until the agent fixes them.

CircleCI setup verifies project access, checks the repo config file, and configures how AgentRail will obtain pipelines for AgentRail branches. If .circleci/config.yml is missing and AgentRail can infer a safe starter Node workflow, the connect command creates it. If automatic CircleCI branch builds are not available, AgentRail configures the CircleCI pipeline-run API when the token can access a pipeline definition. If CircleCI settings cannot be fixed locally, setup reports the exact blocker.

Use the readiness commands before calling setup done:

agentrail provider status
agentrail provider doctor

After connecting Linear, import an issue:

agentrail linear import ENG-123

Imported Linear and GitHub provider tasks go through the routing engine. Missing routing configuration fails closed instead of creating hidden unassigned work. When AgentRail cannot find a suitable agent, the task stays waiting and the routing explanation suggests updating an existing agent or creating a new one from a likely role template. After agentrail agent create or agentrail agent update, AgentRail retries those waiting tasks automatically.

7. Start A Coding Agent

Use the generated agent id when manually launching a runner. The exact id is printed by agentrail agent create.

Example:

agentrail agent run --agent-id agt_example --once

The shared runner guidance lives in agent recipes.

Advanced Manual Lifecycle Calls

Manual HTTP and API-key examples are developer reference material, not the recommended onboarding path. See the SDK guide for TypeScript and Python client usage, and the developer guide for raw curl calls and lower-level API details.