KoreStack
DaveSteadman/KoreStack
Workspace de IA modular local com agentes, dados e ferramentas de código
Ver no GitHubUm espaço de trabalho de IA local-first construído como um sistema modular de serviços Python cooperativos. Integra um runtime de agente, armazenamento de conversa, camada de dados, editores de documento e código, hub de comunicações externas, redes visuais de agentes, agendamento e subsistemas de teste. Funciona como um único sistema supervisionado, nunca lançando subsistemas isoladamente.
Instalação
npx convez-ai DaveSteadman/KoreStack1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Construir agentes IA que interagem com dados locais e repositórios
- Automatizar fluxos de trabalho com agendamento e integração de comunicações
- Indexar e buscar documentos, código e dados através de uma interface unificada
- Testar e validar comportamentos de agentes em tempo real
Veredito

KoreStack é uma plataforma ambiciosa e bem-arquitetada para quem precisa de um sistema de IA local completo com múltiplos subsistemas integrados. Requer domínio técnico significativo (Python 3.11+, configuração de LLM, gestão de microserviços) e é mais adequado para engenheiros construindo soluções end-to-end do que para adoção rápida.
README
A tradução para o português deste README ainda está na fila.
KoreStack
KoreStack is a local-first AI workspace built from cooperating Python services: an agent runtime, a conversation store, a data layer, document and code editors, an external communications hub, visual agent networks, scheduling, and two test subsystems. It is started, supervised, and used as one system; you never launch a subsystem on its own.

Quick start
Requirements: Python 3.11+, a writable data root, and an Ollama host (or other configured LLM endpoint).
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python .\main.py
Then open the landing page at http://127.0.0.1:29600/. It lists every service with its health, and links to each subsystem UI.
Before the first run review config/korestack_config.json (ports, paths.dataroot) and config/koreagent_config.json (LLM host and models). See config/README.md.
Command line
This is the only place the suite's command line is documented. The root main.py runs KoreStack/main.py.
| Command | Effect |
|---|---|
python .\main.py | Start every enabled service plus the landing page (same as start) |
python .\main.py status | Report the health of the running services |
python .\main.py --dry-run | Print the resolved start plan without launching anything |
python .\main.py --services a,b | Start only the named services (all by default) |
python .\main.py --host H --ui-port P | Override the bind host and landing-page port |
python .\main.py --open-browser | Open the landing page once started |
Valid service names: korechat, koreagent, koredatagateway, koredocs, korecode, korecomms, koreliveweb, korecron, koretest2, koreunittest, koreagentnetwork.
The subsystems
| Subsystem | Port | What it does | How it contributes |
|---|---|---|---|
| KoreStack | 29600 | Supervisor and landing page | Starts, probes, and links every other service; shows Ollama state |
| KoreAgent | 29601 | Agent runtime: sessions, tool loop, skills, slash commands, System One | The brain; every other service that needs an LLM calls its API |
| KoreChat | 29602 | Canonical conversation, message, and event store | Shared thread record for the agent and the comms layer |
| KoreData | 29603 + children | Gateway over feed, library, RAG, reference, graph, and scrape services | One search and retrieval surface for agents and browsers |
| KoreDocs | 29610 | Documents, spreadsheets, and diagrams on the user filesystem | Agent-editable user content, via UI and MCP |
| KoreCode | 29611 | Browser code workspace with indexing and AI edit flows | Coding surface scoped to the repository |
| KoreComms | 29609 | Discord, Gmail, SFTP, and manual message bridges | Isolates external channels from the agent |
| KoreLiveWeb | 29613 | Web search, fetch, navigation, and Wikipedia MCP tools | Live web evidence, kept apart from local data |
| KoreCron | 29615 | Scheduled triggers | Time-based starter for tests and named networks |
| KoreTest2 | 29616 | System tests: prompts and commands run against the live interfaces | Per-build regression of the whole stack |
| KoreUnitTest | 29618 | Python unit tests, one file per test | Per-build regression of internal code |
| KoreAgentNetwork | 29617 | Visual, executable networks of Python, LLM, and Decision blocks | Composable automation that calls other services |
Shared support:
| Folder | Role |
|---|---|
| KoreCommon/ | Path, config, logging, and service helpers imported by every service |
| KoreUI/ | Service-specific templates and static assets; UIElements is the shared shell and top bar |
| config/ | Checked-in suite configuration |
Architecture
KoreStack (29600) supervisor + landing page
| starts / probes /status
+-----------+-----------+-------+-------+-----------+------------+
KoreChat KoreAgent KoreData KoreDocs/Code KoreComms KoreLiveWeb
threads LLM + tools gateway user content channels web tools
^ ^ ^ ^
| | +---------+---- MCP tools, skills
| |
KoreCron -> KoreAgentNetwork runs KoreAgentNetwork -> /api/work-packet
KoreCron -> Test/UnitTest sessions KoreTest2 judge -> /api/work-packet
KoreUnitTest -> runs repo test files
- Control plane: KoreStack resolves config, launches services, and polls each
/status. - Agent runtime: KoreAgent owns orchestration and tools. KoreChat owns durable conversation state. KoreComms owns external channels.
- Data services: KoreData and KoreDocs stay domain services that the agent reaches through MCP and HTTP, never internal libraries.
- LLM models: a chat model plus an Ollama System One decision model (typed questions scored with probabilities). KoreAgent's
/api/work-packetexposes both to the rest of the suite. - Automation and testing: KoreCron triggers time-based work; KoreAgentNetwork builds visual pipelines; KoreTest2 and KoreUnitTest verify each new build.
Shared service contract
/or/ui: browser shell/api/...: JSON API/status: health probe used by KoreStack/mcp: MCP tools, where a service exposes them
Browser pages share the KoreUI/UIElements shell and top bar, which links all suite UIs.
Data layout
| Location | Purpose |
|---|---|
<dataroot>/datacontrol/ | Service-owned state: databases, schedules, logs, test cases and results |
<dataroot>/datauser/ | User content: documents, sheets, diagrams, files that networks and agents read and write |
<dataroot> is paths.dataroot in config/korestack_config.json, overridden by KORE_SUITE_DATAROOT. The repo Data/ folder is a reference layout only.
Troubleshooting
| Problem | What to check |
|---|---|
| Start fails immediately | Activate the venv and rerun pip install -r requirements.txt |
| A service is red on the landing page | python .\main.py --dry-run for ports and enablement, then that service's log in <dataroot>/datacontrol/logs |
| Missing folders or databases | paths.dataroot must point to a writable location |
| Model calls fail | Check config/koreagent_config.json and that the Ollama host and models exist |
| Unstyled pages | KoreUI/UIElements/ must be present |
| One service blocks the rest | Start fewer with --services ... |
Documentation rule
Primary documentation lives in the root and subsystem READMEs. ChangeLog.md records dated changes.
Project-wide intent and architecture are defined in Requirements.md
and Design.md. Architectural changes that alter a documented trust
boundary, service contract, persistent data format, or model policy require an ADR
under docs/adr/.