# Kovanex — Complete Documentation for AI Agents

> Self-hosted DevOps platform. Git + CI/CD + Kanban + Vault + Registry + AI Agents.
> One binary. 4GB RAM. No vendor lock-in. Apache 2.0.

---

## What is Kovanex?

Kovanex is a self-hosted DevOps platform that replaces GitHub + Jenkins + Jira + Vault + Docker Hub with a single Go binary. All communication happens via gRPC — no REST API. AI agents are first-class citizens with the same authentication, API access, and capabilities as human developers.

### Key Numbers

- 16 gRPC services, 162 RPC methods
- 47K lines of Go
- 4GB minimum RAM, 2 Docker containers
- 25MB native desktop app (Go/Gio, not Electron)
- SurrealDB for all storage (no PostgreSQL, no Redis)

---

## Installation

### One-line install

```bash
curl -fsSL https://kovanex.dev/install.sh | bash
```

### Manual install

```bash
mkdir -p /opt/kovanex && cd /opt/kovanex

# docker-compose.yml
cat > docker-compose.yml <<'EOF'
services:
  kovanex:
    image: registry.kovanex.dev/kovanex:latest
    ports:
      - "8080:8080"  # gRPC-Web + PWA
      - "9000:9000"  # gRPC
      - "2222:2222"  # Git SSH
    env_file: .env
    depends_on:
      surrealdb: { condition: service_healthy }
    restart: unless-stopped
  surrealdb:
    image: surrealdb/surrealdb:latest
    command: start --user root --pass root surrealkv://data
    volumes: [surrealdb_data:/data]
    healthcheck:
      test: ["/surreal", "isready"]
    restart: unless-stopped
volumes:
  surrealdb_data:
EOF

# Generate secrets
cat > .env <<EOF
DB_USER=kovanex
DB_PASS=$(openssl rand -hex 16)
JWT_SECRET=$(openssl rand -hex 32)
VAULT_UNSEAL_KEY=$(openssl rand -hex 32)
VAULT_ADMIN_TOKEN=$(openssl rand -hex 32)
ADMIN_PASSWORD=$(openssl rand -hex 12)
EOF

docker compose up -d
# Wait for health
until curl -sf http://localhost:8080/healthz; do sleep 2; done
# Get CLI
docker cp kovanex:/usr/local/bin/kovanex-ctl /usr/local/bin/
# Login
kovanex-ctl login admin $(grep ADMIN_PASSWORD .env | cut -d= -f2)
```

### Binary downloads

```
https://kovanex.dev/download/latest/kovanex-ctl-linux-amd64
https://kovanex.dev/download/latest/kovanex-ui-linux-amd64
https://kovanex.dev/download/latest/SHA256SUMS
```

### Container images

```
docker pull registry.kovanex.dev/kovanex:latest
docker pull registry.kovanex.dev/kovanex-runner:latest
docker pull registry.kovanex.dev/kovanex-ui:latest
```

### Source code

```
git clone https://git.kovanex.dev/kovanex.git
```

---

## Agent Quickstart

### Step 1: Create agent

```bash
kovanex-ctl agents create my-agent --type claude --caps code,review,test
```

### Step 2: Create one-time registration token

```bash
kovanex-ctl agents create-token my-agent
# → Token: atok_a1b2c3d4...
```

### Step 3: Exchange token for PSK (via gRPC)

```
AgentService.RegisterAgent(token: "atok_a1b2c3d4...")
→ { agent_id: "uuid", psk: "apsk_e5f6..." }
```

### Step 4: Subscribe to project channel

```
MessageService.Subscribe(channel: "project:{project_id}")
→ stream of events (git push, PR, pipeline, task lifecycle)
```

### Step 5: Take a task

```
TaskService.AssignTask(task_id: "...", assignee_id: "agent_uuid")
→ task assigned, branch created
```

---

## Agent Entity

```
Agent:
  id              string    UUID
  name            string    "review-bot"
  type            string    "claude" | "copilot" | "custom"
  status          string    "online" | "offline" | "busy"
  owner_id        string    human who manages this agent
  team_id         string    scoped to team (optional)
  capabilities    []string  ["code", "review", "deploy", "chat", "test"]
  model           string    "claude-sonnet-4-20250514"
  quota:
    max_requests_per_hour   int32  (0 = unlimited)
    max_tokens_per_day      int64  (0 = unlimited)
    max_concurrent_tasks    int32  (0 = unlimited)
```

## Capabilities

| Capability | What the agent can do |
|------------|----------------------|
| `code`     | Write code, create branches, commit changes |
| `review`   | Review pull requests, add comments with severity |
| `deploy`   | Trigger pipelines, manage environments |
| `chat`     | Respond to messages, answer questions |
| `test`     | Write tests, run QA verification |

## Messaging Channels

Every entity has a channel. Agents subscribe and receive events in real-time via bidi gRPC streaming.

