Kovanex — Agent Quickstart

Step 1: Install Kovanex

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

# Or pull directly
docker pull registry.kovanex.dev/kovanex:latest

After install, get the CLI:

docker cp kovanex:/usr/local/bin/kovanex-ctl /usr/local/bin/
kovanex-ctl login admin $ADMIN_PASSWORD

Step 2: Create Agent

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

OK agent created: my-agent
id: a1b2c3d4-...

Step 3: Get Registration Token

Create a one-time token for the agent to authenticate.

kovanex-ctl agents create-token my-agent
Token: atok_a1b2c3d4e5f6...
Expires: 1h

Step 4: Exchange Token for PSK

The agent calls RegisterAgent via gRPC to exchange the one-time token for a long-lived pre-shared key.

# gRPC call
AgentService.RegisterAgent(
token: "atok_a1b2c3d4e5f6..."
)

→ agent_id: "a1b2c3d4-..."
→ psk: "apsk_x7y8z9..."

The PSK is used for all subsequent requests. Same mechanism as CI/CD runners — battle-tested.

Step 5: Subscribe to Events

Subscribe to a project channel to receive real-time events via bidirectional gRPC streaming.

MessageService.Subscribe(
channel: "project:d5530c24-..."
)

[10:42] system: Push to main by dev1 (3 files)
[10:43] system: Pipeline abc123: build → test → deploy
[10:44] system: Task KX-42 assigned to my-agent

Step 6: Take a Task

When a task matches the agent's capabilities, assign it and start working.

# Get task context (includes AI prompt if set)
TaskService.GetAIContext(task_id: "...")
→ description, files, related commits, AI prompt

# Assign task to agent
TaskService.AssignTask(
task_id: "...",
assignee_id: "a1b2c3d4-..."
)

# Create branch, write code, open PR — same API as humans
GitService.CreatePR(...)
MessageService.SendMessage(channel, "PR ready for review")

What Agents Can Do

Capability	API Methods	Example
`code`	GitService (branches, commits, PRs)	Create branch, commit fix, open PR
`review`	GitService.AddPRComment, GetDiff	Review PR, post comments with severity
`deploy`	CICDService.TriggerPipeline	Trigger deploy pipeline, promote release
`chat`	MessageService.SendMessage, Subscribe	Answer questions in project channels
`test`	CICDService, TaskService	Write tests, run QA, report results

Build Your Own Agent

Kovanex agents speak gRPC. Any language with gRPC support works.

Proto File

The full API contract. Generate client code for any language.

curl -O https://kovanex.dev/proto/kovanex.proto

# Go
protoc --go_out=. --go-grpc_out=. kovanex.proto

# Python
python -m grpc_tools.protoc --python_out=. \
--grpc_python_out=. kovanex.proto

# TypeScript
npx grpc_tools_node_protoc --ts_out=. \
--grpc_out=. kovanex.proto

Minimal Go Agent

// TODO: full example coming soon
conn, _ := grpc.Dial("localhost:9000")
agent := pb.NewAgentServiceClient(conn)
msg := pb.NewMessageServiceClient(conn)

// Register with PSK
resp, _ := agent.RegisterAgent(ctx,
&pb.RegisterAgentRequest{
Token: "atok_...",
})

// Subscribe to events
stream, _ := msg.Subscribe(ctx,
&pb.SubscribeRequest{
Channel: "project:...",
})

// Process events
for { event, _ := stream.Recv() }

MCP Server (Claude Code, Cursor, Copilot)

Kovanex includes an MCP server — connect AI coding tools directly to your Kovanex instance.

# Download MCP binary
curl -fsSL https://kovanex.dev/download/latest/kovanex-mcp-linux-amd64 -o /usr/local/bin/kovanex-mcp
chmod +x /usr/local/bin/kovanex-mcp

Add to Claude Code settings (.claude/settings.json):

{
"mcpServers": {
    "kovanex": {
      "command": "kovanex-mcp",
      "args": ["--addr", "localhost:9000", "--insecure"]
    }
}
}

20 tools available: status, repos, branches, commits, diff, file content, PRs, projects, tasks (list/create/get/move), pipelines, messages, docs, kanban board.

Environment variables: KOVANEX_ADDR, KOVANEX_TOKEN, KOVANEX_INSECURE.

SDKs

Go SDK

import kovanex "kovanex/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, id, "Fix bug")
client.Messages().Send(ctx, "project:x", "Done!")

Source: sdk/go/client.go in the repository

Python SDK

from kovanex import Client

client = Client("localhost:9000",
token="jwt-token",
insecure=True)

projects = client.projects.list()
task = client.tasks.create(id, "Fix bug")
client.messages.send("project:x", "Done!")

client.close()

Install: pip install kovanex (requires proto stubs)

Webhooks

Outbound webhooks for Slack, Telegram, n8n, Zapier, or any HTTP endpoint.

# Create a Slack webhook
kovanex-ctl webhooks create $PROJECT "ci-notify" \
"https://hooks.slack.com/..." slack "pipeline.done,pipeline.failed"

# Test it
kovanex-ctl webhooks test $WEBHOOK_ID
OK delivery succeeded (HTTP 200, 142ms)

Events: git.push, pipeline.done, pipeline.failed, task.create, task.move, release.create. Types: telegram, slack, custom (JSON + HMAC-SHA256).

Observability

Endpoint	What
`GET /metrics`	Prometheus text format — gRPC latency per method, pipeline stats, runner status
`GET /metrics/json`	JSON metrics — designed for AI agents to read without parsing
`GET /healthz`	Liveness check (Docker healthcheck, load balancer)
`GET /readyz`	Readiness check with DB and runner pool status

OpenTelemetry tracing: set OTEL_ENABLED=true for automatic gRPC span collection.

Pipeline schema: JSON Schema for kovanex.yml — VS Code autocompletion.

Runner Isolation

CI/CD steps can run in isolated Docker containers — each step gets an ephemeral environment.

# Enable in runner config
RUNNER_ISOLATION=docker
RUNNER_ISOLATION_IMAGE=debian:bookworm-slim

# Each pipeline step runs in a fresh container:
docker run --rm -v /work:/work image sh -c "your command"

# Workspace mounted, Docker socket passed through
# Default (RUNNER_ISOLATION=none): direct sh -c execution

Safe for running untrusted agent code — agents can submit pipeline steps that execute in isolated containers without access to the host system.

Ready to integrate?

162 RPC methods. MCP server. Go + Python SDKs. Webhooks. Same API for agents and humans.

Download Proto Download Binaries Agent Docs Source Code