internal/

Package accesspolicy merges per-team session rules into one effective set and answers the questions the API middleware asks on every request.

Package agent is the transport boundary: the interface ADR 003 describes ("the reconciler and everything above the transport boundary never knows whether it's talking to a local in-process agent or a remote one over mTLS") but that Phase 1 never actually built, confirmed directly against this repo before writing this package: every reconcile controller (internal/reconcile/application, internal/reconcile/database) takes a bare docker.Runtime, and cmd/levelrail/main.go's dynamicSource hands every controller the same single local docker.Runtime with no node concept anywhere.

Package agentinit renders the files "init" writes into a project: app.yaml, AGENTS.md and .mcp.json.

Package ai implements the BYOK AI assistant chat feature: a provider-agnostic turn engine (engine.go) that runs a conversation against an LLM (Provider below) with tool use backed by the existing MCP tool surface (toolcaller.go, internal/mcptools), pausing every mutating tool call for an explicit human confirmation click (classify.go).

Package alerting implements threshold rules over internal/telemetry's metrics and logs, and crashloop detection as a built-in rule kind sharing the same evaluate/notify path rather than a separate mechanism.

Package api implements the HTTP API the web frontend (1.10) and, later, the MCP layer both build on.

Package apiclient is the one HTTP client implementation for the control plane's versioned API (internal/api, mounted at /api/v1).

Package appimport turns a source platform's application inventory into a reviewed, staged import: per-app verdicts, a hostname mapping with a visible diff, preflight checks and a secret-free receipt.

Package appsleep stops opted-in apps that have had no requests for a while and wakes them on the next request, so idle apps cost no memory or CPU.

Package appwizard analyses a git repository through a provider file-tree API and returns pre-filled, evidence-backed suggestions for creating an app.

Package attention builds the list of things an operator should look at right now, shared by the CLI and the MCP server.

Package authengine hosts the theauth-go library behind a flag.

Package backup drives a database backup end to end: dump a managed database container's data, stream it straight to an S3-compatible bucket, and record the attempt in store.BackupHistory.

Package bindaddr resolves the small bind-address vocabulary app services and managed databases use to choose which network interface a published port binds to.

Package bindmount validates a service's bind-mount host path, shared by internal/compose and internal/spec: internal/compose imports internal/spec (a compose service expands into a spec.Service), so neither of those two packages can hold this logic without the other importing it back and cycling.

Package bitbucketapp implements OAuth2 and the small slice of Bitbucket Cloud's REST API this control plane needs once connected.

Package brand provides the branding indirection layer this project requires: no product name is ever hardcoded in source.

Package build drives container image builds through BuildKit's Go client (github.com/moby/buildkit/client), never by shelling out to `docker build` or the `docker` CLI, matching the same "no CLI shelling" rule the node communication layer follows.

Package catalog holds Levelrail's own curated set of one-click service templates (ADR 015).

Package changelog parses the repo's release-please-maintained CHANGELOG.md into the entries GET /api/v1/changelog and the dashboard's "What's new" panel serve, so release notes keep exactly one source of truth instead of a second, hand-curated copy.

Package changes answers "what changed on this app recently" by merging the app event log, deploy attempts and the audit log into one ordered list.

Package cliconsole turns one typed console line into a vetted argv for the platform CLI and runs it as a child process.

Package clitree is the CLI's command tree, shared by its shell completions and the control plane's web CLI console allowlist.

Package compliance builds access reviews and signed evidence packs from data the platform already records.

Package compose parses a Docker Compose file into Levelrail's own desired-state model, in two shapes depending on the caller.

Package costestimate is a deterministic, pure-Go engine that turns an app's CPU/memory allocation into an ESTIMATED monthly cost under a few generic reference pricing profiles (a plain VM, a managed VM, a metered container PaaS).

Package cpbackup manages control plane self-backups: verified SQLite snapshots kept in a directory under the data dir.

Package cutover plans and runs a guided, reversible move of one staged import app: readiness rules, a persisted state machine, DNS undo data.

Package dataexport sends logs, audit events and metrics to destinations an operator already runs.

Package datamigrate copies live data from a source database into a managed database here, and checks a cutover is safe.

Package dbaccess manages database users, temporary credentials and network scope.

Package dbcatalogbuild builds, validates and signs the database version catalog (databases.v1.json) from upstream registries and endoflife.date.

