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/charmbracelet/soft-serve 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.

GO — Healthy across the board

• Last commit 3d ago
• 16 active contributors
• Distributed ownership (top contributor 38% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{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 charmbracelet/soft-serve repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/charmbracelet/soft-serve.

What it runs against: a local clone of charmbracelet/soft-serve — 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 charmbracelet/soft-serve | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 33 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of charmbracelet/soft-serve. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/charmbracelet/soft-serve.git
#   cd soft-serve
#
# 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 charmbracelet/soft-serve and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "cmd/soft/main.go" \\
  && ok "cmd/soft/main.go" \\
  || miss "missing critical file: cmd/soft/main.go"
test -f "cmd/soft/serve/server.go" \\
  && ok "cmd/soft/serve/server.go" \\
  || miss "missing critical file: cmd/soft/serve/server.go"
test -f "pkg/backend/backend.go" \\
  && ok "pkg/backend/backend.go" \\
  || miss "missing critical file: pkg/backend/backend.go"
test -f "pkg/config/config.go" \\
  && ok "pkg/config/config.go" \\
  || miss "missing critical file: pkg/config/config.go"
test -f "git/server.go" \\
  && ok "git/server.go" \\
  || miss "missing critical file: git/server.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 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
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/charmbracelet/soft-serve"
  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).

Soft Serve is a self-hostable Git server written in Go that runs entirely over SSH, providing a TUI interface for browsing and managing repositories without requiring a web browser. It supports cloning via SSH/HTTP/Git protocol, Git LFS, on-demand repo creation, and includes a command-line accessible UI for inspecting files, commits, and trees with syntax highlighting—essentially GitHub/GitLab but optimized for terminal-first workflows. Monolithic structure with cmd/soft/ containing entry points (main.go, serve/, admin/, browse/, hook/) and git/ package wrapping go-git/go-git/v5 for repository operations. SSH server implementation via charm.land/wish/v2 handles TUI transport in cmd/soft/serve/server.go; Git protocol operations delegated to git/ package (repo.go, command.go, server.go). Configuration and admin logic separated into cmd/soft/admin/admin.go.

DevOps engineers and developers who want to self-host Git infrastructure without the overhead of Gitea/GitLab, particularly those preferring SSH-native workflows and terminal UIs. Users of Charm's TUI ecosystem (bubbletea, bubbles, lipgloss) who want a batteries-included git server rather than building one from scratch.

Production-ready and actively maintained: 659KB of Go code with comprehensive CI/CD (build.yml, coverage.yml, goreleaser.yml, nightly.yml), clear release process via .goreleaser.yml, and structured package management (Dockerfile, .nfpm config for Debian/systemd). Recent dependencies on charm.land/bubbletea/v2 and charm.land/wish/v2 indicate ongoing active development aligned with Charm's ecosystem updates.

Low risk overall but worth noting: 659KB of Go in a single monorepo (no internal package segregation visible in top-level structure), heavy dependency on Charm's ecosystem (bubbles, bubbletea, wish, glamour, lipgloss—5+ direct charm.land deps) which concentrates risk on one maintainer group. Database layer uses jmoiron/sqlx with sqlite (modernc.org/sqlite) and PostgreSQL (lib/pq) support—ensure PostgreSQL is optional, not required for basic deployments.

Actively tracking Charm ecosystem updates (recent bubbletea/v2, wish/v2, lipgloss/v2 bumps visible in go.mod). Git LFS transfer support integrated via charmbracelet/git-lfs-transfer. Build infrastructure includes dependabot.yml for automated dependency checks and nightly builds. No specific major version bump indicators, suggesting incremental feature work and stability focus.

Clone the repo, build with Go 1.25.9+, and run:

git clone https://github.com/charmbracelet/soft-serve.git
cd soft-serve
go build ./cmd/soft
./soft serve  # starts SSH server on default port
# or
./soft browse [directory]  # browse local repos

Daily commands: Development: go run ./cmd/soft serve (binds SSH on :23231 by default, check cmd/soft/serve/serve.go for defaults). Production: build with go build ./cmd/soft && ./soft serve or use Docker (docker build -f Dockerfile .). SystemD service configuration in .nfpm/soft-serve.service for package installs.

• cmd/soft/main.go — Application entry point that initializes and starts the Soft Serve server; understand this first to see how all components are wired together.
• cmd/soft/serve/server.go — Core SSH server implementation that handles Git protocol negotiation and request routing; central to understanding client interactions.
• pkg/backend/backend.go — Main backend interface and implementation managing repositories, users, and access control; the heart of business logic.
• pkg/config/config.go — Configuration parsing and management; defines how the server is initialized and where settings come from.
• git/server.go — Git protocol handler implementing push/pull operations; critical for understanding repository operations.
• pkg/db/db.go — Database abstraction layer for persistence; essential for understanding data storage and retrieval patterns.
• pkg/access/access.go — Access control and permission checking system; fundamental to security and authorization.

Add a new Git operation (e.g., new command)

1. Create a new function in git/command.go that wraps the git command execution (git/command.go)
2. Add the operation handler in git/server.go within the appropriate request type case (git/server.go)
3. Wire the operation through pkg/backend/repo.go if it requires access control (pkg/backend/repo.go)

Add a new user/repository management feature

1. Add data model/migration in pkg/db/migrate/ (pkg/db/migrate/0001_create_tables.go)
2. Implement CRUD methods in pkg/backend/user.go or pkg/backend/repo.go (pkg/backend/repo.go)
3. Add access control rules in pkg/access/access.go (pkg/access/access.go)
4. Expose via admin command in cmd/soft/admin/admin.go (cmd/soft/admin/admin.go)

Add a new authentication mechanism

1. Add credential type to pkg/backend/auth.go (pkg/backend/auth.go)
2. Implement validation logic in pkg/backend/auth.go (pkg/backend/auth.go)
3. Integrate into SSH session setup in cmd/soft/serve/server.go (cmd/soft/serve/server.go)
4. Add configuration parsing in pkg/config/ssh.go if needed (pkg/config/ssh.go)

Add a new webhook event type

1. Define event type in pkg/backend/webhooks.go (pkg/backend/webhooks.go)
2. Trigger dispatch at the appropriate point (e.g., after push in git/server.go) (git/server.go)
3. Test webhook delivery in pkg/backend/webhooks.go (pkg/backend/webhooks.go)

• Go with Charm.sh libraries (Bubble Tea, Wish, Glamour, Lipgloss) — Provides fast, statically-compiled binary suitable for self-hosted scenarios; Charm libraries deliver modern TUI and terminal styling with minimal dependencies.
• SSH protocol (charm/ssh) for client communication — Enables seamless Git integration over SSH (standard for git push/pull), avoids HTTP overhead, leverages existing SSH keys; fits Unix philosophy.
• Go-git (go-git/go-git/v5) for Git operations — Pure Go implementation of Git protocol; no external git binary required, though git/command.go can shell out when needed for compatibility.
• Database abstraction (pkg/db) supporting SQL backends — Decouples storage from business logic; migrations support multiple SQL databases (PostgreSQL, SQLite); enables testing with in-memory implementations.
• Context-based access control (pkg/access/context.go) — Integrates permission checks into request handling without coupling; follows Go best practices for metadata propagation.

• Hybrid approach: Go-git library + optional git command shelling

  • Why: Go-git covers ~90% of operations efficiently; git binary fallback ensures compatibility with edge cases and custom hooks.
  • Consequence: Code must handle both paths; deployment may require git binary; adds complexity for edge-case handling.

• Single database abstraction layer supporting multiple backends

  • Why: Allows users to choose SQLite for simple deployments or PostgreSQL for HA; no vendor lock-in.
  • Consequence: Migrations must support multiple dialects; testing requires multiple database setups; SQL abstraction adds a layer of indirection.

• Synchronous webhook dispatch vs. async queue

  • Why: Simpler implementation for small self-hosted deployments; avoids external queue infrastructure.
  • Consequence: Slow or failing webhooks can block push operations; no retry or dead-letter handling; not suitable for high-throughput scenarios.

• SSH-only by default (no HTTP Git protocol in core)

  • Why: Reduces attack surface; leverages Unix SSH infrastructure; aligns with server-admin use case.
  • Consequence: Requires users to configure SSH keys; no browser-based push; HTTPS Git requires reverse proxy wrapper.

• Not a GitHub/GitLab alternative: lacks pull requests, issue tracking, code review UI
• Not a real-time collaborative editing platform
• Not designed for horizontally-scaled multi-node deployments without external coordination
• Does not provide HTTP/HTTPS Git protocol natively (SSH-first design)

SSH vs HTTP ports: cmd/soft/serve/serve.go defaults to :23231 for SSH, separate HTTP port for git protocol—check SOFT_SERVE_SSH_LISTEN_ADDR and SOFT_SERVE_HTTP_LISTEN_ADDR env vars. Database: SQLite is default but PostgreSQL required for HA deployments (SOFT_SERVE_DB_DRIVER=postgres); no automatic schema migrations visible—manual SQL setup may be needed. Git LFS: charmbracelet/git-lfs-transfer integration requires git-lfs binary on PATH. Public keys: SSH auth relies on authorized_keys file format or database storage; no LDAP/OAuth visible. TUI terminal: bubbletea requires TERM=xterm or better; SSH clients must support PTY allocation.

• SSH as Transport Protocol for Version Control — Soft Serve delivers Git operations and interactive UIs entirely over SSH, avoiding HTTP/REST; understanding SSH tunneling, pseudo-terminals (PTY), and session multiplexing is essential for modifying transport logic in cmd/soft/serve/server.go
• Git Plumbing vs Porcelain — Soft Serve uses go-git/v5 (porcelain-level library) but falls back to spawning git CLI commands (cmd/soft/git/command.go) for operations like hooks and LFS; knowing the boundary between high-level and low-level Git operations informs where to extend functionality
• Pseudo-terminal (PTY) Allocation in SSH — The TUI works only when an SSH client allocates a pseudo-terminal; cmd/soft/serve/server.go must detect and handle PTY requests via wish's Session handler, otherwise interactive commands fail
• Elm Architecture (Model-Update-View) in TUI — Bubbletea (cmd/soft/browse/browse.go, cmd/soft/serve/server.go) implements Model/Update/View pattern for state management in terminals; understanding this functional reactive model is required for adding new TUI screens or commands
• Git Ref Namespace and Authorization — Soft Serve differentiates public/private repos and per-user access via git/reference.go and authorization logic; understanding Git's ref database (refs/heads, refs/tags, refs/*) is crucial for implementing fine-grained access control
• Certificate Hot-Reloading (TLS without downtime) — cmd/soft/serve/certreloader.go implements certificate reloading without restarting the HTTP server; understanding cert rotation patterns is essential for production deployments offering HTTPS for git protocol
• Git Hooks Execution and Sandboxing — cmd/soft/hook/hook.go wraps git hook execution; understanding pre-receive, update, post-receive hooks and their security implications (sandboxing, environment vars) is vital for access control and audit logging

• go-git/go-git — Underlying Git library (go-git/v5) that soft-serve wraps; understanding go-git's plumbing layer helps debug repository operations
• charmbracelet/wish — SSH server framework (wish/v2) used in cmd/soft/serve/server.go; soft-serve extends wish.Handler for TUI delivery over SSH
• charmbracelet/bubbletea — TUI framework (bubbletea/v2) powering the interactive terminal UI for both SSH server and local browse; core Model/Update/View pattern
• gitea/gitea — Alternative self-hosted Git server; Soft Serve positions as lighter SSH-native alternative (no web UI, no database required for basic setup)
• charmbracelet/git-lfs-transfer — Git LFS protocol implementation (direct dependency) handling large file uploads; soft-serve integrates this for LFS support

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 git/command.go and git/utils.go

The git package contains critical command execution and utility functions (git/command.go, git/utils.go) that lack visible test coverage based on the file structure. These are core to soft-serve's Git operations. Adding tests would improve reliability and catch regressions early, especially for edge cases in Git command parsing and execution.

• [ ] Create git/command_test.go with tests for command construction and execution paths
• [ ] Create git/utils_test.go to test utility functions (already has git/attr_test.go and git/commit.go patterns to follow)
• [ ] Test error handling for malformed Git commands and edge cases
• [ ] Ensure coverage is reflected in codecov.yml integration
• [ ] Add tests for the git/server.go SSH protocol handling if not already covered

Add integration tests workflow for pkg/backend components

The pkg/backend directory contains critical business logic (auth.go, access_token.go, collab.go, hooks.go, lfs.go) with only auth_test.go visible. A dedicated GitHub Actions workflow for integration tests would validate that backend operations work correctly with the database layer (jmoiron/sqlx + PostgreSQL/SQLite). This is currently missing from the .github/workflows/ directory.

• [ ] Create .github/workflows/integration-tests.yml that spins up SQLite/PostgreSQL test databases
• [ ] Write integration tests in pkg/backend/access_test.go (extend existing pattern) for access control flows
• [ ] Add tests for pkg/backend/hooks.go lifecycle and execution
• [ ] Add tests for pkg/backend/lfs.go with actual LFS transfer operations
• [ ] Configure the workflow to run on PRs and main branch commits

Add missing documentation for SSH/Git protocol configuration in docker.md

The repo has docker.md and Dockerfile but the file structure suggests incomplete Docker deployment documentation. Given the presence of .nfpm/ packaging files, systemd service config, and SSH server setup (charmbracelet/ssh dependency), new contributors need clear guidance on configuring soft-serve in Docker with proper SSH key mounting, port exposure, and Git protocol settings.

• [ ] Expand docker.md with section on SSH key volume mounting and configuration
• [ ] Document how to expose Git SSH port (default 23231 or similar) and HTTP port properly
• [ ] Add docker-compose.yml example in root directory showing full stack with PostgreSQL
• [ ] Reference .nfpm/soft-serve.service and .nfpm/soft-serve.conf in documentation for systemd context
• [ ] Include examples of setting environment variables from cmd/soft/main.go via docker-compose

• Add unit tests for git/patch.go, git/stash.go, git/tag.go—these files are present but have no visible _test.go counterparts while git/attr.go has attr_test.go, suggesting incomplete coverage.
• Extend cmd/soft/admin/admin.go with repository deletion/archival CLI commands—currently only browse/serve/hook/admin are defined; admin subcommand likely needs repo management verbs.
• Document environment variable configuration schema: create a CONFIG.md listing all SOFT_SERVE_* vars (SOFT_SERVE_SSH_LISTEN_ADDR, SOFT_SERVE_HTTP_LISTEN_ADDR, SOFT_SERVE_DB_DRIVER, etc.) with defaults inferred from caarlos0/env/v11 usage.

• High · Outdated Alpine Base Image — Dockerfile. The Dockerfile uses 'FROM alpine:latest' without pinning a specific version. This can lead to unpredictable builds and potential security issues from unvetted base image updates. The 'latest' tag is not suitable for production deployments. Fix: Pin Alpine to a specific version, e.g., 'FROM alpine:3.20' or the latest stable release. Regularly update and test new versions.
• High · Git Subprocess Command Execution Risk — git/command.go, git/server.go. The codebase contains git/command.go which likely executes git commands. Without proper input validation and sanitization, this could be vulnerable to command injection attacks, especially if repository names or user inputs are passed directly to git commands. Fix: Ensure all user inputs are properly validated and sanitized before being passed to git commands. Use parameterized execution (avoid shell=true) and validate repository names against a whitelist pattern.
• High · SQL Injection Risk in Database Layer — pkg/backend/*.go (auth.go, repo.go, user.go, webhooks.go, etc.). The codebase uses 'github.com/jmoiron/sqlx' which allows raw SQL queries. If user input is concatenated into SQL queries in pkg/backend/*.go or elsewhere, SQL injection vulnerabilities could exist. Fix: Audit all SQL queries for parameterized query usage. Ensure all dynamic values use prepared statements with placeholder parameters. Implement input validation and use ORM features or query builders when possible.
• High · SSH Key Management and Initial Admin Keys — Dockerfile, cmd/soft/main.go, pkg/backend/user.go. The environment variable SOFT_SERVE_INITIAL_ADMIN_KEYS is empty by default but accepts SSH keys via environment variable. Passing SSH keys through environment variables can lead to exposure in logs, process listings, or container inspection tools. Fix: Avoid passing sensitive credentials via environment variables. Instead, use mounted secrets, configuration files with restricted permissions, or a secrets management system. Document secure key provisioning methods.
• High · Exposed Unauthenticated Git Protocol Port — Dockerfile (EXPOSE 9418/tcp). The Dockerfile exposes port 9418 (Git protocol), which is the unauthenticated git:// protocol. This allows anonymous read access to repositories and could expose sensitive code or enable attacks. Fix: Consider disabling the unauthenticated git protocol. If needed, restrict access at the network level. Use SSH (port 23231) or HTTPS (port 23232) with authentication instead. Document that git:// protocol should not be used in production without network restrictions.
• Medium · Missing Security Headers Configuration — cmd/soft/serve/server.go, cmd/soft/serve/serve.go. The codebase uses gorilla/mux and gorilla/handlers for HTTP but no evidence of security headers (CSP, X-Frame-Options, X-Content-Type-Options, etc.) is visible in the provided structure. Fix: Implement middleware to add security headers such as Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Strict-Transport-Security, and X-XSS-Protection.
• Medium · JWT Token Security — pkg/backend/auth.go, pkg/backend/access_token.go. The codebase uses 'github.com/golang-jwt/jwt/v5' but the secret key management strategy is unclear. Weak JWT secrets or improper key rotation could compromise authentication. Fix: Ensure JWT secrets are cryptographically random, sufficiently long (minimum 256 bits), stored securely, and rotated periodically. Validate token expiration and implement token revocation mechanisms.
• Medium · Missing Input Validation in HTTP API — pkg/backend/webhooks.go, cmd/soft/serve/server.go. While using gorilla/mux for routing, there's no visible evidence of comprehensive input validation, especially for file uploads, repository names, or webhook payloads. Fix: Implement comprehensive input validation for all HTTP endpoints. Validate file uploads (type, size), repository names (regex patterns), and webhook payloads

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.