If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/flynn/flynn shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 5y ago

• 3 active contributors
• BSD-3-Clause licensed
• Tests present
• ⚠ Stale — last commit 5y ago
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 52% of recent commits
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live flynn/flynn repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/flynn/flynn.

What it runs against: a local clone of flynn/flynn — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in flynn/flynn | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-3-Clause | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1736 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of flynn/flynn. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/flynn/flynn.git
#   cd flynn
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of flynn/flynn and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "flynn/flynn(\\.git)?\\b" \\
  && ok "origin remote is flynn/flynn" \\
  || miss "origin remote is not flynn/flynn (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-3-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-3-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-3-Clause" \\
  || miss "license drift — was BSD-3-Clause at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "bootstrap/bootstrap.go" \\
  && ok "bootstrap/bootstrap.go" \\
  || miss "missing critical file: bootstrap/bootstrap.go"
test -f "blobstore/blobstore.go" \\
  && ok "blobstore/blobstore.go" \\
  || miss "missing critical file: blobstore/blobstore.go"
test -f "appliance/postgresql/handler.go" \\
  && ok "appliance/postgresql/handler.go" \\
  || miss "missing critical file: appliance/postgresql/handler.go"
test -f "appliance/redis/client.go" \\
  && ok "appliance/redis/client.go" \\
  || miss "missing critical file: appliance/redis/client.go"
test -f "blobstore/backend/backend.go" \\
  && ok "blobstore/backend/backend.go" \\
  || miss "missing critical file: blobstore/backend/backend.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1736 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1706d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/flynn/flynn"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Flynn is an unmaintained next-generation open source Platform-as-a-Service (PaaS) written primarily in Go that provided container orchestration, service management, and multi-database appliance support (PostgreSQL, MongoDB, MariaDB). It abstracted away infrastructure complexity to let developers deploy applications without managing servers, similar to Heroku but self-hosted. Monorepo organized into appliance/ (database services: postgresql/, mongodb/, mariadb/ each with cmd/, img/, and handler patterns) and root-level service binaries. Database appliances follow a consistent pattern: cmd/ contains service entry points (e.g., appliance/postgresql/cmd/flynn-postgres), handler.go implements API logic, process.go manages instance lifecycle, and img/ holds Docker build artifacts.

DevOps engineers and platform teams who wanted to run a self-hosted PaaS on their own infrastructure; developers seeking a Heroku-like experience without vendor lock-in. No longer recommended for new deployments due to unmaintained status.

ABANDONED. The project explicitly states it is no longer being developed and no longer receives security updates. The Go version is pinned to 1.13 (released Nov 2019), all public infrastructure (binary hosting, cluster discovery) has been shut down, and the README directs users to transition to alternative systems immediately.

CRITICAL: Do not use in production. The codebase is unmaintained with no security patches, uses Go 1.13 (5+ years old), depends on deprecated Azure SDK and other stale libraries, and provides zero forward compatibility guarantees. No active CI/CD visible; migration away is the only responsible path.

Nothing. Project is archived. No active development, PRs, or issues are being addressed. The repository is preserved for historical reference only.

This project cannot be reliably started. Dependencies are outdated, infrastructure is gone, and security vulnerabilities are unpatched. For historical curiosity only: git clone https://github.com/flynn/flynn.git && cd flynn && cat Makefile (project uses Make for builds, not Go modules alone). Do not attempt to run in any environment connected to production or untrusted networks.

Daily commands: Do not run this in any real environment. Historical reference only: make (see Makefile for build targets), but binary execution requires deprecated external services (cluster discovery, binary hosting—all shut down). Vagrant file exists (Vagrantfile) suggesting local VM testing was supported, but VirtualBox/Vagrant configuration is likely obsolete.

• bootstrap/bootstrap.go — Core bootstrap orchestration that initializes Flynn clusters with declarative action sequences; essential for understanding platform initialization.
• blobstore/blobstore.go — Central blob storage abstraction supporting multiple backends (S3, Azure, GCS); critical for application artifact management.
• appliance/postgresql/handler.go — PostgreSQL appliance API handler demonstrating the pattern for database service provisioning used across all appliances.
• appliance/redis/client.go — Redis client wrapper showing how Flynn manages in-memory data services and state persistence.
• blobstore/backend/backend.go — Storage backend interface defining the contract for pluggable storage providers (S3, Azure, GCS, PostgreSQL, Minio).
• Makefile — Build orchestration that compiles Go binaries for multiple appliances and services; defines the build pipeline.

