backplane

README

Backplane

Runtime Administration for High-Value Systems

Backplane is the Invisible Admin Panel for Go. It allows you to debug, configure, and rescue running applications via SSH, without the security risks of an HTTP admin dashboard.

Table of Contents

• Architecture
• Quick Start
• The Reflector Bridge
• Automation
• Production Patterns
• Security & Compliance
• Licensing

Prerequisites

Backplane strictly enforces standard SSH public key authentication.

• You must have a valid SSH key pair.
• Your public key (id_ed25519.pub or similar) must be present in ~/.ssh/authorized_keys on the host machine.
• If this file is missing, Backplane will deny all connections.

Architecture

Backplane operates on a strictly "Air Gapped" model. It binds a dedicated SSH server to 127.0.0.1, ensuring that administrative access is physically impossible from the public internet without prior host-level authorization.

• Zero-Allocation Logging: Uses a fixed-size ring buffer. It will never cause an OOM.
• Crash-Proof Isolation: The TUI runs in a distinct goroutine sandbox. A panic in the admin panel will never propagate to your main application loop.
• Standard SSH Auth: Leveraging ~/.ssh/authorized_keys, it respects your existing infrastructure security policies.

Running the Demo

To trigger the demo application (as seen in the GIF):

# 1. Run the demo server
go run examples/basic/main.go

# 2. In a separate terminal, SSH into it
ssh -p 2222 localhost

Integration

Backplane is not a framework. It is a library you import.

package main

import (
    "github.com/drskyle/backplane/pkg"
)

func main() {
    // 1. Initialize Default Options
    opts := pkg.DefaultOptions()

    // 2. Launch the Backplane (Non-blocking)
    stop, err := pkg.StartServer(opts)
    if err != nil {
        panic(err)
    }
    defer stop()

    // 3. Your Application Logic Here
    select {}
}

The Reflector Bridge

Modern applications require runtime reconfiguration. Backplane exposes thread-safe atomic types that bind directly to the TUI.

Old Way (Dangerous): Restarting the app to change a config.

Backplane Way:

package main

import (
"github.com/drskyle/backplane/pkg"
"github.com/drskyle/backplane/pkg/atomic"
)

// 1. Define variables as Atomic types (Thread-Safe)
var (
MaxConnections = atomic.NewInt(1000)
MaintenanceMode = atomic.NewBool(false)
LogLevel = atomic.NewString("INFO")
)

func main() {
// 2. Initialize Backplane
bp := pkg.New(pkg.DefaultOptions())

    // 3. One-line Registration (No internal imports!)
    bp.Expose("Max Connections", MaxConnections)
    bp.Expose("Maintenance Mode", MaintenanceMode)
    bp.Expose("Log Level", LogLevel)

    // 4. Start Server
    bp.Start()

    // Your app reads them safely at runtime:
    if MaintenanceMode.Load() {
        blockTraffic()
    }

}

No mutexes required. No race conditions.

Automation (Headless Mode)

You don't always want a TUI. Backplane supports Headless Mode for DevOps automation and shell scripting.

Get a value:

$ ssh -p 2222 localhost get MaxConnections
1000

Set a value (Instant Update):

$ ssh -p 2222 localhost set MaxConnections 2000
OK

List all exposed variables:

$ ssh -p 2222 localhost list
MaxConnections  = 2000
MaintenanceMode = false
LogLevel        = INFO

Production Patterns

Backplane isn't just a debugger; it's a control plane.

Use Case 1: The "Instant Maintenance" Switch

Need to stop traffic now to migrate a database? Don't redeploy. Just flip the switch.

In your code:

var Maintenance = atomic.NewBool(false)

func middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if Maintenance.Load() {
            http.Error(w, "Down for maintenance", 503)
            return
        }
        next.ServeHTTP(w, r)
    })
}

In the terminal:

ssh -p 2222 localhost set Maintenance true

Use Case 2: Zero-Config Prometheus Exporting

Since Backplane variables are standard atomics, you can read them directly in your metrics collectors.

prometheus.NewGaugeFunc(
    prometheus.GaugeOpts{Name: "app_max_conns"},
    func() float64 { return float64(MaxConnections.Load()) },
)

Change the value in the TUI -> Prometheus updates instantly.

Use Case 3: Dynamic Logging (Debug on Demand)

Stop spamming logs. Keep the level at ERROR by default. When an incident starts, switch to DEBUG instantly without restarting.

var LogLevel = atomic.NewString("ERROR")

func LogDebug(msg string) {
    if LogLevel.Load() == "DEBUG" {
        fmt.Println(msg)
    }
}

Compliance & Audit

Every modification made via Backplane is cryptographically attributed to the SSH key of the operator.

Audit logs are emitted to the configured io.Writer (defaults to stdout, but can be persisted to a file or explicit audit service).

[AUDIT] [2026-01-23T07:15:00Z] User 'alice' changed 'DB_Timeout' | OLD: 30s -> NEW: 10s

This persistent, immutable logging ensures full traceability for SOC2 / ISO27001 compliance.

Access

Once integrated, your application will listen on port 2222 (default). Access it using any standard SSH client:

ssh -p 2222 localhost

Licensing

Backplane is free software licensed under the GNU Affero General Public License v3.0 (AGPL v3).

If your application is proprietary, or if you cannot comply with the viral open-source requirements of the AGPL v3, you must purchase a Commercial License.

Commercial Licenses start at $2,000 / year / project.

For commercial licensing and proper indemnification, contact: drskyle8000@gmail.com