When the user asks to install OpenRAG, follow this workflow in order.
Initial assessment phase
Before starting installation, check for an existing OpenRAG installation:
- Check if
~/.openrag/tui/.env exists
- If it exists:
- Read the configuration to understand what's already set up
- Check if services are currently running with
docker compose ps for the generated OpenRAG compose file, or by filtering on the compose project/labels instead of docker ps --filter "name=openrag"
- Inform the user about the existing installation
- Ask if they want to:
- Start existing services (if stopped)
- Reconfigure existing installation
- Verify existing installation
- Proceed with fresh installation (will use existing config)
- If no existing installation found, proceed with fresh installation workflow
Primary goals
- Produce a grounded installation spec in
requirements.md
- Break the work into executable tasks in
todo.md
- Implement all tasks that can be completed in the current environment
- Pause for user action when a task requires credentials, configuration choices, or other interactive input
- Verify the installation locally until
http://localhost:3000 launches without startup errors and http://localhost:5001/docs is reachable
- Treat browser onboarding after the app launches as user-owned and outside installation completion
Requirements authoring phase
First, create or update requirements.md using the official OpenRAG installation documentation:
- Use
https://docs.openr.ag/install-options as the source of truth
- Do not hallucinate implementation details that are not supported by the documentation or the local environment
- Prioritize the minimal installation path and the fewest necessary steps
- Organize requirements into logical categories
- Use numbered identifiers in the format
REQ-001, REQ-002, and so on
- Include acceptance criteria for every requirement
- Include requirements covering:
- System prerequisites and resource requirements
- Configuration and security
- Platform compatibility
- Edge cases and troubleshooting considerations
Include the following specific requirement in the spec:
- Non-containerized service:
docling-serve on port 5001
- It is a required bundled Python service
- It is bundled with OpenRAG and managed by
uvx or uv
- It should be automatically started and stopped via
uvx openrag
- It should be available at
http://localhost:5001/docs
- Verification should include either
lsof -i :5001 or curl http://localhost:5001/docs
- Do not immediately flag failure if
http://localhost:5001/docs is not ready right after startup; wait and re-check because docling-serve may come up after the main OpenRAG services
Requirements review phase
After drafting requirements.md:
- Review it for gaps, ambiguities, contradictions, and missing edge cases
- Tighten vague language
- Add missing acceptance criteria where needed
- Update the file before moving to implementation planning
Task planning and execution phase
After requirements.md is stable:
- Read
requirements.md
- Create
todo.md that breaks the work into concrete tasks
- Implement each task that is relevant to the current environment
- For user-interactive tasks, do not guess or fabricate values; instruct the user to complete the step and confirm when done
- Mark tasks complete in
todo.md only after they pass validation
- If troubleshooting partially started OpenRAG services, stop all services before attempting to start them again
CRITICAL: Interactive Terminal Limitation
Most agent shell tools cannot drive interactive terminal applications that require user input. This includes any command that renders a TUI, prompts for passwords, or expects arrow-key navigation.
When the installation reaches the point where uvx openrag needs to be run:
What NOT to do:
- Do NOT attempt to run
uvx openrag through the agent's shell tool expecting to interact with it
- Do NOT try to use background processes for interactive commands
- Do NOT assume you can send input to an already-running interactive terminal
What TO do:
- Explicitly instruct the user to open a NEW terminal window/tab outside the agent's shell
- Provide the exact command to run:
uvx --python 3.13 openrag
- Give step-by-step instructions for what they will see and how to respond:
- First run: Select "Reconfigure" (option 2)
- Set OpenSearch Admin password (MUST be strong)
- Set Langflow Admin password (can autogenerate or manual)
- Accept defaults for other prompts (press 'N' or skip)
- Return to menu and select "Start services" (option 1)
- Wait for "Services are running" message
- Wait for user confirmation that they completed the steps
- After confirmation, verify the installation using non-interactive commands:
- Check container status:
docker ps --filter "name=openrag"
- Verify ports:
lsof -i :3000 and lsof -i :5001
- Test endpoints:
curl http://localhost:3000 and curl http://localhost:5001/docs
Example user instruction format:
The next step requires running an interactive command that I cannot control directly.
Please open a NEW terminal window (separate from this agent session) and run:
uvx --python 3.13 openrag
You will see a menu. Follow these steps:
1. Type '2' and press Enter (Reconfigure)
2. Enter a STRONG OpenSearch Admin password (write it down!)
3. Enter Langflow Admin password (or autogenerate)
4. Press 'N' or skip for other prompts
5. Type '1' and press Enter (Start services)
6. Wait for "Services are running" message
Once complete, come back here and confirm: "Configuration and services started successfully"
User-interactive guidance
When a task requires user input, secret values, or interactive terminal control:
- Tell the user exactly what action they need to take
- Explain how you will verify completion
- Wait for confirmation before proceeding
- Explicitly instruct the user that the OpenSearch password must be strong, defaults can be used for all other values to get started quickly
- ALWAYS instruct users to run
uvx openrag in a separate terminal outside the agent's shell
- Provide explicit step-by-step guidance for what they will see and how to respond
- After user confirms completion, verify using non-interactive commands
Safety and accuracy rules
- Prefer official documentation and observed local state over assumptions
- Do not invent ports, services, commands, configuration keys, or file locations unless verified
- Keep installation steps as simple and minimal as possible
- Use secure defaults and align with OWASP-style handling of secrets and credentials
- Call out platform-specific limitations when they affect installation or verification
- Be explicit that the agent's shell cannot drive interactive TUI applications
- Never attempt to run
uvx openrag interactively through the agent's shell
- Do not treat delayed startup alone as a failure condition when output is still progressing normally
Verification and completion
Before considering the installation complete:
- Verify all completed tasks against the acceptance criteria in
requirements.md
- Confirm required services are running
- Verify
http://localhost:3000 first
- Wait briefly, then verify
docling-serve is reachable at http://localhost:5001/docs
- If OpenRAG services were restarted during troubleshooting, verify they are all healthy after the clean restart
- Only escalate to troubleshooting if repeated checks fail after a reasonable delay or the terminal shows explicit errors
- Consider the installation complete once the app launches without startup errors on
http://localhost:3000 and http://localhost:5001/docs is reachable
- Do not treat provider selection or browser onboarding completion as part of installation completion
Collaboration style
- Be explicit about what is known, what is inferred, and what still needs verification
- Surface ambiguities early and resolve them before implementation
- Keep outputs structured and easy to audit
- Iterate on
requirements.md and todo.md as new validated information is discovered
- Clearly communicate when user action is required in a separate terminal