// Package main provides the entry point for the rdev API server. // // rdev (Remote Developer) provides a REST API for controlling Claude Code // instances running in Kubernetes pods. External clients (Discord bots, // CLI tools, etc.) connect via this API. // // Authentication: // - All endpoints (except /health, /ready, /docs) require X-API-Key header // - Admin key from RDEV_ADMIN_KEY env var for key management // - Create additional keys via POST /keys // // Endpoints: // - GET /health - Health check (no auth) // - GET /ready - Readiness check (no auth) // - GET /docs - Scalar API documentation (no auth) // - GET /openapi.json - OpenAPI 3.0 specification (no auth) // - GET /keys - List API keys // - POST /keys - Create API key // - GET /keys/{id} - Get API key details // - DELETE /keys/{id} - Revoke API key // - GET /projects - List available projects // - GET /projects/{id} - Get project details // - POST /projects/{id}/claude - Run Claude command // - POST /projects/{id}/shell - Run shell command // - POST /projects/{id}/git - Run git command // - GET /projects/{id}/events - SSE stream for output // - GET /projects/{id}/claude-config - List commands/skills/agents // - GET /projects/{id}/claude-config/commands - List commands // - POST /projects/{id}/claude-config/commands - Create command // - GET /projects/{id}/claude-config/commands/{name} - Get command // - PUT /projects/{id}/claude-config/commands/{name} - Update command // - DELETE /projects/{id}/claude-config/commands/{name} - Delete command // (same pattern for /skills and /agents) package main import ( "context" "log/slog" "os" "strconv" "github.com/orchard9/rdev/internal/auth" "github.com/orchard9/rdev/internal/db" "github.com/orchard9/rdev/internal/handlers" "github.com/orchard9/rdev/pkg/api" ) func main() { logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{ Level: slog.LevelInfo, })) // Load configuration from environment cfg := loadConfig() // Initialize database with auto-migrations database, err := db.New(db.Config{ Host: cfg.DBHost, Port: cfg.DBPort, User: cfg.DBUser, Password: cfg.DBPassword, Database: cfg.DBName, SSLMode: cfg.DBSSLMode, }, logger) if err != nil { logger.Error("failed to connect to database", "error", err) os.Exit(1) } defer database.Close() // Initialize auth service authService := auth.NewService(database.DB, cfg.AdminKey) // Create app app := api.New("rdev-api", api.WithPort(cfg.Port), api.WithLogger(logger), ) // Add auth middleware (skips /health, /ready, /docs, /openapi.json) app.Use(auth.Middleware(authService)) // Initialize handlers projectsHandler := handlers.NewProjectsHandler() keysHandler := handlers.NewKeysHandler(authService) claudeConfigHandler := handlers.NewClaudeConfigHandler( projectsHandler.Registry(), projectsHandler.Executor(), ) // Register routes projectsHandler.Mount(app.Router()) keysHandler.Mount(app.Router()) claudeConfigHandler.Mount(app.Router()) // Enable API documentation app.EnableDocs(buildOpenAPISpec()) // Cleanup on shutdown app.OnShutdown(func(_ context.Context) error { return database.Close() }) logger.Info("rdev-api starting", "port", cfg.Port, "db_host", cfg.DBHost, "admin_key_set", cfg.AdminKey != "", ) app.Run() } // Config holds application configuration. type Config struct { Port int DBHost string DBPort int DBUser string DBPassword string DBName string DBSSLMode string AdminKey string } func loadConfig() Config { port := 8080 if v := os.Getenv("PORT"); v != "" { if p, err := strconv.Atoi(v); err == nil { port = p } } dbPort := 5432 if v := os.Getenv("DB_PORT"); v != "" { if p, err := strconv.Atoi(v); err == nil { dbPort = p } } return Config{ Port: port, DBHost: getEnv("DB_HOST", "postgres.databases.svc"), DBPort: dbPort, DBUser: getEnv("DB_USER", "appuser"), DBPassword: os.Getenv("DB_PASSWORD"), DBName: getEnv("DB_NAME", "rdev"), DBSSLMode: getEnv("DB_SSL_MODE", "disable"), AdminKey: os.Getenv("RDEV_ADMIN_KEY"), } } func getEnv(key, defaultVal string) string { if v := os.Getenv(key); v != "" { return v } return defaultVal } // buildOpenAPISpec creates the OpenAPI specification for the rdev API. func buildOpenAPISpec() *api.OpenAPISpec { spec := api.NewOpenAPISpec("rdev API", "0.5.0"). WithDescription(`Remote Developer API for controlling Claude Code instances in Kubernetes. rdev runs Claude Code CLI in isolated pods, controlled via this REST API with SSE streaming. External clients (Discord bots, Slack bots, CLI tools) connect here to interact with projects. ## Authentication All endpoints except /health, /ready, and /docs require authentication via API key. **Header**: ` + "`X-API-Key: rdev_sk_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`" + ` Or: ` + "`Authorization: Bearer rdev_sk_...`" + ` ### Getting Started 1. Set RDEV_ADMIN_KEY environment variable with your super admin key 2. Use the admin key to create additional keys via POST /keys 3. Use created keys for normal operations ### Scopes | Scope | Description | |-------|-------------| | projects:read | List and view projects | | projects:execute | Run commands (claude, shell, git) | | keys:read | List API keys (metadata only) | | keys:write | Create and revoke keys | | admin | Full access (all scopes) | ## Architecture - **rdev-api**: This Go service - **claudebox pods**: Isolated pods running Claude Code CLI - **postgres**: API key storage (auto-migrating) ## Streaming Command output is streamed via Server-Sent Events (SSE) at /projects/{id}/events. `). WithServer("http://localhost:8080", "Local development"). WithServer("http://rdev-api.rdev.svc:8080", "Kubernetes internal") // Tags spec.WithTag("Authentication", "API key management") spec.WithTag("Projects", "Project management and discovery") spec.WithTag("Commands", "Command execution (claude, shell, git)") spec.WithTag("Events", "Server-Sent Events for real-time output") spec.WithTag("Claude Config", "Manage commands, skills, and agents in /workspace/.claude/") spec.WithTag("System", "Health and readiness endpoints") // System endpoints spec.AddPath("/health", "get", api.Op( "Health check", "Returns health status. No authentication required.", "System", )) spec.AddPath("/ready", "get", api.Op( "Readiness check", "Returns readiness status. No authentication required.", "System", )) // Key management endpoints spec.AddPath("/keys", "get", withAuth( "List API keys", "Returns all API keys with metadata (not secrets). Requires keys:read scope.", "Authentication", "keys:read", `[ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "discord-bot", "key_prefix": "a1b2c3d4", "scopes": ["projects:read", "projects:execute"], "created_at": "2026-01-24T20:00:00Z", "active": true } ]`, )) spec.AddPath("/keys", "post", withAuthAndBody( "Create API key", `Creates a new API key. The secret is returned only once - save it securely! **Expiration options**: 30d, 60d, 90d, 1y, never (default: never)`, "Authentication", "keys:write", `{ "name": "discord-bot", "scopes": ["projects:read", "projects:execute"], "project_ids": ["pantheon"], "expires_in": "90d" }`, `{ "key": { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "discord-bot", "key_prefix": "a1b2c3d4", "scopes": ["projects:read", "projects:execute"], "project_ids": ["pantheon"], "created_at": "2026-01-24T20:00:00Z", "expires_at": "2026-04-24T20:00:00Z", "active": true }, "secret": "rdev_sk_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" }`, )) spec.AddPath("/keys/{id}", "get", withAuthAndParams( "Get API key", "Returns details for a specific API key. Requires keys:read scope.", "Authentication", "keys:read", []param{{Name: "id", In: "path", Description: "Key ID (UUID)", Required: true}}, )) spec.AddPath("/keys/{id}", "delete", withAuthAndParams( "Revoke API key", "Revokes an API key immediately. The key cannot be used after revocation. Requires keys:write scope.", "Authentication", "keys:write", []param{{Name: "id", In: "path", Description: "Key ID (UUID)", Required: true}}, )) // Projects - List and Get spec.AddPath("/projects", "get", withAuth( "List projects", "Returns all available projects (claudebox pods). Requires projects:read scope.", "Projects", "projects:read", `[ { "id": "pantheon", "name": "Pantheon", "description": "Go API backend", "pod": "claudebox-pantheon-0", "status": "running" } ]`, )) spec.AddPath("/projects/{id}", "get", withAuthAndParams( "Get project", "Returns details for a specific project. Requires projects:read scope.", "Projects", "projects:read", []param{{Name: "id", In: "path", Description: "Project ID (e.g., 'pantheon')", Required: true}}, )) // Commands spec.AddPath("/projects/{id}/claude", "post", withAuthBodyAndParams( "Run Claude command", "Executes a Claude Code prompt in the project's claudebox pod. Requires projects:execute scope.", "Commands", "projects:execute", []param{{Name: "id", In: "path", Description: "Project ID", Required: true}}, `{ "prompt": "fix the bug in auth handler", "stream_id": "optional-correlation-id" }`, `{ "id": "cmd-pantheon-001", "project": "pantheon", "type": "claude", "status": "queued", "stream_url": "/projects/pantheon/events?stream_id=cmd-pantheon-001" }`, )) spec.AddPath("/projects/{id}/shell", "post", withAuthBodyAndParams( "Run shell command", "Executes a shell command in the project's claudebox pod. Requires projects:execute scope.", "Commands", "projects:execute", []param{{Name: "id", In: "path", Description: "Project ID", Required: true}}, `{ "command": "go test ./...", "stream_id": "optional-correlation-id" }`, `{ "id": "cmd-pantheon-002", "project": "pantheon", "type": "shell", "status": "queued", "stream_url": "/projects/pantheon/events?stream_id=cmd-pantheon-002" }`, )) spec.AddPath("/projects/{id}/git", "post", withAuthBodyAndParams( "Run git command", "Executes a git command in the project's claudebox pod. Requires projects:execute scope.", "Commands", "projects:execute", []param{{Name: "id", In: "path", Description: "Project ID", Required: true}}, `{ "args": ["status"], "stream_id": "optional-correlation-id" }`, `{ "id": "cmd-pantheon-003", "project": "pantheon", "type": "git", "status": "queued", "stream_url": "/projects/pantheon/events?stream_id=cmd-pantheon-003" }`, )) // SSE Events spec.AddPath("/projects/{id}/events", "get", map[string]any{ "summary": "Stream events", "description": `Server-Sent Events stream for real-time command output. Requires projects:read scope. ## Event Types - **connected**: Initial connection confirmation - **output**: Command output (stdout or stderr) - **error**: Error occurred during execution - **complete**: Command finished (includes exit_code and duration_ms) - **heartbeat**: Keep-alive (sent every 30s) ## Example ` + "```javascript" + ` const events = new EventSource('/projects/pantheon/events?stream_id=cmd-001', { headers: { 'X-API-Key': 'rdev_sk_...' } }); events.addEventListener('output', (e) => { const data = JSON.parse(e.data); console.log(data.line); }); events.addEventListener('complete', (e) => { const data = JSON.parse(e.data); console.log('Done:', data.exit_code); events.close(); }); ` + "```", "tags": []string{"Events"}, "security": []map[string]any{ {"ApiKeyAuth": []string{}}, }, "parameters": []map[string]any{ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": map[string]any{"type": "string"}, }, { "name": "stream_id", "in": "query", "description": "Command ID to filter events (optional)", "required": false, "schema": map[string]any{"type": "string"}, }, }, "responses": map[string]any{ "200": map[string]any{ "description": "SSE stream", "content": map[string]any{ "text/event-stream": map[string]any{ "schema": map[string]any{ "type": "string", "example": "event: output\ndata: {\"line\": \"Building...\", \"stream\": \"stdout\"}\n\n", }, }, }, }, }, }) // Claude Config - Overview spec.AddPath("/projects/{id}/claude-config", "get", withAuthAndParams( "Get config overview", `Returns an overview of the project's Claude config (/workspace/.claude/). Lists available commands, skills, and agents. Requires projects:read scope.`, "Claude Config", "projects:read", []param{{Name: "id", In: "path", Description: "Project ID", Required: true}}, )) // Claude Config - Commands spec.AddPath("/projects/{id}/claude-config/commands", "get", withAuthAndParams( "List commands", "Lists all custom commands in /workspace/.claude/commands/. Requires projects:read scope.", "Claude Config", "projects:read", []param{{Name: "id", In: "path", Description: "Project ID", Required: true}}, )) spec.AddPath("/projects/{id}/claude-config/commands", "post", withAuthBodyAndParams( "Create command", `Creates a new custom command in /workspace/.claude/commands/{name}.md. Commands are markdown files with frontmatter. Requires projects:execute scope.`, "Claude Config", "projects:execute", []param{{Name: "id", In: "path", Description: "Project ID", Required: true}}, `{ "name": "deploy", "content": "---\ndescription: Deploy to production\n---\n\nRun the deployment..." }`, `{ "name": "deploy", "type": "commands", "content": "---\ndescription: Deploy to production\n---\n\nRun the deployment..." }`, )) spec.AddPath("/projects/{id}/claude-config/commands/{name}", "get", withAuthAndParams( "Get command", "Returns a specific command's content. Requires projects:read scope.", "Claude Config", "projects:read", []param{ {Name: "id", In: "path", Description: "Project ID", Required: true}, {Name: "name", In: "path", Description: "Command name", Required: true}, }, )) spec.AddPath("/projects/{id}/claude-config/commands/{name}", "put", withAuthBodyAndParams( "Update command", "Updates a command's content. Requires projects:execute scope.", "Claude Config", "projects:execute", []param{ {Name: "id", In: "path", Description: "Project ID", Required: true}, {Name: "name", In: "path", Description: "Command name", Required: true}, }, `{ "content": "---\ndescription: Updated description\n---\n\nUpdated content..." }`, `{ "name": "deploy", "type": "commands", "content": "---\ndescription: Updated description\n---\n\nUpdated content..." }`, )) spec.AddPath("/projects/{id}/claude-config/commands/{name}", "delete", withAuthAndParams( "Delete command", "Deletes a command. Requires projects:execute scope.", "Claude Config", "projects:execute", []param{ {Name: "id", In: "path", Description: "Project ID", Required: true}, {Name: "name", In: "path", Description: "Command name", Required: true}, }, )) // Claude Config - Skills (same pattern as commands) spec.AddPath("/projects/{id}/claude-config/skills", "get", withAuthAndParams( "List skills", "Lists all skills in /workspace/.claude/skills/. Requires projects:read scope.", "Claude Config", "projects:read", []param{{Name: "id", In: "path", Description: "Project ID", Required: true}}, )) spec.AddPath("/projects/{id}/claude-config/skills", "post", withAuthBodyAndParams( "Create skill", "Creates a new skill. Requires projects:execute scope.", "Claude Config", "projects:execute", []param{{Name: "id", In: "path", Description: "Project ID", Required: true}}, `{"name": "go-testing", "content": "# Go Testing Skill\n\n..."}`, `{"name": "go-testing", "type": "skills", "content": "# Go Testing Skill\n\n..."}`, )) spec.AddPath("/projects/{id}/claude-config/skills/{name}", "get", withAuthAndParams( "Get skill", "Returns a specific skill's content. Requires projects:read scope.", "Claude Config", "projects:read", []param{ {Name: "id", In: "path", Description: "Project ID", Required: true}, {Name: "name", In: "path", Description: "Skill name", Required: true}, }, )) spec.AddPath("/projects/{id}/claude-config/skills/{name}", "put", withAuthBodyAndParams( "Update skill", "Updates a skill's content. Requires projects:execute scope.", "Claude Config", "projects:execute", []param{ {Name: "id", In: "path", Description: "Project ID", Required: true}, {Name: "name", In: "path", Description: "Skill name", Required: true}, }, `{"content": "# Updated Skill\n\n..."}`, `{"name": "go-testing", "type": "skills", "content": "# Updated Skill\n\n..."}`, )) spec.AddPath("/projects/{id}/claude-config/skills/{name}", "delete", withAuthAndParams( "Delete skill", "Deletes a skill. Requires projects:execute scope.", "Claude Config", "projects:execute", []param{ {Name: "id", In: "path", Description: "Project ID", Required: true}, {Name: "name", In: "path", Description: "Skill name", Required: true}, }, )) // Claude Config - Agents (same pattern) spec.AddPath("/projects/{id}/claude-config/agents", "get", withAuthAndParams( "List agents", "Lists all agents in /workspace/.claude/agents/. Requires projects:read scope.", "Claude Config", "projects:read", []param{{Name: "id", In: "path", Description: "Project ID", Required: true}}, )) spec.AddPath("/projects/{id}/claude-config/agents", "post", withAuthBodyAndParams( "Create agent", "Creates a new agent. Requires projects:execute scope.", "Claude Config", "projects:execute", []param{{Name: "id", In: "path", Description: "Project ID", Required: true}}, `{"name": "code-reviewer", "content": "# Code Reviewer Agent\n\n..."}`, `{"name": "code-reviewer", "type": "agents", "content": "# Code Reviewer Agent\n\n..."}`, )) spec.AddPath("/projects/{id}/claude-config/agents/{name}", "get", withAuthAndParams( "Get agent", "Returns a specific agent's content. Requires projects:read scope.", "Claude Config", "projects:read", []param{ {Name: "id", In: "path", Description: "Project ID", Required: true}, {Name: "name", In: "path", Description: "Agent name", Required: true}, }, )) spec.AddPath("/projects/{id}/claude-config/agents/{name}", "put", withAuthBodyAndParams( "Update agent", "Updates an agent's content. Requires projects:execute scope.", "Claude Config", "projects:execute", []param{ {Name: "id", In: "path", Description: "Project ID", Required: true}, {Name: "name", In: "path", Description: "Agent name", Required: true}, }, `{"content": "# Updated Agent\n\n..."}`, `{"name": "code-reviewer", "type": "agents", "content": "# Updated Agent\n\n..."}`, )) spec.AddPath("/projects/{id}/claude-config/agents/{name}", "delete", withAuthAndParams( "Delete agent", "Deletes an agent. Requires projects:execute scope.", "Claude Config", "projects:execute", []param{ {Name: "id", In: "path", Description: "Project ID", Required: true}, {Name: "name", In: "path", Description: "Agent name", Required: true}, }, )) return spec } // param represents an OpenAPI parameter. type param struct { Name string In string Description string Required bool } // withAuth creates an operation that requires authentication. func withAuth(summary, description, tag, scope, example string) map[string]any { return map[string]any{ "summary": summary, "description": description + "\n\n**Required scope**: `" + scope + "`", "tags": []string{tag}, "security": []map[string]any{ {"ApiKeyAuth": []string{}}, }, "responses": map[string]any{ "200": map[string]any{ "description": "Success", "content": map[string]any{ "application/json": map[string]any{ "example": example, }, }, }, "401": map[string]any{"description": "Unauthorized - Missing or invalid API key"}, "403": map[string]any{"description": "Forbidden - Insufficient permissions"}, }, } } // withAuthAndBody creates an operation with auth and request body. func withAuthAndBody(summary, description, tag, scope, requestExample, responseExample string) map[string]any { return map[string]any{ "summary": summary, "description": description + "\n\n**Required scope**: `" + scope + "`", "tags": []string{tag}, "security": []map[string]any{ {"ApiKeyAuth": []string{}}, }, "requestBody": map[string]any{ "required": true, "content": map[string]any{ "application/json": map[string]any{ "example": requestExample, }, }, }, "responses": map[string]any{ "201": map[string]any{ "description": "Created", "content": map[string]any{ "application/json": map[string]any{ "example": responseExample, }, }, }, "400": map[string]any{"description": "Bad Request - Invalid input"}, "401": map[string]any{"description": "Unauthorized - Missing or invalid API key"}, "403": map[string]any{"description": "Forbidden - Insufficient permissions"}, }, } } // withAuthAndParams creates an operation with auth and path parameters. func withAuthAndParams(summary, description, tag, scope string, params []param) map[string]any { parameters := make([]map[string]any, len(params)) for i, p := range params { parameters[i] = map[string]any{ "name": p.Name, "in": p.In, "description": p.Description, "required": p.Required, "schema": map[string]any{"type": "string"}, } } return map[string]any{ "summary": summary, "description": description + "\n\n**Required scope**: `" + scope + "`", "tags": []string{tag}, "security": []map[string]any{ {"ApiKeyAuth": []string{}}, }, "parameters": parameters, "responses": map[string]any{ "200": map[string]any{"description": "Success"}, "401": map[string]any{"description": "Unauthorized - Missing or invalid API key"}, "403": map[string]any{"description": "Forbidden - Insufficient permissions"}, "404": map[string]any{"description": "Not Found"}, }, } } // withAuthBodyAndParams creates an operation with auth, body, and params. func withAuthBodyAndParams(summary, description, tag, scope string, params []param, requestExample, responseExample string) map[string]any { parameters := make([]map[string]any, len(params)) for i, p := range params { parameters[i] = map[string]any{ "name": p.Name, "in": p.In, "description": p.Description, "required": p.Required, "schema": map[string]any{"type": "string"}, } } return map[string]any{ "summary": summary, "description": description + "\n\n**Required scope**: `" + scope + "`", "tags": []string{tag}, "security": []map[string]any{ {"ApiKeyAuth": []string{}}, }, "parameters": parameters, "requestBody": map[string]any{ "required": true, "content": map[string]any{ "application/json": map[string]any{ "example": requestExample, }, }, }, "responses": map[string]any{ "201": map[string]any{ "description": "Created", "content": map[string]any{ "application/json": map[string]any{ "example": responseExample, }, }, }, "400": map[string]any{"description": "Bad Request - Invalid input"}, "401": map[string]any{"description": "Unauthorized - Missing or invalid API key"}, "403": map[string]any{"description": "Forbidden - Insufficient permissions"}, }, } }