Package dbupgrade advises on and automates minor and patch upgrades of managed databases: a curated version catalog, per database policies with a maintenance window, and a resumable runner that backs up, upgrades, verifies and reverts.

Package dbviewer runs read-only (and, when explicitly allowed, write) SQL against a managed database by exec'ing the engine's own client inside its container.

Package demo builds and guards the read-only public demo instance: a seeded control plane with no Docker, ingress or agent listeners.

Package deploy is the build integration: it connects internal/spec's build declaration to internal/build's BuildKit client, and a successful build's output to internal/store's desired state, closing the loop the application controller (internal/reconcile/ application) reads from on every reconcile.

Package deploylog is the glue between internal/build.ProgressEvent (the progress callback all three real deploy-attempt trigger paths already thread through internal/deploy.Pipeline.Deploy) and two real consumers: a persisted, replayable row in telemetry.db (internal/telemetry's deploy_logs table) and any currently-connected SSE viewer watching that same attempt live.

Package deploysafety decides whether a new release may take traffic and whether a live one must be rolled back, and holds the shared reason strings.

Package deploywatch pins released images as rollback targets and watches each new release after cutover, rolling it back when it misbehaves.

Package diagnose is a deterministic, pure-Go pattern matcher over diagnostic signals the platform already collects: deploy attempt status/error, reconcile condition reason strings, crashloop alert state, and recent log lines.

Package dnsrecords builds a provider-agnostic DNS record manager from whichever ACME DNS-01 provider a control plane already has credentials for (Cloudflare or Route53), reusing libdns's own interfaces instead of inventing a second one: github.com/libdns/cloudflare and github.com/libdns/route53, both already a dependency via internal/ingress's Caddy DNS-01 wiring, implement them already.

Package dnszones manages whole DNS zones at Cloudflare and Route53: zones, their assigned name servers, record sets with routing policies, delegation checks, propagation checks, zone file import and export, and templates.

Package docker wraps the Docker Engine API.

Package dockerguard is an in-process Unix socket proxy in front of the Docker Engine API.

Package dockertest holds test helpers shared by every package whose _live_test.go files need a real Docker daemon (or other real, network-dependent infra) to run.

Package domaindoctor runs an ordered set of read-only checks against one domain (DNS, CAA, ports, TLS, HTTP, redirects, HSTS, platform state) and turns each result into a fix an operator can act on.

Package email is the platform's one email-sending capability: a narrow Sender interface plus SMTP, SES, and Resend implementations, shared by internal/alerting and internal/api so neither imports the other.

Package envredact decides which environment values are sensitive and masks them for every read surface.

Package eventhook delivers platform events to operator-configured HTTPS endpoints: signed, queued, retried with backoff, dead-lettered after the last attempt, and recorded in a delivery log that supports replay.

Package experimental is the single platform gate for features hidden at launch.

Package exposure answers "which published container ports can the internet reach" and manages comment-tagged DOCKER-USER rules that restrict them.

Package extdb connects to databases this platform does not run: validating their addresses, probing them read-only, and opening them for the viewer through short-lived helper containers.

Package failure classifies a failed, held or unhealthy deploy into one structured object shared by the API, CLI and MCP surfaces.

Package giteaapp implements OAuth2 and the small slice of Gitea's REST API this control plane needs once connected.

Package githubapp implements the GitHub App manifest registration flow, App-level JWT signing (RS256, per GitHub's own App authentication spec), and the small slice of the GitHub REST API this control plane needs once an App is connected: minting installation access tokens, listing an installation's repositories, and listing a repository's branches.

Package gitlabapp implements OAuth2 and the small slice of GitLab's REST API this control plane needs once connected.

Package gitprovider holds the small slice of REST-client plumbing that is genuinely identical across internal/githubapp, internal/gitlabapp, and internal/bitbucketapp: sending a built request and turning its response into either a decoded value or a uniform API error.

Package gpu detects NVIDIA GPUs on a node by querying nvidia-smi and the Docker daemon's registered runtimes.

Package hostdiag answers a fixed set of read-only host questions for the web CLI console, in process.

Package iac turns multi-document YAML resource files into a plan of changes against a control plane and applies it through the ordinary REST API, so per-resource authorization applies to every item.

Package imagemove streams a host-built image from a source Docker host over SSH into a target node's image store and verifies it by image ID.

Package imageupdate periodically asks the control plane to check each opted-in app's image tag against its registry and redeploy when it moved.

Package importplan classifies an import input (repo URL, docker run command, image reference, compose file or Dockerfile) and builds a side-effect free deployment plan preview from it.

Package ingress is the Phase 0 spike for embedding Caddy as a Go library, driven entirely through its in-process admin API.

Package integrations holds the curated catalog of third-party tools an app can attach (internal/catalog's deployable-template catalog is unrelated: this is per-app add-ons, not services to deploy).

Package investigate merges the signals that explain a spike (deploys, config changes, restarts, resource saturation) into one ordered timeline.

Package loadbalancer is the product-level load balancer model layered on the embedded Caddy reverse_proxy upstream pool (internal/ingress).

Package maintenance holds one-off scheduled maintenance windows: their validation, state, and the lead-time announcement through alert channels.

Package mcptools builds the MCP tool server every levelrail-mcp transport (stdio, network, and the in-process transport an embedded caller like internal/ai uses) shares: one *mcp.Server with every tool registered against the same apiclient.Client.

Package meshpath answers one question for the ingress and application controllers: can this control plane reach a remote node's published ports over the WireGuard mesh right now, and on which address.

Package models manages AI model resources: an inference engine (Ollama, vLLM, llama.cpp) running as a container on a GPU node, with an OpenAI-compatible endpoint fronted by an API-key gateway.

Package network is ADR 006's WireGuard mesh: the abstraction that ADR 006 says "has to be designed in Phase 1 as an interface, not a concrete WireGuard dependency" and that, until now, did not exist at all (the directory the project's repo layout reserves for it was empty).

Package nodemove runs persisted, resumable moves of apps and databases between nodes, and node drains built on those moves.

Package objectstore is the S3-compatible storage layer shared by log archive and other features that write to a connected storage destination.

Package oidc mints short-lived, signed OIDC tokens for pipeline jobs that opt in with `oidc: {audience: ...}`, and publishes the matching JWKS so AWS IAM, GCP workload identity federation, and Vault's JWT auth method can verify them without a long-lived credential ever touching a job.

Package orphans is the single definition of a leftover container or volume that desired state no longer accounts for.

Package pipeline is a user-defined CI/CD layer on top of the existing build and deploy primitives.

Package pkgregistry renders private package registry credentials into the tool config files a Dockerfile build reads through BuildKit secret mounts, so a token is never baked into an image layer or a build log.

Package placement is the multi-node scheduler: node label selectors plus a simple spread over eligible nodes.

Package platformimport reads apps from another self-hosted platform (read-only) into a neutral model and maps it to this platform's resources.

Package policy evaluates deploy guardrail rules against what an app is about to run.

Package preflight runs deterministic pre-deploy checks (DNS, ports, disk, memory, image and git reachability, env, mounts, GPU) and reports pass, warn or fail with a reason and fix hint for each.

Package preview captures a thumbnail of each deployed release with a short-lived browser container and keeps them within bounded storage.

Package prompb implements the small subset of Prometheus's remote-read wire protocol needed for a Prometheus remote read endpoint (ReadRequest/ReadResponse and their nested messages), by hand, using google.golang.org/protobuf's low-level protowire primitives (already a transitive dependency, no new module).

Package provision creates and tears down cloud VMs at a provider (Hetzner, DigitalOcean, Azure, GCP) so a fresh node can join the fleet through the existing join-token enrollment flow, without an operator manually clicking through a cloud console first.

Package proxycoexist helps run the dashboard behind a reverse proxy that already owns ports 80 and 443 (Traefik, Caddy, nginx), which is the normal situation on a server migrating off another platform.

Package proxyroutes writes and maintains route files in an external reverse proxy's watched configuration directory (Traefik's file provider), so domains reach this instance through a proxy that owns ports 80 and 443.

Package quota holds the pure limit arithmetic for team and project resource quotas.

Package reconcile implements the core convergence loop: desired state in, observed state diffed against it, idempotent and level-triggered controllers converge the two.

Package registrycatalog implements a minimal client for the Docker Registry HTTP API v2's catalog endpoints (_catalog, <name>/tags/list), used to browse repositories and tags in Levelrail's own built-in registry (internal/reconcile/registry) from the app-creation UI.

Package registryvendor is the catalog of container registry vendors the credential flow offers presets for: default host, fixed username where the vendor defines one, and how long its tokens live.

Package repolayout inspects a repository's file tree to suggest where its build context and Dockerfile should point, so a monorepo does not silently fall back to auto-detecting the repository root.

Package resourceadvisor turns telemetry, limits and specs into read-only resource findings.

Package rightsizing is a deterministic, pure-Go engine that turns an app's historical CPU/memory usage into a resource-limit suggestion.

Package rollback plans and applies a return to an earlier control plane release.

Package scheduledeploy checks, on an interval, which apps have a due cron schedule (store.AppSchedule, migrations/0250_app_schedules.sql) and redeploys the latest commit on their configured branch.

Package scheduledtask runs operator-defined jobs on a cron schedule, in the running container (exec mode) or in a fresh one-off container built from the app's own spec (fresh mode), mirroring internal/backup's Runner/Scheduler split: Runner (this file) does one run and records its outcome, Scheduler (scheduler.go) decides when a run is due.

Package secretrotation schedules and performs per-secret rotation policies for app secrets: generate a new value, keep the old one for a grace window, restart the owning app, and record every step.

Package secrets implements envelope encryption: per-app data encryption keys, wrapped by a master key held only by the control plane, using filippo.io/age for the crypto primitives.

Package selfupgrade replaces the control plane binary with a verified newer release and rolls binary and data back if it does not become healthy.

Package serverready reports whether a server can run the control plane and in which mode.

Package setupguide derives the Get started checklist from real instance state.

Package sharedenv composes internal/store's shared env var tables (project_env_vars, organization_env_vars, environment_env_vars) with internal/secrets' envelope encryption, so a secret-marked shared env var resolves to its decrypted plaintext by the time internal/reconcile/application's resolveEnv merges it into a running container's environment.

Package spec parses and validates the app.yaml file: the one declarative file a user writes in their repo, per the app spec design.

Package sshprovision adopts a machine the operator already has (any VPS, home server, Raspberry Pi) as a node by dialing into it over SSH and installing the node agent there.

Package standalone models domains that are not owned by any app and proxy to a target the operator picks: a local port, an address, a URL, another app's port or a container.

Package statuspage builds the opt-in public status page: component probing, 90-day uptime bars, operator-authored incidents and the whitelisted public view.

Package store is the embedded SQLite state layer: WAL mode, modernc.org/sqlite (pure Go, no cgo, keeps cross-compiling the control plane binary trivial), forward-only versioned migrations.

Package supplychain records the SBOM of each build, optionally scans it for known vulnerabilities in a short-lived container, and decides whether a release may go live.

Package telemetry is the node-local metrics store, decided in ADR 009: a dedicated SQLite database (telemetry.db, separate from internal/store's levelrail.db) holding container resource-usage samples, queried in place rather than shipped anywhere centrally.

Package tlsowner decides which component terminates TLS for a hostname, so every surface reports one coherent certificate and ACME state.

Package totp holds the recovery-code format helpers and an RFC 6238 code generator the auth engine and its tests share.

Package trafficpolicy holds the per-domain traffic control model (headers, path forwarders, geolocation, caching, redirects): the wire types the API, CLI and dashboard share, their validation, and a human readable preview.

Package tui is the interactive terminal UI behind the CLI's "tui" command: a live, keyboard-driven view of apps, databases, deployments, nodes, domains, alerts and backups over the public HTTP API only.

Package updatecheck periodically checks the configured update channel's latest release against the running build, when an operator has opted into auto-update checking (update_settings.auto_update_enabled, migrations/0258_update_settings.sql).

Package upgradehistory records every control plane version transition at boot, however the binary was replaced, and builds the links and context the Updates page shows for it.

Package upgradesched runs scheduled and automatic control plane upgrades.

Package usagecost allocates a real or configured infrastructure price to the apps and databases that consume it, then rolls the result up per project, environment and team.

Package vault resolves a live secret value from an external HashiCorp Vault instance at container-create time, as an alternative to internal/secrets' own envelope-encrypted storage.

Package version holds the control plane's own build version, injected via -ldflags at release build time (see .github/workflows/release.yml).

Package webhook is the git integration: a GitHub push-webhook receiver that verifies the request signature, extracts the pushed commit SHA, fetches the repository at that SHA to a local checkout, and hands the result to internal/deploy's Pipeline, the same pipeline a manual deploy trigger will use once the HTTP API exists.

Package webpush sends browser push notifications (RFC 8030/8291) to every subscription this control plane's dashboard has registered, backing the "webpush" notification-channel kind in internal/alerting: an operator gets a deploy/alert notification even with no dashboard tab focused or open, something none of the other 17 channel kinds (all webhooks or email) can do on their own.