kandev/docs/GETTING_STARTED.md

Getting Started with Kandev Backend Development

Note: This guide reflects the current unified binary implementation. The original microservices architecture is documented in IMPLEMENTATION_PLAN.md for future reference.

Prerequisites

Required Software

1. Go 1.21 or higher

   # Check version
   go version
   
   # Install from https://go.dev/dl/
   

2. Docker

   # Check version
   docker --version
   
   # Install from https://docs.docker.com/get-docker/
   

3. Augment CLI Credentials

   # Verify Augment session exists
   cat ~/.augment/session.json
   

4. Git with SSH Keys Configured (for repository access)

   git --version
   
   # Verify SSH keys exist
   ls -la ~/.ssh/
   

---

Quick Start

Step 1: Build the Backend

cd apps/backend

# Build the binary
make build

# This creates ./bin/kandev

Step 2: Run the Server

# Run with default settings (creates kandev.db in current directory)
./bin/kandev

# Or specify a custom database path
KANDEV_DB_PATH=/path/to/kandev.db ./bin/kandev

The server starts on port 8080 by default.

Step 3: Verify It's Running

The backend uses a WebSocket-first architecture. Connect to ws://localhost:8080/ws to interact with the API.

Using websocat (Command Line)

# Install websocat
# macOS: brew install websocat
# Linux: cargo install websocat

# Health check
echo '{"id":"1","type":"request","action":"health.check","payload":{}}' | websocat ws://localhost:8080/ws

# Should return a response with status "ok"

Using JavaScript

const ws = new WebSocket('ws://localhost:8080/ws');

