JARVIS Release (Stack Distribution)

JARVIS_Release is the version-pinned, runnable stack distribution for JARVIS (ARP spec/v1). It ships a lock file + Docker Compose setup that brings up a full local stack with sensible defaults.

What this repo ships

Core spec-facing services:

• Run Gateway
• Run Coordinator
• Atomic Executor
• Composite Executor
• Node Registry
• Selection Service
• PDP

Internal JARVIS services:

• Run Store
• Event Stream
• Artifact Store

Local dev STS (default profile):

• Keycloak (dev-secure-keycloak)

Version pinning

• stack.lock.json is the stack source of truth (component versions, node pack versions, helper libs).
• pyproject.toml pins the same component versions for the arp-jarvis meta package.

Decision: Mode B / per-service GHCR images. Each JARVIS component repo publishes a GHCR image on vX.Y.Z tags. This repo consumes those images via Docker Compose and pins the references in stack.lock.json.

Quickstart (CLI-first, dev-secure-keycloak)

1. Copy the env template:

Default (dev-secure-keycloak):

cp compose/.env.example compose/.env.local

Dev-insecure (no inbound JWT):

cp compose/.env.example.insecure compose/.env.local

Optional (dev-insecure, macOS/Linux or WSL) one-command bring-up:

bash ./start_dev.sh \
  --llm-api-key "<your_openai_api_key>" \
  --llm-chat-model "gpt-4.1-mini"

2. Configure the LLM (required for Selection Service + Composite Executor):

• Set ARP_LLM_API_KEY and ARP_LLM_CHAT_MODEL in compose/.env.local.
• OpenAI is the default profile; ARP_LLM_PROFILE=openai is optional.
• For offline tests, you can opt into ARP_LLM_PROFILE=dev-mock (not the default).

3. Install the meta CLI:

python3 -m pip install -e .
arp-jarvis versions

This installs the arp-jarvis CLI version from your local checkout, while the Docker images remain pinned separately via STACK_VERSION in compose/.env.local and stack.lock.json.

4. Bring up the stack and verify wiring:

arp-jarvis stack pull
arp-jarvis stack up -d
arp-jarvis doctor

5. If using dev-secure-keycloak (default), log in once:

arp-jarvis auth login

This is a browser/device flow. The CLI never asks for your password directly. For the default local realm, a dev user is pre-seeded; the credentials are only for the Keycloak login page during the browser step.

6. Start a run:

arp-jarvis runs start --goal "Generate a UUID, then return it."

Notes:

• Keycloak is exposed on http://localhost:8080 (issuer default).
• Run Gateway is exposed on 8081. Run Coordinator is exposed on 8082 (configure via RUN_COORDINATOR_HOST_PORT).
• If you change KEYCLOAK_HOST_PORT, update ARP_AUTH_ISSUER in compose/profiles/dev-secure-keycloak.env.
• dev-insecure disables inbound JWT checks but still runs Keycloak for service-to-service token exchange.
• Node Registry runs with ARP_AUTH_MODE=optional to allow Selection Service calls (current Selection client does not attach bearer tokens).

Docker Compose fallback (no CLI)

docker compose --env-file compose/.env.local -f compose/docker-compose.yml up -d
curl -s http://localhost:8081/v1/health

Stack profiles

Set STACK_PROFILE in compose/.env.local to one of:

• dev-secure-keycloak (default)
• dev-insecure
• enterprise (template only)

Meta CLI (arp-jarvis)

Convenience commands for interacting with the running stack:

arp-jarvis doctor
arp-jarvis auth login
arp-jarvis nodes list
arp-jarvis runs start --goal "Generate a UUID, then return it."

Compose wrapper (does not replace docker compose):

arp-jarvis stack up -d --print-command

You can also invoke component CLIs via arp-jarvis:

arp-jarvis run-gateway --help
arp-jarvis run-coordinator --help
arp-jarvis atomic-executor --help

Repo layout

JARVIS_Release/
  stack.lock.json
  compose/
    docker-compose.yml
    .env.example
    profiles/
      dev-secure-keycloak.env
      dev-insecure.env
      enterprise.env
    keycloak/
      realm-arp-dev.json
  assets/ (diagrams, logos)