internal/

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 attention builds the list of things an operator should look at right now, shared by the CLI and the MCP server.

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 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 cronexpr parses and evaluates standard 5-field cron expressions ("minute hour day-of-month month day-of-week", e.g.

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 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 diskspace provides a single, reusable free-disk-space check (statfs's Bavail, the same "free space an unprivileged user could actually write" number GET /api/v1/system/doctor's disk_space check and GET /api/v1/system/status already surface), so disk-heavy operations elsewhere in this codebase (BuildKit builds, backup bookkeeping) can gate on it without reimplementing the syscall.

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 docker wraps the Docker Engine API.

Package dockerhub implements a minimal client for Docker Hub's public, unauthenticated Hub API: repository search and tag listing, used to let an operator discover a well-known public image from the app-creation "docker image" step (RegistryImagePicker.tsx) instead of typing a reference blind.

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 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 experimental is the single platform gate for features hidden at launch.

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

Package firewall manages host ufw rules as declarative allow/deny records.

Package forecast projects a resource's usage trend forward with a plain ordinary-least-squares line fit over recent (timestamp, bytes used) samples: deterministic, pure-Go, no external model, the same read-and-suggest shape internal/rightsizing already establishes.

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 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 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 loadbalancer is the product-level load balancer model layered on the embedded Caddy reverse_proxy upstream pool (internal/ingress).

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 netguard builds HTTP clients for user-configured outbound URLs (alert and deploy notification webhooks) that refuse to connect to loopback, private, link-local, or otherwise internal addresses.

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 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 passkey wraps github.com/go-webauthn/webauthn for this project's two ceremonies (registering a credential, signing in with one).

Package pathfilter matches changed file paths against doublestar-style globs, the filter behind pipeline `paths` / `paths_ignore` and the deploy-on-push path filters.

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

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

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 probe implements readiness and liveness checks the controller runs against a container: an HTTP(S) request to its published port, or a command exec'd inside it.

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 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 rightsizing is a deterministic, pure-Go engine that turns an app's historical CPU/memory usage into a resource-limit suggestion.

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 execs an operator-defined command into a running app's container on a cron schedule (e.g.

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 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 slowquery parses already-stored container log lines (see internal/api/database_slow_queries.go) into structured slow-query entries for Postgres and MySQL.

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 stackdetect inspects a local project directory and guesses how the platform should build it.

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 ticker is the run-until-cancelled loop shared by this codebase's periodic schedulers (backup, scheduledeploy, scheduledtask, updatecheck), extracted here so a new one doesn't add another copy.

Package totp implements time-based one-time passwords (RFC 6238, the algorithm every mainstream authenticator app speaks) plus the small amount of supporting logic 2FA needs: secret generation, an otpauth:// provisioning URI, and single-use recovery codes.

Package untrusted prepares attacker-influenced text (workload logs, env values, deploy output, error messages, commit messages, PR titles) for an AI model: it strips terminal and invisible characters, redacts obvious secrets, truncates, and wraps the result in a delimited block that says it is data.

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 upgrade runs the read-only checks that gate a platform self-upgrade.

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.