ws.onopen = () => {
  ws.send(JSON.stringify({
    id: '1',
    type: 'request',
    action: 'health.check',
    payload: {}
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log('Health:', msg); // { id: '1', type: 'response', action: 'health.check', payload: { status: 'ok' }, ... }
};

---

WebSocket Message Protocol

Connection

Connect to: ws://localhost:8080/ws

Message Envelope

All messages use this envelope format:

{
  "id": "correlation-uuid",
  "type": "request|response|notification|error",
  "action": "action.name",
  "payload": {},
  "timestamp": "2026-01-10T10:30:00Z"
}

Message Types

• request - Client request to the server
• response - Server response to a request
• notification - Server push notification (e.g., agent status updates)
• error - Error response

---

Basic Usage

Create a Board

websocat

echo '{"id":"1","type":"request","action":"board.create","payload":{"name":"My Project","description":"Project tasks"}}' | websocat ws://localhost:8080/ws

JavaScript

ws.send(JSON.stringify({
  id: '1',
  type: 'request',
  action: 'board.create',
  payload: { name: 'My Project', description: 'Project tasks' }
}));

List Boards

websocat

echo '{"id":"2","type":"request","action":"board.list","payload":{}}' | websocat ws://localhost:8080/ws

JavaScript

ws.send(JSON.stringify({
  id: '2',
  type: 'request',
  action: 'board.list',
  payload: {}
}));

Create a Column

websocat

echo '{"id":"3","type":"request","action":"column.create","payload":{"board_id":"<board_id>","name":"To Do"}}' | websocat ws://localhost:8080/ws

JavaScript

ws.send(JSON.stringify({
  id: '3',
  type: 'request',
  action: 'column.create',
  payload: { board_id: '<board_id>', name: 'To Do' }
}));

Create a Task

websocat

echo '{"id":"4","type":"request","action":"task.create","payload":{"board_id":"<board_id>","column_id":"<column_id>","title":"Fix login bug","description":"Users cannot login"}}' | websocat ws://localhost:8080/ws

JavaScript

ws.send(JSON.stringify({
  id: '4',
  type: 'request',
  action: 'task.create',
  payload: {
    board_id: '<board_id>',
    column_id: '<column_id>',
    title: 'Fix login bug',
    description: 'Users cannot login'
  }
}));

Launch an Agent for a Task

websocat

echo '{"id":"5","type":"request","action":"agent.launch","payload":{"task_id":"<task_id>","agent_type":"augment-agent","repository_url":"/path/to/your/project"}}' | websocat ws://localhost:8080/ws

JavaScript

ws.send(JSON.stringify({
  id: '5',
  type: 'request',
  action: 'agent.launch',
  payload: {
    task_id: '<task_id>',
    agent_type: 'augment-agent',
    repository_url: '/path/to/your/project'
  }
}));

Start Task via Orchestrator

websocat

echo '{"id":"6","type":"request","action":"orchestrator.start","payload":{"task_id":"<task_id>"}}' | websocat ws://localhost:8080/ws

JavaScript

ws.send(JSON.stringify({
  id: '6',
  type: 'request',
  action: 'orchestrator.start',
  payload: { task_id: '<task_id>' }
}));

Check Agent Status

websocat

echo '{"id":"7","type":"request","action":"agent.status","payload":{"agent_id":"<agent_id>"}}' | websocat ws://localhost:8080/ws

JavaScript

ws.send(JSON.stringify({
  id: '7',
  type: 'request',
  action: 'agent.status',
  payload: { agent_id: '<agent_id>' }
}));

Interactive Mode

For interactive testing, connect in interactive mode:

websocat ws://localhost:8080/ws
# Then type messages manually, one per line:
{"id":"1","type":"request","action":"health.check","payload":{}}
{"id":"2","type":"request","action":"board.list","payload":{}}

---

Running the End-to-End Test

The project includes a comprehensive E2E test script:

# Build the agent Docker image first
cd apps/backend/dockerfiles/augment-agent
docker build -t kandev/augment-agent:latest .

# Run the E2E test
cd /path/to/kandev
./scripts/e2e-test.sh

The E2E test uses WebSocket connections to:

1. Start the server with a fresh database
2. Connect via WebSocket to ws://localhost:8080/ws
3. Create a board, column, and task using WebSocket messages
4. Start the task via the orchestrator (orchestrator.start)
5. Verify the agent container starts
6. Check that ACP session is created
7. Receive real-time agent status notifications
8. Wait for agent to complete

---

Configuration

Environment Variable	Default	Description
KANDEV_DB_PATH	./kandev.db	SQLite database file path
PORT	8080	HTTP server port

---

Development Workflow

Build

cd apps/backend
make build

Run Tests

cd apps/backend
make test

# Or with verbose output
go test -v ./...

Code Formatting

go fmt ./...
go vet ./...

View Database

# SQLite CLI
sqlite3 apps/backend/kandev.db

# List tables
.tables

# View boards
SELECT * FROM boards;

# View tasks
SELECT * FROM tasks;

---

Project Structure

kandev/
├── apps/
│   ├── backend/              # Go backend services
│   │   ├── cmd/kandev/       # Main entry point
│   │   │   └── main.go
│   │   ├── internal/
│   │   │   ├── agent/        # Agent management
│   │   │   │   ├── acp/      # ACP session management
│   │   │   │   ├── api/      # Agent HTTP handlers
│   │   │   │   ├── credentials/  # Credential providers
│   │   │   │   ├── docker/   # Docker client
│   │   │   │   ├── lifecycle/# Container lifecycle
│   │   │   │   └── registry/ # Agent type registry
│   │   │   ├── task/         # Task management
│   │   │   │   ├── api/      # Task HTTP handlers
│   │   │   │   ├── models/   # Data models
│   │   │   │   ├── repository/  # SQLite/Memory storage
│   │   │   │   └── service/  # Business logic
│   │   │   ├── orchestrator/ # Orchestration logic
│   │   │   ├── events/       # In-memory event bus
│   │   │   └── common/       # Shared utilities
│   │   │       └── logger/   # Zap logger
│   │   ├── pkg/acp/          # ACP protocol types
│   │   │   └── jsonrpc/      # JSON-RPC 2.0 client
│   │   ├── dockerfiles/      # Agent Dockerfiles
│   │   │   └── augment-agent/
│   │   ├── bin/              # Built binaries (gitignored)
│   │   └── Makefile
│   └── web/                  # Frontend application
├── scripts/
│   └── e2e-test.sh           # End-to-end test script
└── docs/                     # Documentation

---

Troubleshooting

Docker Permission Issues

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
newgrp docker

Port Already in Use

# Find process using port 8080
lsof -i :8080

# Kill it
kill -9 <PID>

Database Issues

# Delete and recreate database
rm apps/backend/kandev.db
./bin/kandev  # Will create fresh database

Agent Container Issues

# List running containers
docker ps -a --filter "label=kandev.managed=true"

# View container logs
docker logs <container_id>

# Clean up old containers
docker rm $(docker ps -a -q --filter "label=kandev.managed=true")

---

Next Steps

See NEXT_STEPS.md for the development roadmap and immediate next steps.