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 --versionreturns 3.11 or higher -
neo --helpresponds - The
.envfile has at least one API key -
CROWDAR_SKILLS_DIRpoints to a folder withlippia-neo-*subfolders - The test repository has a
qa-stack.yaml - If the plan uses the browser: Node.js installed (or the
-playwrightimage) - If the plan uses Jira or Azure DevOps: environment variables loaded and
mcp_serversinqa-stack.yaml