39df51defd
Implements weeks 1-4 of the multi-provider architecture: Week 1 - Foundation: - Add domain models (AgentProvider, AgentRequest, AgentEvent, AgentResult) - Define CodeAgent port interface with Execute, Cancel, Capabilities - Create thread-safe provider registry with first-registered default Week 2 - Claude Code Adapter: - Extract kubectl exec logic into CodeAgent implementation - Parse stream-json output format (init, message, tool_use, result) - Support session continuation via --resume flag Week 3 - OpenCode Adapter: - HTTP/SSE client for opencode serve API - Session management (create, send message, abort) - Event streaming with documented buffer rationale Week 4 - Quality & Polish: - Fix race condition in OpenCode Cancel method - Add AgentRequest.Validate() with ErrPromptRequired, ErrInvalidTimeout - Document DefaultAvailabilityTimeout constants - Add HTTP error context for debugging Also includes: - Work queue system with PostgreSQL adapter - Credential store for infrastructure secrets - Project templates with Woodpecker CI integration - Comprehensive test coverage Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
118 lines
5.2 KiB
Markdown
118 lines
5.2 KiB
Markdown
# 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](.claude/guides/local/setup.md) |
|
|
| **Run tests** | [local/testing.md](.claude/guides/local/testing.md) |
|
|
| **Write Go code / handlers** | [backend/go-guidelines.md](.claude/guides/backend/go-guidelines.md) |
|
|
| **Understand pkg/api** | [packages/api-framework.md](.claude/guides/packages/api-framework.md) |
|
|
| **Add a new handler/endpoint** | [backend/adding-handlers.md](.claude/guides/backend/adding-handlers.md) |
|
|
| **Understand hexagonal architecture** | [backend/hexagonal.md](.claude/guides/backend/hexagonal.md) |
|
|
| **Deploy to k3s** | [ops/deploying.md](.claude/guides/ops/deploying.md) |
|
|
| **Work with Kubernetes adapters** | [services/kubernetes.md](.claude/guides/services/kubernetes.md) |
|
|
| **Database / migrations** | [ops/database.md](.claude/guides/ops/database.md) |
|
|
| **Manage credentials** | [ops/credentials.md](.claude/guides/ops/credentials.md) |
|
|
| **Work queue system** | [services/work-queue.md](.claude/guides/services/work-queue.md) |
|
|
| **Worker pool management** | [services/worker-pool.md](.claude/guides/services/worker-pool.md) |
|
|
| **Project templates** | [services/templates.md](.claude/guides/services/templates.md) |
|
|
| **Build orchestration** | [services/build-orchestration.md](.claude/guides/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
|
|
|
|
```bash
|
|
# 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
|