rdev/CLAUDE.md

rdev - Remote Developer

Run Claude Code instances in isolated Kubernetes pods with REST API control. Enables bots, CI/CD systems, and external orchestrators to dispatch agentive development work to isolated environments.

Platform: threesix.ai - Agent-driven development at scale with shared worker pools.

Find Your Guide

If you need to...	Read this
Set up local dev	local/setup.md
Run tests	local/testing.md
Write Go code / handlers	backend/go-guidelines.md
Understand pkg/api	packages/api-framework.md
Add a new handler/endpoint	backend/adding-handlers.md
Understand hexagonal architecture	backend/hexagonal.md
Deploy to k3s	ops/deploying.md
Work with Kubernetes adapters	services/kubernetes.md
Database / migrations	ops/database.md
Manage credentials	ops/credentials.md
Work queue system	services/work-queue.md
Worker pool management	services/worker-pool.md
Project templates	services/templates.md
Build orchestration	services/build-orchestration.md

Critical Rules

• KUBECONFIG: ALWAYS set export KUBECONFIG=~/.kube/orchard9-k3sf.yaml before kubectl commands
• Hexagonal: Domain models in internal/domain/ must have ZERO external dependencies
• Ports: All adapters implement interfaces from internal/port/
• Migrations: NEVER modify committed migrations. Create NEW ones.
• 500-line limit: Files exceeding 500 lines must be split
• Tests: All handlers and services require tests

Quick Reference

# Set kubeconfig (REQUIRED)
export KUBECONFIG=~/.kube/orchard9-k3sf.yaml

# Run locally
go run ./cmd/rdev-api

# Run tests
go test ./...

# Deploy
kubectl apply -k deployments/k8s/base

# Verify pods
kubectl get pods -n rdev

# Check workers
kubectl get pods -n rdev -l rdev.orchard9.ai/role=worker

# Load credentials from .secrets to rdev-api
./scripts/load-credentials.sh                              # localhost
./scripts/load-credentials.sh https://rdev.example.com     # remote

Architecture Overview

cmd/rdev-api/          # Entry point, DI, OpenAPI spec
internal/
├── domain/            # Pure business models (no deps)
├── port/              # Interface contracts
├── service/           # Business logic orchestration
├── handlers/          # HTTP handlers (REST endpoints)
├── adapter/           # Infrastructure implementations
│   ├── kubernetes/    # K8s client, pod executor
│   ├── postgres/      # Audit, queue, webhooks, credentials
│   ├── gitea/         # Git repository management
│   ├── cloudflare/    # DNS provider
│   └── woodpecker/    # CI provider
├── auth/              # API key auth, scopes
├── middleware/        # Rate limiting
├── worker/            # Background queue processor
└── webhook/           # Event dispatcher
pkg/api/               # HTTP framework (app, responses)
deployments/k8s/       # Kustomize manifests
  └── base/templates/  # Project templates
scripts/               # Operational scripts
  └── load-credentials.sh  # Load secrets to rdev-api

Key Concepts

• Projects: Kubernetes pods with Claude Code, discovered by label rdev.orchard9.ai/project=true
• Workers: Shared claudebox pods that execute any project's tasks, labeled rdev.orchard9.ai/role=worker
• Work Queue: Async task queue for build/test/deploy jobs
• Credentials: Infrastructure secrets (tokens, keys) stored encrypted in PostgreSQL
• Commands: Claude/shell/git commands executed via kubectl exec, streamed via SSE
• API Keys: Scoped auth with project restrictions, IP filtering, expiration
• Webhooks: Event subscriptions with retry delivery
• Templates: Project scaffolding with .woodpecker.yml, .claude/, and stack files

threesix.ai Platform Roadmap

See k3s-fleet/tmp/address-the-gaps.md for full implementation details:

Gap	Status	Description
Woodpecker Auto-Activation	Planned	Auto-enable CI on project creation
Project Templates	Planned	Seed repos with .woodpecker.yml, .claude/
Work Queue	Planned	Task queue for worker pool
Worker Pool	Planned	Shared claudebox workers (3-5 pods)
Bot Communication	Planned	Webhook callbacks on task completion
Build Orchestration	Planned	Structured build specs via API

Constraints

• ON-PREM k3s - not GKE, always set KUBECONFIG
• Kustomize only - no ArgoCD
• chi/v5 router - no gin, echo, or other frameworks
• sqlx for DB - no GORM
• slog for logging - no logrus, zap