rdev/docs/reference.md

rdev Quick Reference

Quick reference for operating rdev on the k3s cluster.

Prerequisites

# REQUIRED: Set kubeconfig before any kubectl command
export KUBECONFIG=~/.kube/orchard9-k3sf.yaml

# API access
export RDEV_API_URL="https://rdev.masq-ops.orchard9.ai"
export RDEV_API_KEY="<from rdev-credentials secret>"

Essential Commands

rdev API

# Health check
curl -H "X-API-Key: $RDEV_API_KEY" $RDEV_API_URL/health

# List projects
curl -H "X-API-Key: $RDEV_API_KEY" $RDEV_API_URL/projects

# Work queue stats
curl -H "X-API-Key: $RDEV_API_KEY" $RDEV_API_URL/work/stats

# List credentials (masked)
curl -H "X-API-Key: $RDEV_API_KEY" $RDEV_API_URL/credentials

Pod Management

# View rdev pods
kubectl get pods -n rdev

# View logs (use script for convenience)
./scripts/logs.sh           # Last 100 lines
./scripts/logs.sh -f        # Follow/stream
./scripts/logs.sh -e        # Errors only

# Restart rdev-api
kubectl rollout restart deployment/rdev-api -n rdev

Database Connections

CockroachDB

# Interactive SQL shell
kubectl exec -it -n databases cockroachdb-0 -- \
  /cockroach/cockroach sql --insecure --host=localhost:26257

# Run a query
kubectl exec -n databases cockroachdb-0 -- \
  /cockroach/cockroach sql --insecure --host=localhost:26257 \
  -e "SHOW DATABASES;"

# Check cluster status
kubectl exec -n databases cockroachdb-0 -- \
  /cockroach/cockroach node status --insecure --host=localhost:26257

Console: https://cockroachdb.threesix.ai

Redis

# Get password
REDIS_PASS=$(kubectl get secret -n threesix redis-credentials -o jsonpath="{.data.REDIS_PASSWORD}" | base64 -d)

# Interactive CLI
kubectl exec -it -n threesix redis-0 -- redis-cli -a "$REDIS_PASS"

# Ping test
kubectl exec -n threesix redis-0 -- redis-cli -a "$REDIS_PASS" ping

# Memory info
kubectl exec -n threesix redis-0 -- redis-cli -a "$REDIS_PASS" info memory

PostgreSQL (rdev metadata)

kubectl exec -it -n databases postgres-0 -- psql -U rdev -d rdev

Credentials Management

Infrastructure credentials are stored in .secrets (gitignored) at repo root.

# Load credentials to database
./scripts/load-credentials.sh $RDEV_API_URL

# Verify loaded
curl -H "X-API-Key: $RDEV_API_KEY" $RDEV_API_URL/credentials?category=cloudflare

Key credential categories:

• gitea - Git repository management
• cloudflare - DNS record management
• woodpecker - CI/CD pipelines

See Credentials Guide for .secrets file format.

Release & Deploy

# Release + deploy (one command)
./scripts/release.sh v0.10.1 "Description of changes" --deploy

# Release only (no deploy)
./scripts/release.sh v0.10.1 "Description of changes"

# Manual deploy
kubectl apply -f deployments/k8s/base/rdev-api.yaml
kubectl rollout restart -n rdev deployment/rdev-api

Service URLs

Service	Internal URL	External URL
rdev API	rdev-api.rdev.svc:8080	https://rdev.masq-ops.orchard9.ai
CockroachDB	cockroachdb-public.databases.svc:26257	https://cockroachdb.threesix.ai
Redis	redis.threesix.svc:6379	(internal only)
PostgreSQL	postgres.databases.svc:5432	(internal only)
Gitea	gitea.gitea.svc:3000	https://git.threesix.ai
Woodpecker	woodpecker-server.woodpecker.svc:8000	https://ci.threesix.ai

Documentation Index

Topic	Location
Developer Guides	.claude/guides/
Setup & Local Dev	.claude/guides/local/setup.md
Go Guidelines	.claude/guides/backend/go-guidelines.md
Hexagonal Architecture	.claude/guides/backend/hexagonal.md
Operations	docs/operations/
Deployment	docs/operations/deployment.md
Monitoring	docs/operations/monitoring.md
Troubleshooting	docs/operations/troubleshooting.md
Database Connections	docs/operations/database-connections.md
API Reference	docs/api/
Authentication	docs/api/authentication.md
SSE Streaming	docs/api/sse-examples.md
Architecture	docs/architecture/
Overview	docs/architecture/README.md
Security	docs/architecture/security.md

Troubleshooting

rdev-api Not Responding

# Check pod status
kubectl get pods -n rdev -l app=rdev-api

# Check logs
./scripts/logs.sh -e  # errors only

# Restart
kubectl rollout restart deployment/rdev-api -n rdev

Database Connection Issues

# Check CockroachDB
kubectl get pods -n databases -l app=cockroachdb

# Check Redis
kubectl get pods -n threesix -l app=redis

# Check PostgreSQL
kubectl get pods -n databases -l app=postgres

Credentials Not Working

# Verify credentials loaded
curl -H "X-API-Key: $RDEV_API_KEY" $RDEV_API_URL/credentials | jq

# Reload and restart
./scripts/load-credentials.sh $RDEV_API_URL
kubectl rollout restart deployment/rdev-api -n rdev

---

Legacy: Claudebox VM Reference

Note: This section documents the original claudebox Docker/VM deployment pattern. rdev now runs on k3s. See above for current commands.

The original architecture used Docker containers on a VM with Discord bot integration. This reference is preserved for historical context and for deployments not using k3s.

Click to expand legacy claudebox documentation

Architecture (VM-based)

Physical Layout:
├── Remote VM (Ubuntu 22.04+)
│   ├── Docker Container: claudebox-project-a
│   ├── Docker Container: claudebox-project-b
│   └── Docker Container: claudebox-project-c
│   └── Discord Bot Process (routes to containers)

Key Differences from k3s

Aspect	Claudebox (VM)	rdev (k3s)
Orchestration	Docker Compose	Kubernetes
Commands	docker exec	kubectl exec
Storage	Host volumes	Longhorn PVCs
Credentials	~/.claude/.credentials.json	PVC mount
Bot	Deno Discord bot	REST API

Claudebox Commands (VM)

# Start containers
cd ~/claude-infra
docker compose up -d

# View status
docker compose ps

# Execute command
docker exec -it claudebox-project-a bash

# Claude session
docker exec -it claudebox-project-a claude "your prompt"

Management Script

claude-manage start              # Start all containers
claude-manage status             # Check system status
claude-manage logs project-a     # View logs
claude-manage shell project-b    # Open shell
claude-manage health             # Run health checks

For full claudebox documentation, see:

• https://github.com/RchGrav/claudebox
• https://github.com/zebbern/claude-code-discord