Thomas
229bd4b3ed
* feat: migrate tooling and runtimes to bun * fix: serialize act installs and adapt backup checks * fix: finish bun scripts and rootless act setup * fix: support bun images in runtime benchmarks * fix: keep a single bun toolchain configuration * fix: include docs mascot sources in workshop build * docs: use bun in remaining tool commands * fix: complete bun sqlite development tooling * docs: explain sqlite development adapter * fix: align remaining commands and local ci validation * fix: use renovate regex fallback with bun * fix: finalize bun sqlite connections during cleanup * fix: preserve sqlite foreign key enforcement * fix: align docker build frontends * fix: prepare release versions with bun * Add Bun benchmarks and preserve SQLite connection defaults * Benchmark Bun installs, conflicts and production workloads * Force Bun workspace tools and HTTP/1.1 upstream streaming * Exclude benchmark evidence from Docker contexts * Expose branch benchmarks through CI * Verify hydrated widget data in production benchmarks * Measure image archives and document benchmark protocol * Audit dependency sharing across every workspace * Pin pnpm for nested baseline benchmark scripts * Preserve nested manager pinning on benchmark resume * Include application and runtime image footprints * Fail benchmark gates on candidate command errors * Report complete build overhead and sampled memory bounds * Validate migration comparisons across pinned revisions * Record configurable runtime memory budgets * Retain out-of-memory kills in runtime budget probes * Reject OOM events consistently across runtime metrics * Record complete Bun migration benchmarks * Record memory diagnosis and correct Turbo caching * Use Bun package management while preserving Node runtimes * Keep native build fallbacks and exclude development artifacts * Fix Node ESM metadata and isolate local CI configuration * Measure development performance and isolate act environment * Support isolated environment files in rootless act * Validate the full migration range with act * Preserve native SQLite binding for bundled migrations * Use documented dev defaults and report benchmark scope * Validate dev defaults and isolate restart measurements * Record package-manager and development benchmarks * Keep benchmark measurements and link full command artifacts * Clean up temporary act environment files * Validate Node runtimes in package-manager comparisons * Validate every workspace in manual CI runs * Retain patched nested brace expansion versions * Complete package-manager and Node performance report * Normalize archived benchmark logs * Record final hosted validation * Cache both Next builds with platform isolation * Prime cache with write-only mode * Split Next artifacts below Cloudflare upload limit * Assemble coherent standalone cache outputs * Preserve traced middleware entrypoints * Assemble traced directory links before files * Separate cached dependencies from assembled output * Record signed Turbo cache benchmarks * Remove archived benchmark captures Full benchmark evidence is preserved at 8f7d3bcd14109bfb13fa664d31710b88d820ad66. * Remove migration benchmark harness * fix: correct migration launch and local Act prerequisites * Consolidate Turbo caches and production artifacts * Exclude generated files from Docker cache inputs * fix: address Bun migration review findings * fix: check restored compiler bundle manifests
Homarr Developer CLI
Build and launch local Homarr images and GHCR pull-request builds, then manage them from responsive terminal dashboards.
Requirements
- Docker or OrbStack
- Go 1.25+ to build from source
- GitHub CLI authenticated with
gh auth loginfor pull-request features
Setup
bun install
Create .env from .env.example and set DB_URL to an absolute path for the SQLite file before running the migration. In a POSIX shell, use cp .env.example .env; in PowerShell, use Copy-Item .env.example .env.
Then run bun run db:migration:sqlite:run to create or update the database. The migration command also seeds a new database. Use bun run db:seed explicitly when you need to seed an existing database. Start Redis separately with bun run docker:dev:up when it is needed.
The examples below use bun run dev:cli -- ..., which works from POSIX shells and PowerShell. If you prefer a global command, install it with bun run dev:cli:install and add your Go bin directory to PATH.
Build
bun run dev:cli -- build feature
bun run dev:cli -- build --pr 6441
bun run dev:cli -- rebuild feature
Checkout builds are tagged as homarr:<name>. The source checkout and revision are recorded on the image so homarr rebuild and the development dashboard can rebuild it later. PR builds use a temporary checkout and default to homarr:pr-<number>.
Launch
homarr --pr 6441 --env WORKSHOP_WEB_URL=https://app-v2.preview.homarr.dev/
bun run dev:cli -- run dev
bun run dev:cli -- run --detach dev
bun run dev:cli -- run --pr 6441
bun run dev:cli -- run --pr 6441 --demo
bun run dev:cli -- run --env FOO=bar --env FEATURE=true dev
PR launches always pull the latest GHCR tag before starting. Local tags remain local.
The installed binary accepts --pr, --demo, --detach, and repeatable --env KEY=VALUE flags directly, so
homarr --pr <number> --env KEY=VALUE is shorthand for homarr run --pr <number> --env KEY=VALUE.
The first launch generates a per-user encryption key in the OS config directory and reuses it for later launches. Set HOMARR_DEV_SECRET_ENCRYPTION_KEY to a 64-character hexadecimal key to override it.
The command reference below assumes the optional homarr installation. Without it, prefix each command with bun run dev:cli -- (for example, bun run dev:cli -- dev).
Commands
homarr Interactive local and remote image browser
homarr --pr <number> Pull and launch a PR image, with optional --env overrides
homarr dev Explicit alias for the main browser
homarr dash Start on the instance dashboard
homarr build <name> Build this checkout as homarr:<name>
homarr build --pr <number> Build a PR locally from a temporary checkout
homarr rebuild <name> Rebuild from recorded provenance
homarr images List local images with build provenance
homarr data List instance data volumes
homarr data rm <volume> Preview permanent data deletion; add --force to confirm
homarr prune Remove stopped instances
homarr list Script-friendly instance list
homarr logs <container> Follow logs
homarr shell <container> Open an interactive shell in a running instance
homarr ci [pr] [--watch] View or watch GitHub CI checks for a pull request
homarr open <container> Open in browser
homarr stop <container> Stop
homarr restart <container> Restart
homarr remove <container> Force-remove
homarr doctor Check Docker, Engine API, and optional integrations
Development Browser
/ Filter by PR number, title, author, branch, CI, image, state, or port
↑/↓ or j/k Select row
Enter or Space Start the available image; choose local or remote when both exist; stop when running
R Build locally in background (or rebuild local image)
p Pull remote PR image in background and start container
m Manage mode (chords: b rebuild, i delete image, d delete data, c remove container, p prune)
t Background tasks overlay (status, progress, cancellation)
Tab Cycle sidebar tab (logs / build / ci)
l Toggle sidebar visibility
L Pin logs to currently selected container
f Follow or pause logs
Page Up/Down Scroll logs
M Toggle demo mode for next launch
b Toggle bot PRs
o Open PR on GitHub
a Open running instance in browser
c Copy instance URL to clipboard
r Refresh data
1 / 2 / d Switch screen (development / instances)
? Help overlay
q Quit (cancels background tasks)
Pull progress with live layer bytes, throughput, BuildKit step streaming, local build provenance, CI rollup badges, container health status, and live output streams are non-blocking. When a background pull completes, the sidebar automatically transitions to streaming the running instance's live logs.
Instance Dashboard
/ Filter by name, image, state, health, port, or URL
↑/↓ or j/k Select row
Enter or Space Start / stop selected instance
s Stop instance
S Restart instance
x Remove container (keeps data)
m Manage mode for selected instance
t Background tasks overlay
Tab Cycle sidebar tab (logs / build / ci)
l Toggle sidebar visibility
L Pin logs
f Follow / pause logs
Page Up/Down Scroll logs
o Open running instance in browser
c Copy URL to clipboard
R Rebuild from recorded provenance
r Refresh
1 / 2 / d Switch screen
? Help overlay
q Quit