Declarative GitOps control plane for GoClaw deployments.
GCPlane manages GoClaw resources — agents, providers, channels, MCP servers, cron jobs, and agent teams — through YAML manifests with a reconcile-and-converge model.
- Declarative manifests — k8s-style YAML with camelCase keys
- Plan → Apply — preview changes before applying
- Serve mode — continuous reconciliation with health/metrics endpoints
- Git source — watch a git repo for manifest changes (GitOps)
- Prune — safely delete resources removed from manifest (
--prune) - Reference validation — catch broken cross-resource references before apply
- Export — dump live GoClaw state as manifest YAML
- Diff — detect drift between manifest and live state
- Pluggable providers — built for GoClaw (and extensible to any xClaw exposed API)
- Multi-platform — Linux, macOS, Windows (amd64/arm64)
┌─────────────────────────────────────────────────────────────┐
│ YAML Manifest (camelCase) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Provider │ │ Agent │ │ Channel │ │ MCPServer│ ... │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└───────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ GCPlane Engine │
│ │
│ ┌────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ Validate │→ │ Reconcile │→ │ Apply (Create/ │ │
│ │ (refs + │ │ (Observe → │ │ Update/Delete) │ │
│ │ schema) │ │ Compare) │ │ │ │
│ └────────────┘ └──────────────┘ └──────────────────────┘ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ Key Translation │ │ Source (File / Git repo) │ │
│ │ camelCase ↔ snake │ │ SHA256 / commit hash skip │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
└───────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ GoClaw Instance │
│ HTTP REST API (:18790) + WebSocket RPC v3 │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │Providers │ │ Agents │ │Channels │ │MCP/Teams │ │
│ │(13+ LLM) │ │(AI bots) │ │(TG/Slack)│ │(tools) │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ▼ │
│ PostgreSQL │
└─────────────────────────────────────────────────────────────┘
┌──────────┐ ┌────────────┐ ┌──────────────┐
│ Git Repo │────▶│ Controller │────▶│ GoClaw API │
│ or File │ │ (30s loop) │ │ │
└──────────┘ └─────┬──────┘ └──────────────┘
│
┌─────▼──────┐
│ HTTP Server│
│ :8480 │
│ │
│ /healthz │
│ /readyz │
│ /metrics │
│ /status │
│ /sync │
└────────────┘
# One-liner (auto-detects OS/arch)
curl -fsSL https://raw.githubusercontent.com/dataplanelabs/gcplane/main/install.sh | sh
# Specific version
curl -fsSL https://raw.githubusercontent.com/dataplanelabs/gcplane/main/install.sh | sh -s -- --version v0.6.1
# Or via Go
go install github.com/dataplanelabs/gcplane@latest# Create manifest
cat > manifest.yaml << 'EOF'
apiVersion: gcplane.io/v1
kind: Manifest
metadata:
name: my-setup
connection:
endpoint: http://localhost:18790
token: ${GOCLAW_TOKEN}
resources:
- kind: Provider
name: anthropic
spec:
displayName: "Anthropic"
providerType: anthropic_native
apiBase: https://api.anthropic.com
apiKey: ${ANTHROPIC_API_KEY}
enabled: true
- kind: Agent
name: assistant
spec:
displayName: "Assistant"
provider: anthropic
model: claude-sonnet-4-20250514
agentType: open
status: active
isDefault: true
EOF
# Preview → Apply
gcplane plan -f manifest.yaml
gcplane apply -f manifest.yaml| Command | Description |
|---|---|
validate |
Check manifest syntax + references (offline) |
plan |
Preview changes (dry-run) |
apply |
Apply manifest to GoClaw |
diff |
Show drift between manifest and live state |
export |
Dump live GoClaw state as manifest YAML |
serve |
Continuous reconciliation (GitOps mode) |
| Flag | Description |
|---|---|
-f, --file |
Manifest file or directory |
--prune |
Delete resources removed from manifest |
--auto-approve |
Skip confirmation prompt |
--repo |
Git repository URL (serve mode) |
--interval |
Reconciliation interval (default: 30s) |
| Kind | Description |
|---|---|
Provider |
LLM provider (Anthropic, OpenAI, Gemini, etc.) |
Agent |
AI agent with model, tools, and identity |
Channel |
Messaging channel (Telegram, Slack, Discord) |
MCPServer |
MCP tool server with agent grants |
CronJob |
Scheduled task |
AgentTeam |
Agent team (v1/v2 with notifications) |
Tool |
Custom tool definition |
Skill |
Agent skill (update only) |
TTSConfig |
Text-to-speech settings |
| Document | Description |
|---|---|
| Manifest Reference | Resource kinds, secrets, prune, serve endpoints |
| System Architecture | Package structure, data flow, design decisions |
| Tenant Structure | Multi-tenant deployment patterns |
| Usage Guide | Detailed command usage and examples |
| Project Roadmap | Release plan and future features |
| Code Standards | Development conventions |
# Setup (requires Docker for GoClaw)
cp .env.example .env # fill in credentials
mise run setup # start GoClaw + apply config
# Install git hooks
git config core.hooksPath .githooks
# Test
mise run test # unit tests
mise run test:e2e # full e2e (reset + plan + apply + serve)
# Serve (continuous reconciliation)
mise run serve| GCPlane | GoClaw | Tested |
|---|---|---|
| v0.7.x+ | 2.x | CI E2E |
GCPlane is tested against GoClaw v2.x in CI. The E2E workflow spins up GoClaw via ghcr.io/nextlevelbuilder/goclaw:full with PostgreSQL and runs validate, plan, apply, diff, export, and destroy commands.
MIT