OpenJCockpit documentation

The knowledge base for OpenJCockpit, the open-source AI Software Factory for governed agentic software development. Start with the path that matches what you want to do. Every page links onwards to related topics.

New here? Read the project README first, then the Overview.

By goal

I want to…	Start here	Then
Understand the platform	Overview	Architecture
Try it locally	Quickstart	Authentication, LLM providers
Build with agents and workflows	Agents and workflows	Spec-driven development, Agents and A2A, Git integration, Spec queue
Configure governance	Policy enforcement	Approval gates, MCP tools, Security considerations
Extend the platform	Agents and A2A	Skills Hub, MCP tools, Local development
Operate and troubleshoot	Troubleshooting	Runbooks, Known limitations, Configuration reference
Contribute	CONTRIBUTING.md	Local development, Testing, Continuous integration
Assess it for my organization	Security considerations	Known limitations, Policy enforcement

All pages

Getting started

• Quickstart: prerequisites, start the stack, first workflow run, stop and reset.
• Authentication: Keycloak, seeded local users, roles, service clients, login theme, realm re-import.

Concepts

• Overview: the AI Software Factory, core concepts, the dashboard, vision vs. current status.
• Architecture: components, technologies, design principles, request flow.
• Agent runtime: the execution plane, its contract with the agent service, security and failure semantics.

Workflows

• Agents and workflows: execution model, default workflows, prompts, groups, export/import, chaining.
• Spec-driven development: specs in project repositories and the spec folder rules.
• Spec queue: sequential spec processing and auto-merge.
• Git integration: workspaces, branches, checkpoints, tickets, credentials, pull requests.

Governance

• Policy enforcement: OPA, policy-guarded tools, guardrails, audit trails.
• Approval gates: human-in-the-loop decisions and the operations runbook.
• Security considerations: local-only credentials, risky postures, hardening starting points.
• Authorization model: roles, endpoint matrix, service identities.
• Security review: production-readiness findings, resolutions and residual risks.

Integrations

• LLM providers: Ollama, LiteLLM, OpenAI, reverts, release notes.
• MCP tools: the Git MCP server, policy-checked tools, workspace isolation.
• Agents and A2A: agent catalogue, configuration-driven agents, A2A.
• Skills Hub: skills and the dev-only marketplace double.

Development

• Local development: requirements, layout, running parts, verification.
• Testing: test layers and the Playwright E2E suite.
• Continuous integration: CI legs, ci-summary, other workflows.

Operations

• Production runbook: Kubernetes and VM/VPS install, upgrade, rollback, backup, monitoring, alerts.
• Release checklist: what must pass before a production release.
• Runbooks: services, volumes, destructive commands, definition-file logging.
• Remote agent runtime: running embabel-agent-runtime on another host.
• Troubleshooting: symptom → cause → fix.
• Known limitations: maturity, accepted risks and follow-ups.
• Dependency management: Renovate.

Reference

• Configuration reference: environment variables and defaults.
• Historical notes: superseded behaviour preserved for traceability.
• Documentation migration map: where each former README section now lives.

Other documentation in the repository

Document	Topic
OpenJCockpit Docs	Published documentation: these pages plus guided tutorials and video scripts.
docs-site (source)	Project overview page: about, spec queue details, illustrated first-run tutorial.
services/embabel-agent-service/docs/agent-integration/OPERATIONS.md	Authoritative operations guide for configuration-driven agents, A2A and git-workspace runs (Dutch).
services/embabel-agent-service/AGENTS.md	Spec-driven workflow rules for agents.
services/embabel-agent-service/README.md	Log keys and the workflow-definition write race statement.
frontend/e2e/README.md	Playwright E2E harness in full detail.
frontend/apps/dashboard/README.md and frontend/libs/*/README.md	Dashboard app and feature libraries.
agents/README.md	Local agent catalogue format.
infrastructure/litellm/README.md	LiteLLM gateway configuration.
infrastructure/keycloak/local-users/README.md	Personal local Keycloak users.
SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, LICENSE, NOTICE	Project policies and licensing.