Add a new database appliance

1. Create appliance directory structure under appliance/<dbname>/ with handler.go, process.go, cmd subdirectories (appliance/postgresql/handler.go)
2. Implement HTTP API handlers for provisioning, replication, and backup following the pattern in handler.go (appliance/postgresql/handler.go)
3. Implement process lifecycle management (start, stop, health checks) in process.go (appliance/postgresql/process.go)
4. Create CLI entry points in cmd/<dbname>/main.go and cmd/<dbname>-api/main.go (appliance/postgresql/cmd/flynn-postgres/main.go)
5. Add container image build rules in appliance/<dbname>/img/packages.sh and Makefile (Makefile)
6. Register bootstrap actions in bootstrap/bootstrap.go for service initialization (bootstrap/bootstrap.go)

Add a new blob storage backend

1. Implement the Backend interface defined in blobstore/backend/backend.go (blobstore/backend/backend.go)
2. Create provider-specific implementation file (e.g., blobstore/backend/<provider>.go) following S3 pattern (blobstore/backend/s3.go)
3. Add backend initialization in blobstore/blobstore.go's NewBlobstore factory method (blobstore/blobstore.go)
4. Update bootstrap configuration to include backend selection in manifest_template.json (bootstrap/manifest_template.json)

Add a bootstrap initialization action

1. Create action file following naming convention bootstrap/<action_type>_action.go (see deploy_app_action.go) (bootstrap/deploy_app_action.go)
2. Implement the Action interface with Execute method for cluster setup logic (bootstrap/deploy_app_action.go)
3. Register action in bootstrap/bootstrap.go's action dispatcher and sequencing logic (bootstrap/bootstrap.go)
4. Add action definition to bootstrap/manifest_template.json for declarative configuration (bootstrap/manifest_template.json)

Add service state persistence

1. Define state serialization in appliance/<service>/state.go following redis/state.go pattern (appliance/redis/state.go)
2. Implement dump/restore operations in appliance/<service>/dump.sh and restore.sh scripts (appliance/redis/dump.sh)
3. Integrate state handlers in appliance/<service>/handler.go backup endpoints (appliance/postgresql/handler.go)
4. Update process lifecycle in appliance/<service>/process.go to handle state recovery on startup (appliance/postgresql/process.go)

• Go — Compiled language providing fast execution, single-binary deployment, and strong concurrency support for distributed services.
• PostgreSQL/MongoDB/MariaDB/Redis — Battle-tested data services packaged as pluggable appliances to provide infrastructure primitives for hosted applications.
• Multi-backend blob storage (S3/Azure/GCS) — Abstraction layer prevents vendor lock-in and enables deployment across cloud providers and on-premise object storage.
• Declarative bootstrap manifests (JSON) — Infrastructure-as-code approach enables reproducible cluster initialization and version control of cluster configurations.
• Container images + Vagrant — Appliances packaged as containers with Vagrant for local development consistency.

• Appliance processes run as daemons rather than orchestrated by external container runtime

  • Why: Simpler deployment model for the era (pre-Kubernetes dominance); tight control over process lifecycle and state management.
  • Consequence: No automatic failover or horizontal scaling at the infrastructure layer; requires manual process management and replication logic in appliance code.

• Synchronous HTTP APIs for service provisioning rather than event-driven async

  • Why: Simpler mental model for bootstrap sequencing; immediate visibility of provisioning success/failure.
  • Consequence: Blocking sequential operations during cluster initialization; longer bootstrap times for large clusters; harder to parallelize independent operations.

• State serialized to dump files rather than distributed consensus (Raft/Paxos)

  • Why: Reduces complexity and eliminates external consensus dependencies; easier to understand recovery semantics
  • Consequence: undefined

Critical: (1) No public infrastructure—cluster discovery and binary hosting are permanently shut down; binaries cannot be downloaded or discovered. (2) Go 1.13 is EOL; compilation on modern Go versions will fail due to breaking changes and deprecated imports (e.g., Azure SDK). (3) Database appliances expect specific container environments and systemd integration not present in standard Docker/Kubernetes. (4) MAINTAINERS file may list contact info but project is unfixable; reported issues will not be resolved. (5) TUP build system (Tupfile.ini) is non-standard and requires explicit installation; most developers expect only Make.

