Getting started: run AI SprintFlow on your machine#

This gets the console running locally in about ten minutes, then connects it to your Jira, your code host and Claude so you can run a first story as a dry run (nothing is pushed). Every command here was run on a clean machine.

On Windows or macOS without Python, use the desktop installer instead: see installers.md.

1. What you need#

2. Install#

unzip ai-sprintflow.zip && cd ai-sprintflow
python3 -m venv .venv && source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install --upgrade "pip>=26.2"
pip install -e ".[console]"                                   # add ,scale,otel for PostgreSQL/S3/tracing
sprintflow --version                                          # 1.0.0

3. Start the console#

mkdir -p secrets
sprintflow console init-key > secrets/console_key && chmod 600 secrets/console_key   # back this file up
export SPRINTFLOW_CONSOLE_KEY_FILE=$PWD/secrets/console_key
export SPRINTFLOW_CONSOLE_DIR=$PWD/data/console SPRINTFLOW_RUNS_DIR=$PWD/data/runs

sprintflow console user add <your-name> --role admin          # prompts for a password (12+ characters)
sprintflow console serve --host 127.0.0.1 --port 8700 --insecure-http

Open http://127.0.0.1:8700 and sign in. --insecure-http allows the session cookie over plain HTTP and is only for your own machine; every shared installation runs behind HTTPS (see deployment.md).

Without a license key AI SprintFlow runs on a 7-day free trial with up to 5 seats (License page, or sprintflow license status).

4. Connect Jira, your code host and an AI model#

In the console, Connections:

1. Jira — site URL, the bot account's email and API token → Test connection.
2. Source host — provider, repository (e.g. payroll/cph), URL for self-hosted GitLab, token → Test connection.
3. AI model — pick the provider, then → Test connection: - Claude (Anthropic, Amazon Bedrock, Google Vertex AI): an API key or cloud credentials, or Use Claude Code settings.json to reuse what Claude Code on this machine already uses (Bedrock profile and region, Vertex, a gateway, or apiKeyHelper). For Bedrock with AWS SSO, Sign in to AWS runs your configured awsAuthRefresh. - Another cloud model (OpenAI, Azure OpenAI, Google Gemini, Mistral, DeepSeek, Groq, OpenRouter): API key and model. Set the prices under Advanced so the cost caps are right (unknown models are priced like the most expensive Claude model until you do). - A model on your own hardware (Ollama, LM Studio, vLLM, or any OpenAI-compatible server such as LocalAI or llama.cpp): the server's address and model; no key, no per-token cost, nothing leaves your network. With Docker: docker compose --profile local-ai up -d, docker compose exec ollama ollama pull qwen3-coder, then provider Local: Ollama, address http://ollama:11434/v1. A server on the Docker host: http://host.docker.internal:<port>/v1. Test connection lists the models the server offers.

SprintFlow's steps are tuned for Claude. Other models work through the same tools; choose one with tool (function) calling and strong coding ability. Small local models may need more fix rounds or stop early.

Health now shows Ready to run tickets when everything required is in place.

Then Settings → General → Shadow mode: on. While it is on, nothing leaves AI SprintFlow — no push, no pull request, no Jira comment or status change — so you can try it on real stories safely.

5. Run your first story#

Runs → New run, enter a story key (e.g. PAY-123), keep Dry run ticked, Start run. Watch the stages on the run page: Prepare → Baseline → Understand → Plan → Implement → Verify → Review → (Proof) → Publish. When it finishes, the Changes tab has the diff and Report explains what was done and why. In shadow mode or dry run the result is a patch file instead of a pull request.

Before your first run, a readiness check against the real systems catches permission problems early:

sprintflow pilot check --from-console --issue PAY-123 --baseline     # writes pilot-report.md

6. Command-line only (no console)#

Everything also works from a YAML file, e.g. for a CI job:

cp examples/sprintflow.yml sprintflow.yml       # fully commented; point the ${file:...} secrets at real files
sprintflow validate-config                      # names anything missing
sprintflow pilot check --issue PAY-123 --baseline
sprintflow run PAY-123 --dry-run
sprintflow status                               # recent runs

Repository-specific settings (commands, coding rules, prompts, components) go in .sprintflow/config.yml in the repository itself; see examples/team-knowledge/.sprintflow/. Most repositories need none: the stack, or the repository's own CI configuration, tells AI SprintFlow how to build and test.

7. Optional: the production pieces, locally#

# Build and test in throwaway containers instead of on your machine:
#   Settings → Sandbox → runtime: docker   (Docker or Podman must be installed)

# PostgreSQL + a separate worker, like production:
pip install -e ".[console,scale]"
docker run -d --name sf-pg -e POSTGRES_USER=sprintflow -e POSTGRES_PASSWORD=sprintflow -p 5432:5432 postgres:16
export SPRINTFLOW_DATABASE_URL=postgresql+psycopg://sprintflow:sprintflow@localhost:5432/sprintflow
#   Settings → Storage & workers → execution: queue, then in a second terminal:
sprintflow worker --from-console

8. Run the test suite#

pip install -e ".[dev,console,scale,otel]"
pytest -q

Browser tests run when Chromium, Node and ffmpeg are available (SPRINTFLOW_TEST_CHROMIUM=/path/to/chromium), and PostgreSQL tests when SPRINTFLOW_TEST_PG points at a test database; otherwise they are skipped, not failed.

Troubleshooting#