Skip to content

Requirements and installation

You can run the engine in three ways. Choose the one that fits your case:

Way When to use it What you need
Local Try out a plan, write a new one, debug Python, the engine repo, and the skills repo (see point 1)
Docker Run it just like in CI, without installing Python Docker (see point 2)
CI Have it run on its own in response to a repository event The pipeline configuration (see point 3)

1. Running it on your computer

1.1 What needs to be installed

Requirement Version What for
Python 3.11 or higher The engine is written in Python
Git Any recent version Cloning the repositories
Node.js 20 or higher Only if the plan uses the browser (tools: [browser]) or runs a Playwright suite
uv (uvx) Any recent version Only if the project uses Jira: the Jira MCP is launched with uvx mcp-atlassian
An API key Anthropic or OpenAI The models the plan uses

1.2 Repositories

The engine doesn't include the skills: it reads them from a folder. The simplest approach is to clone both repositories side by side:

mis-repos/
├── crowdar-engine-mvp/     ← the engine
├── neo-releases/           ← the skills (the engine looks for them in ../neo-releases/skills)
└── mi-proyecto/            ← the test repository, with its qa-stack.yaml

1.3 Installation

From the crowdar-engine-mvp folder:

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
copy .env.example .env
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env

To check that it was installed:

neo --help

1.4 The .env file

The engine reads its configuration from environment variables, or from a .env file in the folder you run it from. The .env file is in .gitignore: it is never committed.

Variable Required What for
ANTHROPIC_API_KEY If the plan uses anthropic/... models Calling Claude
OPENAI_API_KEY If the plan uses openai/... models Calling GPT
CROWDAR_SKILLS_DIR No (default ../neo-releases/skills) Where the skills are
CROWDAR_ANTHROPIC_MODEL No Anthropic model that Model 2 uses for classifying, if --model isn't passed
CROWDAR_OPENAI_MODEL No Same, for OpenAI

Example:

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
CROWDAR_SKILLS_DIR=../neo-releases/skills

Spaces and line breaks in the keys

If you paste an API key with a space or a line break at the end (this happens often in PowerShell), the engine cleans it up automatically when it starts. You don't need to edit it by hand.

1.5 The test repository

The engine works inside the test repository folder you point it to with --workspace. That folder must contain:

File What for How it is generated
qa-stack.yaml Tells the engine which framework and which CI the project uses, where the tests, plans, and reports go, and which MCP servers to launch With the lippia-neo-bootstrap-stack skill
.env.tests (or another one, depending on paths.env_file) URL and credentials of the app under test Created by the bootstrap; you fill it in by hand
plans/*.yaml The plans that will be run Copied from the engine repo or written by you (see Anatomy of a plan)

1.6 If the plan uses Jira or Azure DevOps

Outside Claude Code, .mcp.json is not used. The engine launches the MCP servers with the commands in the mcp_servers section of qa-stack.yaml, and it takes the credentials from the process's environment variables:

# qa-stack.yaml (no credentials: those go in the environment)
mcp_servers:
  jira:
    command: uvx
    args: [mcp-atlassian]
  azure-devops:
    command: npx
    args: ["-y", "@tiberriver256/mcp-server-azure-devops"]
Provider Environment variables
Jira JIRA_URL, JIRA_USERNAME, JIRA_API_TOKEN (and CONFLUENCE_* if applicable)
Azure DevOps AZURE_DEVOPS_ORG_URL, AZURE_DEVOPS_AUTH_METHOD (pat), AZURE_DEVOPS_PAT, AZURE_DEVOPS_DEFAULT_PROJECT (optional)

To save them permanently on your computer, see Requirements and setup.


2. Running it with Docker

The engine is published as an image in Crowdar's GitLab Container Registry. There are two variants:

Image What it includes When to use it
crowdar-engine-mvp:latest The engine (Python 3.11), git, and uv Plans that only reason about files (no browser)
crowdar-engine-mvp:latest-playwright All of the above + Node.js 22 + the Playwright MCP browser Plans that explore the app (tools: [browser]) or run a Playwright suite

The image includes only the engine: no skills, no plans, no credentials. You pass those three things in when you run it:

docker run --rm \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -e CROWDAR_SKILLS_DIR=/skills/skills \
  -v "$PWD/../neo-releases:/skills:ro" \
  -v "$PWD:/work" -w /work \
  <registry>/lippia/products/neo/crowdar-engine-mvp:latest \
  run plans/feature-new-end-to-end.yaml --input-file input.json --workspace /work

Pin the image version

latest changes with every merge to the engine's main branch. For reproducible executions, use a fixed tag (for example c4cd2740-playwright, the one the CI templates use today).


3. Running it in CI

In CI you don't need to install anything: the job uses the engine image, clones the skills, and runs the plan. The pipeline files are generated by the lippia-neo-ci-bootstrap skill. All the details (variables, labels, differences between platforms) are in Set up CI.

Platform support

The neo event and neo report commands (reading the MR/PR event and commenting the result) currently support GitLab and GitHub. Bitbucket and Jenkins don't have a CI adapter in the engine.


4. Quick checklist

  • python --version returns 3.11 or higher
  • neo --help responds
  • The .env file has at least one API key
  • CROWDAR_SKILLS_DIR points to a folder with lippia-neo-* subfolders
  • The test repository has a qa-stack.yaml
  • If the plan uses the browser: Node.js installed (or the -playwright image)
  • If the plan uses Jira or Azure DevOps: environment variables loaded and mcp_servers in qa-stack.yaml