KUROLABS
QUICKSTART GUIDE

Installing KuroCodeAgent

Follow verified setup instructions to run KuroCode on Windows, Linux, or macOS.

01. System Prerequisites

Python Version
3.10, 3.11, 3.12, 3.13
Tested across active CPython builds
Git Client
Available in PATH
Required for automated rollback checkpoints
Operating System
Windows / Linux / macOS
Windows provides native DPAPI vault

02. Option 1 — Install from PyPI (Recommended)

Fastest

KuroCode is distributed on PyPI with automatic trusted publishing. Simply execute:

terminal 
pip install kurocode

Once installed, launch the terminal REPL simply with:

terminal 
kuro

03. Option 2 — Install from Source (For Contributors)

If you want to modify KuroCode, submit pull requests, or inspect internals:

bash / powershell 
# Clone repository
git clone https://github.com/kurolabs-ai/KuroCodeAgent.git
cd KuroCodeAgent

# Create and activate virtual environment
python -m venv .venv
# On Windows: .venv\Scripts\activate
# On Linux/macOS: source .venv/bin/activate

# Install in editable mode
pip install -e .

# Launch assistant
kuro

04. Provider Configuration

KuroCode requires at least one LLM API key. Choose either the encrypted interactive vault or a local .env file.

OPTION A: ENCRYPTED VAULT (RECOMMENDED)

Keys are encrypted with Windows DPAPI (CryptProtectData) or AES-256 and never stored in plaintext.

kuro
# Inside the running terminal:
/key gemini AIzaSyYourKeyHere
/key groq gsk_YourKeyHere
OPTION B: LOCAL .ENV FILE

Create a .env file in your working directory:

GEMINI_API_KEY=your_gemini_key
GROQ_API_KEY=your_groq_key
KURO_PROVIDER=gemini
KURO_SAFE_MODE=true

05. Verification & Diagnostics

Verify that KuroCodeAgent successfully detects your hardware telemetry and configured providers:

verification commands
/status — Displays active provider, model chain, and Safe Mode status
/system — Tests live CPU, RAM, and disk utilization telemetry
/hub list — Verifies connectivity with Kuro Hub capability store

06. Common Issues & Troubleshooting

'kuro' is not recognized as an internal or external command

Ensure Python's Scripts directory (e.g. ~/.local/bin on Unix or %USERPROFILE%\AppData\Local\Programs\Python\PythonXX\Scripts on Windows) is included in your system's PATH environment variable.

Git checkpoint warning on execution

KuroCode automatically snapshots staged and unstaged changes prior to file modifications. Ensure git is installed and that the working directory is an initialized repository (git init).

HTTP 429 Provider Rate Limit

KuroCode features automatic model cascading and multi-key pool rotation. Add multiple keys with /key <provider> <key> or specify a fallback provider in your .env file.

Read Documentation Report installation issue on GitHub