Remote Controller

Remote Controller is a durable remote command execution platform with three components:

1. agent (Go daemon on managed hosts)
2. control-plane (Go gRPC server + PostgreSQL state)
3. console (Wails + Svelte 5 desktop shell)

The control path is agent-initiated so hosts behind NAT/firewalls can still be managed.

flowchart LR
    Operator["Operator (Desktop Console)"] -->|"Bearer token"| Control["Control Plane (gRPC API + Dispatcher)"]
    DB[("PostgreSQL")]
    Control <--> DB
    Agent1["Agent A"] -->|"mTLS gRPC ControlStream"| Control
    Agent2["Agent B"] -->|"mTLS gRPC ControlStream"| Control
    Control -->|"RunJob / CancelJob"| Agent1
    Control -->|"RunJob / CancelJob"| Agent2
    Agent1 -->|"Output + Status"| Control
    Agent2 -->|"Output + Status"| Control

Features implemented

1. Bidirectional gRPC control stream (AgentChannel.ControlStream).
2. Agent hello + heartbeat + reconnect backoff with jitter.
3. Command dispatch + output chunk persistence + terminal status tracking.
4. PostgreSQL migrations and typed store layer.
5. Command idempotency keys and server-side deduplication.
6. Agent checkpoint-based duplicate execution protection.
7. Dev token auth, RBAC role checks, and audit event persistence.
8. OIDC JWT validation support with dev-token fallback.
9. Health/readiness/metrics endpoints (/healthz, /readyz, /metrics).
10. Dev docker compose stack with generated mTLS certificates.
11. Console pages for agents, command submission/detail with output tail, and audit log listing.
12. Configurable output retention pruning (OUTPUT_RETENTION, default 168h).
13. Profile-driven builder for customized agent and remote-host binaries + deployment artifacts.
14. Secure-by-default control-plane startup (TLS required unless explicit dev-only insecure override).
15. Operational metrics for connected agents, dispatch queue depth, and command terminal outcomes.

Repository layout

• /proto protobuf contracts (buf based generation)
• /gen/proto generated gRPC/protobuf Go code
• /agent daemon implementation
• /control-plane API, stream server, dispatch, persistence
• /console Wails/Svelte frontend skeleton
• /deploy docker compose stack
• /builder profile-driven custom build tool
• /scripts development helpers
• /docs architecture/API/runbook/threat model

Quickstart

1. Generate protobuf code:

make proto

2. Run lint and tests:

make lint
make test

3. Start local stack (Postgres + control plane + one agent):

make dev-up

4. Verify health and metrics endpoints:

curl http://localhost:8080/healthz
curl http://localhost:8080/readyz
curl http://localhost:8080/metrics

5. Stop local stack:

make dev-down

6. Create and use a custom build profile:

make builder-init
# edit builder/profile.json (or start from builder/profile.example.json)
make builder-build-all

Builder outputs:

• build/<profile>/bin/remote-controller-agent
• build/<profile>/bin/control-plane
• build/<profile>/artifacts/agent/*
• build/<profile>/artifacts/remote-host/*

Windows build profiles (build.goos=windows) emit .exe binaries automatically.

Auth

Control API methods require a bearer token.

• Default dev token: dev-token
• Header: authorization: Bearer dev-token

OIDC mode:

• OIDC_ISSUER_URL=<issuer URL>
• OIDC_AUDIENCE=<client id/audience>
• Use bearer OIDC access token in authorization metadata.

TLS policy

The control plane is secure-by-default:

1. CA_CERT_FILE, SERVER_CERT_FILE, and SERVER_KEY_FILE are required.
2. Insecure mode is dev-only and must be explicitly enabled with CONTROL_PLANE_ALLOW_INSECURE_DEV=true or --allow-insecure-dev.
3. Secure mode enforces strict agent mTLS (RequireAndVerifyClientCert).
4. Presence liveness transitions are configurable with:
   • AGENT_STALE_AFTER (default 30s)
   • AGENT_OFFLINE_AFTER (default 2m, must exceed stale threshold)

Testing notes

control-plane/internal/store integration tests require Postgres.

• Set TEST_DATABASE_URL (or DATABASE_URL) to enable migration/idempotency integration tests.
• If unset, those tests skip.

Known limitations

1. Console UI uses polling for output tail and does not yet use push events.
2. Multi-session fanout and very large fleet optimizations are not implemented.