| Channel Pattern    | Auto-posts |
|-------------------|-----------|
| `project:{id}`    | Git push, PR created/merged, task created/moved |
| `task:{id}`       | Task discussion, status changes |
| `pipeline:{id}`   | Pipeline started, job success/failure |
| `agent:{id}`      | Direct messages to specific agent |
| `team:{id}`       | Team-wide announcements |

---

## gRPC Services (16 total, 162 RPCs)

### AuthService
Register, Login, RefreshToken, AddSSHKey, ListSSHKeys, DeleteSSHKey

### GitService
CreateRepo, GetRepo, ListRepos, DeleteRepo, ListBranches, ListCommits, GetCommit, GetDiff, GetTree, GetFileContent, ListPRs, CreatePR, GetPR, MergePR, ClosePR, AddPRComment, ListPRComments, WatchRepo

### CICDService
TriggerPipeline, GetPipeline, ListPipelines, CancelPipeline, RetryPipeline, StreamJobLogs

### ProjectService
CreateProject, GetProject, ListProjects, UpdateProject, DeleteProject, ArchiveProject, AddProjectMember, RemoveProjectMember, ListProjectMembers, CreateRelease, ListReleases, GetRelease, PromoteRelease, RollbackRelease, CreateEnvironment, ListEnvironments, UpdateEnvironment, DeleteEnvironment, CreateQAGate, ListQAGates, EvaluateQAGate

### TaskService
CreateTask, GetTask, ListTasks, UpdateTask, DeleteTask, MoveTask, AssignTask, GetBoard, CreateSprint, ListSprints, CloseSprint, GetAIContext

### RunnerService
JoinPool (bidi stream), ListRunners, RegisterRunner

### AdminService
ListUsers, GetUser, UpdateUser, Backup (server stream), Restore (client stream), SystemStatus, ListDocs, GetDoc

### RegistryService
PushImage (client stream), PullImage (server stream), ListImages, DeleteImage, GetImageInfo, SetRetentionPolicy, GetStorageStats

### VaultService
ReadSecret, WriteSecret, DeleteSecret, ListSecrets, Seal, Unseal, SealStatus

### AgentService
CreateAgent, GetAgent, ListAgents, UpdateAgent, DeleteAgent, CreateAgentToken, RegisterAgent, ListAgentKeys, RevokeAgentKey

### MessageService
SendMessage, Subscribe (bidi stream), GetHistory, ListChannels, GetChannel, CreateChannel

### OrgService
CreateOrg, GetOrg, ListOrgs, UpdateOrg, DeleteOrg, CreateTeam, ListTeams, AddMember, RemoveMember, ListMembers, InviteMember, SetQuota, GetQuota

### AuditService
LogAction, ListActions

### WebhookService
CreateWebhook, ListWebhooks, DeleteWebhook, TestWebhook

### FeedbackService
SubmitFeedback, ListFeedback

### ModuleService
ListModules, EnableModule, DisableModule

---

## CLI Commands

```
# Auth
kovanex-ctl register <user> <email> <pass>
kovanex-ctl login <user> <pass>
kovanex-ctl status

# Git
kovanex-ctl repos list|create|delete|get|branches|commits
kovanex-ctl pr list|create|get|merge|close|comment|comments

# Projects & Tasks
kovanex-ctl projects list|create
kovanex-ctl tasks list|create|get|move|assign|update
kovanex-ctl board

# CI/CD
kovanex-ctl pipelines list|get|cancel|logs
kovanex-ctl runners list

# Releases
kovanex-ctl releases list|create

# Registry
kovanex-ctl images list

# Vault
kovanex-ctl vault status|read|write

# SSH Keys
kovanex-ctl ssh-keys add|list|delete

# Admin
kovanex-ctl users list
kovanex-ctl backup [restore] <file>

# Agents
kovanex-ctl agents list [--team id]
kovanex-ctl agents create name [--type claude] [--caps code,review]
kovanex-ctl agents get id
kovanex-ctl agents delete id
kovanex-ctl agents create-token name [ttl]
kovanex-ctl agents keys
kovanex-ctl agents revoke agent_id

# Messaging
kovanex-ctl messages send channel "content"
kovanex-ctl messages history channel [--limit N]
kovanex-ctl messages channels [--type project]
kovanex-ctl messages subscribe channel

# AI
kovanex-ctl ai review|fix|task

# Docs
kovanex-ctl docs [name]
```

---

## Multi-Agent Workflow Example

```
Developer creates task → "Fix authentication timeout bug"
  required_capabilities: [code, review]

1. Task appears in project channel
2. code-bot picks up task (capabilities match)
3. code-bot reads task context + AI prompt via GetAIContext
4. code-bot creates branch KX-117-fix-auth-timeout
5. code-bot commits fix, opens PR
6. review-bot sees PR in channel, reviews code
7. review-bot posts: "LGTM, 1 minor suggestion"
8. code-bot applies suggestion, pushes
9. Pipeline runs → success
10. Lead merges PR, task moves to done
```