• Appliance Pattern — Flynn abstracts stateful services (databases) as 'appliances' with consistent handler/process/cmd structure; understanding this pattern is essential to comprehending how Flynn managed database lifecycle without losing data
• WAL (Write-Ahead Logging) — PostgreSQL and MongoDB appliances use WAL recovery (pgxlog, mdbxlog modules) for crash resilience and backup consistency; critical for understanding data durability in Flynn
• Container Orchestration via Git Push — Flynn's UX was 'git push' to deploy (like Heroku); internal architecture translated this into container scheduling, service discovery, and routing—a design pattern abandoned in favor of explicit Kubernetes manifests
• BoltDB Persistence — Flynn used BoltDB (embedded key-value store) for metadata and configuration; examining boltdb usage reveals how Flynn stored appliance state without external databases
• Service Discovery & DNS — Flynn appliances had to be discoverable and routable within a cluster; understanding how services registered themselves is key to decoding the networking layer (now non-functional post-shutdown)
• Replication Sets (MongoDB) — MongoDB appliance implements replica set management (replset.go) for high availability; learning this shows how Flynn managed stateful service HA
• DSN (Data Source Name) Parsing — MariaDB appliance parses and manages DSNs (dsn.go) to abstract connection details; understanding DSN handling is crucial for database appliance configuration

• hashicorp/nomad — Modern container orchestration platform solving the same scheduling problem Flynn addressed; active alternative for self-hosted workload management
• kubernetes/kubernetes — Became the industry standard for container orchestration; most Flynn users have migrated to Kubernetes
• dokku/dokku — Lightweight self-hosted PaaS alternative inspired by Heroku; actively maintained and lower operational overhead than Flynn
• flynn/go-check — Flynn's own testing library (dependency in go.mod); used internally for test assertions across the codebase
• coreos/etcd — Distributed configuration and service discovery system; Flynn relied on similar patterns for cluster coordination (now archived/shut down)

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for appliance database handlers

The appliance modules (mariadb, mongodb, postgresql, redis) have handler.go files but only sparse test coverage. appliance/mariadb/process_test.go and appliance/mongodb/process_test.go exist, but handler.go files across all databases lack tests. This is critical for a PaaS that manages stateful services—handler bugs could cause data loss. A contributor could add test coverage for database-specific handler logic (backup/restore, replication, failover).

• [ ] Create appliance/mariadb/handler_test.go with tests for DSN generation and connection pooling in handler.go
• [ ] Create appliance/mongodb/handler_test.go with tests for replica set initialization and dump/restore operations
• [ ] Create appliance/postgresql/handler_test.go with tests for WAL archiving and recovery operations in handler.go
• [ ] Create appliance/redis/handler_test.go with tests for AOF/RDB persistence triggers
• [ ] Ensure tests cover error cases and edge cases (connection failures, corrupted backups, etc.)

Add GitHub Actions CI workflow for Go module validation and build verification

The repo has a Makefile and Tupfile.ini but no modern CI configuration (no .github/workflows). The go.mod shows go 1.13 (outdated) with numerous indirect dependencies. A contributor should add a GitHub Actions workflow to validate the module state, run go vet/gofmt, and verify builds succeed. This prevents dependency drift and catches build regressions early, especially important for an unmaintained project to catch bitrot.

• [ ] Create .github/workflows/go-build.yml with jobs for: go mod tidy validation, go vet, gofmt checks, and test execution
• [ ] Include matrix testing across Go 1.13+ versions to identify minimum compatibility
• [ ] Add go build ./cmd/... to verify all appliance API binaries compile
• [ ] Document the workflow in CONTRIBUTING.md with instructions for local pre-commit validation

Create missing integration tests for appliance process lifecycle management

Files like appliance/postgresql/process.go, appliance/mongodb/process.go, and appliance/redis/process.go manage critical lifecycle operations (start, stop, status) but have minimal or no test coverage beyond process_test.go in a few modules. These process managers are foundational to the Flynn scheduler. Tests should verify process startup, graceful shutdown, state persistence, and recovery after crashes.

• [ ] Create appliance/postgresql/process_test.go with tests for: process start with config, graceful shutdown, WAL xlog state recovery (appliance/postgresql/pgxlog/pgxlog.go)
• [ ] Create appliance/redis/process_test.go covering: start with persistence (dump.sh/restore.sh), state.go snapshot recovery, and AOF rewrite handling
• [ ] Create appliance/mariadb/process_test.go (expand existing) with tests for mdbxlog recovery and binlog management
• [ ] Create appliance/mongodb/process_test.go (expand existing) with replica set process lifecycle and xlog/xlog.go recovery
• [ ] Use mock file systems and process stubs to avoid requiring real database binaries in tests

