Quick start¶
This runs the Arnold backend, the UI, a local review runner and Aerospike on your machine.
Requirements¶
| Tool | Version | Notes |
|---|---|---|
| JDK | 17 | Builds the backend jar |
| Maven | 3.9+ | |
| Docker or Podman | with Compose | Podman needs 8 GB+ free disk in its VM |
1. Build and start¶
git clone https://github.com/PhonePe/arnold.git && cd arnold
mvn -f arnold-backend/pom.xml -DskipTests package
cp deploy/.env.example .env
docker compose up --build
Open http://localhost:3000.
The backend takes about 20 seconds to start. Until it is ready the UI shows Arnold is starting and retries by
itself. A Set up Arnold guide then walks you through whatever .env configures: connecting GitHub or GitLab,
installing the GitHub App on repositories, and connecting Copilot if it is enabled.
Development authentication
The quick start runs with development authentication: there is no sign-in and every request acts as a local superadmin. Never expose this setup to a network. See Sign-in.
2. Connect a forge and a model¶
Arnold is not useful until it can see your code and call a model. Edit .env:
Create a GitHub App (about 5 minutes, see GitHub App), then:
Create a GitLab OAuth application with the api scope (see GitLab), then:
Add an OpenAI-compatible endpoint for reviews (see LLM and harnesses):
CLIO_HARNESS=opencode
CLIO_LLM_BASE_URL=https://api.openai.com/v1
CLIO_LLM_API_KEY=sk-...
OPENCODE_MODELS_URL=https://api.openai.com/v1
OPENCODE_API_KEY=sk-...
Recreate the services that read .env:
Then open Settings → Connected accounts and connect GitHub or GitLab.
3. Review something¶
- Click Run Analysis, paste a pull request or merge request URL, and click Fetch details.
- Optionally add an RFC link, Jira tickets or extra context.
- Pick up to three review personas, a harness and a model.
- Start. Follow progress in Analysis History. Findings appear as inline comments on the PR/MR and in the Arnold review workspace.
Where your pull requests come from¶
Arnold imports every open pull request from repositories where its GitHub App is installed, and every open merge
request visible to GITLAB_SERVICE_TOKEN (optionally limited by ARNOLD_GITLAB_SYNC_GROUPS). The first import starts
about 30 seconds after boot and repeats every ARNOLD_REPOSITORY_SYNC_INTERVAL_SECONDS (default 300). They appear
under Merge Requests → All open.
Forges cannot reach webhooks on localhost, so locally this periodic import keeps Arnold current. See
Webhooks and sync to forward webhooks for instant updates.
Day-to-day commands¶
docker compose up -d --force-recreate server runner # after editing .env
docker compose up -d --build ui # after UI code or config changes
mvn -f arnold-backend/pom.xml -DskipTests package \
&& docker compose up -d --build server # after backend code changes
docker compose --profile analytics up -d # add Elasticsearch (set ELASTIC_ENABLED=true in .env)
docker compose down # stop (data is kept)
docker compose down -v # stop and wipe all data
| Service | URL / port | Logs |
|---|---|---|
| UI | http://localhost:3000 | docker compose logs -f ui |
| Backend API | http://localhost:8090 | docker compose logs -f server |
| Backend admin (health, metrics) | http://localhost:8091 | |
| Runner | none (polls the backend) | docker compose logs -f runner |
Data (users, connections, runs) lives in the aerospike-data volume and survives restarts.
Next¶
- Production deployment: run the released images with real sign-in.
- Architecture: how the parts talk to each other.
- Setup: everything you can configure.
- Troubleshooting: if something does not come up.