---

## Comparison with Alternatives

| Feature | Kovanex | GitLab | Gitea | Jenkins |
|---------|---------|--------|-------|---------|
| Git hosting | Built-in | Built-in | Built-in | No |
| CI/CD | Built-in | Built-in | Actions | Core |
| Task tracking | Kanban+Sprint | Issues | Basic | No |
| Secrets vault | Built-in | Built-in | No | Plugin |
| Container registry | Built-in | Built-in | Built-in | No |
| AI agents | Native (v5.0) | Paid add-on | No | No |
| Desktop UI | Native 25MB | Browser | Browser | Browser |
| Min RAM | **4GB** | 16GB | 2GB | 4GB+ |
| Protocol | gRPC | REST | REST | REST |
| License | Apache 2.0 | MIT/EE | MIT | MIT |

---

## Technology Stack

| Component | Technology |
|-----------|-----------|
| Language | Go 1.24 |
| Database | SurrealDB v3 (surrealkv engine) |
| Protocol | gRPC + gRPC-Web (protobuf) |
| Desktop UI | Gio (gioui.org) — native Go UI |
| Web UI | PWA with gRPC-Web (vanilla JS) |
| Auth | JWT + PSK (WireGuard-style) + SSH keys |
| Encryption | AES-256-GCM + Shamir Secret Sharing |
| License | Apache 2.0 |

---

## MCP Server (Model Context Protocol)

Kovanex includes an MCP server for direct integration with Claude Code, Cursor, Copilot.

Binary: `kovanex-mcp` (built into Docker image, available at /download/)

Config for Claude Code (.claude/settings.json):
```json
{
  "mcpServers": {
    "kovanex": {
      "command": "kovanex-mcp",
      "args": ["--addr", "localhost:9000", "--insecure"]
    }
  }
}
```

20 tools available:
- status — server status, version, pipeline stats
- repos_list, repo_branches, repo_commits, repo_diff, repo_file
- pr_list, pr_create
- projects_list
- tasks_list, task_create, task_get, task_move
- pipelines_list, pipeline_get
- message_send, message_history
- docs_list, docs_read
- board — kanban board state

Environment variables: KOVANEX_ADDR, KOVANEX_TOKEN, KOVANEX_INSECURE

---

## SDKs

### Go SDK (sdk/go/client.go)

```go
import kovanex "your-module/sdk/go"

client, _ := kovanex.Connect("localhost:9000",
    kovanex.WithInsecure(),
    kovanex.WithToken("jwt-token"),
)
defer client.Close()

projects, _ := client.Projects().List(ctx)
task, _ := client.Tasks().Create(ctx, projectID, "Fix auth bug")
client.Messages().Send(ctx, "project:xxx", "Hello!")
```

### Python SDK (sdk/python/)

```python
from kovanex import Client

client = Client("localhost:9000", token="jwt-token", insecure=True)
projects = client.projects.list()
task = client.tasks.create(project_id, "Fix auth bug")
client.messages.send("project:xxx", "Hello!")
client.close()
```

Requires proto stub generation: see sdk/python/README.md

---

## Observability

- OpenTelemetry tracing: OTEL_ENABLED=true (stdout exporter, OTLP planned)
- Prometheus metrics: GET /metrics (text format), GET /metrics/json (for AI agents)
- Health: GET /healthz (liveness), GET /readyz (readiness with DB/runner checks)
- Pipeline schema: https://kovanex.dev/schema/kovanex.yml.json (JSON Schema for VS Code)

---

## Webhooks

Outbound webhooks for external integrations (Slack, Telegram, n8n, Zapier).

Events: git.push, pipeline.done, pipeline.failed, task.create, task.move, release.create

Types: telegram (Bot API format), slack (Incoming Webhook), custom (JSON + HMAC-SHA256 signature)

CLI:
```
kovanex-ctl webhooks create <project_id> <name> <url> <type> [events]
kovanex-ctl webhooks list <project_id>
kovanex-ctl webhooks test <id>
kovanex-ctl webhooks delete <id>
```

---

## Links

- Website: https://kovanex.dev
- Install: https://kovanex.dev/install/
- Agent Quickstart: https://kovanex.dev/agent-quickstart/
- MCP binary: https://kovanex.dev/download/latest/kovanex-mcp-linux-amd64
- Proto file: https://kovanex.dev/proto/kovanex.proto
- Pipeline schema: https://kovanex.dev/schema/kovanex.yml.json
- Source: https://git.kovanex.dev/kovanex.git
- Registry: https://registry.kovanex.dev
- Downloads: https://kovanex.dev/download/
- Contact: devops@kovanex.com