• Document migration paths: The README directs users to 'transition to another system' but provides no concrete guidance. A wiki page or MIGRATION.md with side-by-side comparisons to Kubernetes, OpenShift, and Dokku would help archival users plan exits.
• Add ARCHITECTURE.md: No diagram or prose explanation exists for how the appliance pattern works or how services communicate. Document the handler→process→cmd flow with examples from PostgreSQL and MongoDB.
• Expand test coverage for appliance processes: Files like appliance/mariadb/process.go and appliance/mongodb/process.go have minimal test coverage; write integration tests for instance lifecycle (start→verify→stop) to preserve institutional knowledge before code rots further.

• Critical · Project is Unmaintained and Unsupported — Repository root - README.md. Flynn is officially unmaintained and no longer receives security updates. The README explicitly states 'Flynn is no longer being developed' and 'Flynn no longer receives security updates, we strongly recommend transitioning to another system as soon as possible.' All public infrastructure has been shut down. Fix: Migrate to an actively maintained PaaS platform immediately. Do not use Flynn in production or for any security-sensitive applications.
• Critical · Severely Outdated Go Dependencies — go.mod. The go.mod file specifies go 1.13 (released Sept 2019) with extremely outdated dependencies. Many dependencies use versions from 2015-2017 with no version constraints, making them vulnerable to known CVEs. Examples: aws-sdk-go from 2017, azure-sdk from 2016, boltdb with known vulnerabilities. Fix: Update all dependencies to latest versions. Enable Go module version constraints. However, given the project is unmaintained, this is impractical - do not use this codebase.
• High · Multiple Known Vulnerable Dependencies — go.mod - multiple dependency entries. Several dependencies are known to have security vulnerabilities: boltdb/bolt (v1.3.1) has issues with concurrent access; old aws-sdk-go and azure-sdk versions contain multiple CVEs; golang/protobuf v1.4.1 is outdated; gorilla/securecookie from 2014 predates modern security practices. Fix: Upgrade to patched versions of all dependencies. For unmaintained projects, conduct a full security audit before any use.
• High · Unvetted Custom Flynn Packages — go.mod - multiple github.com/flynn/* dependencies. The codebase uses custom Flynn-maintained packages (github.com/flynn/go-check, flynn/go-docopt, flynn/go-p9p, flynn/que-go, flynn/tail, flynn/go-tuf) from potentially unmaintained repositories. These receive no external security audits. Fix: Review all custom Flynn packages for security issues. Replace with actively maintained alternatives from the community.
• High · Credential and Secret Exposure Risk in Database Handlers — appliance/mariadb/dsn.go, appliance/*/handler.go files. Database handler files (appliance/*/handler.go) likely contain database connection logic that may expose credentials. DSN files (appliance/mariadb/dsn.go) process connection strings that may contain passwords. No evidence of secure credential management patterns. Fix: Implement secure credential management using environment variables or secret vaults. Never hardcode credentials. Sanitize DSN strings before logging.
• Medium · SQL Query Construction Risk — appliance/mariadb/handler.go, appliance/postgresql/handler.go, appliance/mongodb/handler.go. Database handler files across multiple appliances (mariadb, postgresql, mongodb) lack visible parameterization patterns. Risk of SQL injection if queries are constructed dynamically without proper parameterization. Fix: Ensure all database queries use parameterized statements. Conduct code review of all query construction patterns. Use ORM libraries with built-in protection.
• Medium · Process and Shell Script Injection Risks — appliance/mariadb/process.go, appliance/mongodb/process.go, appliance/postgresql/process.go, appliance/redis/process.go, and associated .sh scripts. Multiple shell scripts (appliance/*/start.sh, dump.sh, restore.sh) and Go process files (process.go) execute system commands. Without proper input validation, these are vulnerable to command injection attacks. Fix: Use Go's os/exec package with argument arrays instead of shell string concatenation. Never pass unsanitized user input to shell commands. Validate all inputs before execution.
• Medium · Unsafe File Operations — blobstore/backend/redirect_file_stream.go, appliance/*/dump.sh, appliance/*/restore.sh. File operations in backup/restore scripts and redirect_file_stream.go lack proper validation. Risk of directory traversal attacks if user-controlled input is used in file paths. Fix: Validate all file paths against whitelist.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.