Quick Start

This guide will help you run Hercules locally in just a few minutes.

1. Requirements

2. Clone and Build

git clone https://github.com/<owner>/hercules.git
cd hercules
dotnet restore
dotnet build Hercules.slnx

3. Configure the Provider

Open appsettings.json and set the active provider and keys. Example for local Ollama:

{
  "Llm": {
    "Provider": "ollama-local",
    "OllamaLocal": { "Endpoint": "http://localhost:11434/v1", "Model": "llama3.1" }
  }
}

It’s best to pass secrets via environment variables:

export HERCULES_Llm__Provider=yandexgpt
export HERCULES_Llm__YandexGpt__ApiKey=*** 
export HERCULES_Llm__YandexGpt__FolderId=***

4. Run the CLI (primary mode)

dotnet run --project Hercules

Enter a query in the REPL. Repeat the same query 3 times — the agent will propose creating a skill.

5. Run the Web API with Studio (optional)

# Single process — the agent serves the Studio SPA at /ui (ADR-0009)
dotnet run --project Hercules.WebApi

Open http://localhost:8421/ui/.

For UI work with hot reload, run the Studio dev server alongside it:

# Terminal 2 — Studio dev server (port :4330, base path /ui/)
cd src/hercules-studio
npm install
npm run dev

Open http://localhost:4330/ui/.

There is no separate frontend process and no Electron shell. The old Astro frontend (src/hercules-web) is deprecated — see src/hercules-web/DEPRECATED.md.

6. Run the Telegram Bot (optional)

export HERCULES_Telegram__Enabled=true
export HERCULES_Telegram__BotToken=<token from @BotFather>
dotnet run --project Hercules -- --telegram

What’s Next