Skip to content
Agirunner

Quick Start

This is the shortest complete path from a fresh clone to a running workflow.

Open the dashboard at http://localhost:3000 after startup. The first admin login key is the DEFAULT_ADMIN_API_KEY value from your agirunner/.env file. If you copied .env.example to .env, replace the placeholder values with generated secrets before sharing the environment with anyone else. The public product stack pulls its runtime image from GHCR, so you do not need a separate runtime checkout for the normal quick-start path.

First Run

Section titled “First Run”

  1. Start the stack

    Terminal window
    git clone https://github.com/agirunner/agirunner
    

    cd agirunner
    cp .env.example .env
    

    printf "JWT_SECRET=%s\nWEBHOOK_ENCRYPTION_KEY=%s\nDEFAULT_ADMIN_API_KEY=ab_admin_def%s\nPLATFORM_SERVICE_API_KEY=ar_service_%s\n" \
      "$(openssl rand -hex 32)" \
      "$(openssl rand -hex 32)" \
      "$(openssl rand -hex 16)" \
      "$(openssl rand -hex 16)"
    

    docker compose up -d

    Paste the generated values into .env, then open the dashboard at http://localhost:3000 and sign in with DEFAULT_ADMIN_API_KEY. PLATFORM_SERVICE_API_KEY is for the internal container-manager path, not for dashboard login.

  2. Connect a model and set the system default

    Go to Platform -> Models, connect a provider, and set the System Default Model. Supported providers today are Anthropic, OpenAI, Google, OpenRouter, Ollama, and vLLM. Without this, workflows can be created but cannot make meaningful progress.

    OpenAI can be configured here with API keys or a subscription-backed sign-in.

    For orchestrator and specialist roles, we currently recommend gpt-5.4 with at least low reasoning, and usually medium, as the best default. Lower-capability or non-reasoning models could reduce planning quality and increase retries or operator intervention.

  3. Import a community playbook

    Go to Work Design -> Playbooks, click Add Community Playbook, and import a playbook from agirunner-playbooks. Start with something focused so the first run is easy to understand.

  4. Launch a workflow and watch it run

    Go to Workflows, click New Workflow, and launch the playbook you just imported. You can also launch directly from the playbook page. Then return to Workflows and watch the workflow move.

What Just Happened

Section titled “What Just Happened”

Behind the UI:

  1. the platform created a workflow and initial activation
  2. the orchestrator planned or routed work
  3. specialist tasks were claimed by the runtime
  4. each task executed in an isolated environment
  5. logs, artifacts, and outcomes streamed back to the platform

That is the core Agirunner loop. You are not just watching a model talk. You are watching a control plane create work and an execution plane perform it.

What To Inspect Next

Section titled “What To Inspect Next”

After the first workflow runs, spend a few minutes looking at:

  • the workflow board, to see how work-item state is represented
  • the live console, to see actual execution evidence
  • the deliverables view, to separate produced outputs from transient logs
  • the needs-action surface, to understand where a human would step in
  • the models and environments pages, to see how platform settings shape later runtime behavior

Next Steps

Section titled “Next Steps”