Local

The local package is the Cronhoster code that runs on your own machine. You download one versioned directory, cronhoster-local-<version>, and run the one command inside it, cronhoster-local.js. That command parses the command line, loads your config, and hands off to one script per job: sync (push your job directories to the server) and the local browser tools. The package is in four parts: localhoster-common/, the shared toolkit every hoster carries; localhoster-tools/, the two universal browser tools; cronhoster-tools/, this hoster's own Cron Logs tool; and cronhoster-sync/, the sync command. The directory you see here is exactly the directory in the zip. This page is the file map, then a section per part.

cronhoster-local-<version>/                   unzips from cronhoster-local-<version>.zip
  cronhoster-local.js                         the one command you run: parse args, load config, dispatch
  config.example.json                         the config template (copy to config.json)
  localhoster-common/                         the shared toolkit, identical across every hoster
    index.js                                  the single require surface (loadConfig, toolsSite, the UI kit)
    net.js                                    config load, bare-IP TLS, API-version
    run.js                                    the tools-site frame + per-tool run state
    shell.js                                  the page frame: strip, tabs, status, stylesheet
    ui.js                                     the UI kit: cards, tables, charts, pagination
    format.js                                 formatters: esc, numbers, bytes, dates
    io.js                                     small render/IO helpers
  localhoster-tools/                          the universal tools, shared across every hoster
    web-logs/
      index.js                                run(config): pull the access logs, then build the browser
      lib/
        pull.js                               mirror the access logs down
        render.js                             build the Web Logs pages
        chart.client.js                       draw the charts + tables in the browser
    server-logs/
      index.js                                run(config): pull the stats, then build the browser
      lib/
        pull.js                               mirror the server stats down
        render.js                             build the Server Logs pages
        chart.client.js                       draw the charts + tables in the browser
  cronhoster-tools/                           this hoster's own tools
    cron-logs/
      index.js                                run(config): pull the run records, then build the browser
      lib/
        pull.js                               mirror the run records down
        render.js                             render the Cron Logs pages
        schedule.js                           the cron-settings parser and time matcher
  cronhoster-sync/                            the sync command
    index.js                                  run(config): push the job dirs, pruning removals
    lib/
      manifest.js                             the Merkle tree the sync descends
      version.js                              the API/protocol version

The cronhoster-local package: the entry, the shared toolkit, the universal and Cronhoster-specific tools, and the sync command.

Name	Type	Description
`cronhoster-local.js`	file	The one command you run. It parses the command line, loads the config, and dispatches to each job's own script.
`localhoster-common/`	folder	The shared toolkit, identical across every hoster: the config loader, the tools-site frame, and the UI kit.
`localhoster-tools/`	folder	The two universal browser tools shared across every hoster: Web Logs and Server Logs.
`cronhoster-tools/`	folder	This hoster's own tool: the Cron Logs browser and the run-record pull and schedule parser it reads.
`cronhoster-sync/`	folder	The sync command: it pushes your job directories up, with its own copy of the Merkle tree and API version.
`config.json`	file	The local config: the server address, the API token, and the two paths the local package reads and writes.

`cronhoster-local.js` — the command you run

One command runs everything. It takes a mandatory --config pointing at an absolute path to a .json file, loads that config into a frozen object, and runs one script per switch. Each tool derives its own paths from the config, so running one tool never touches another's pages.

Switch	What it does
`--config <path>`	Absolute path to the local config JSON. Required, and must end in `.json`.
`--sync`	Push the job directories up to the server before the browsers render them.
`--web-logs`	Mirror the access logs down and build the Web Logs browser.
`--server-logs`	Mirror the server stats down and build the Server Logs browser.
`--cron-logs`	Mirror the run records down and build the Cron Logs browser.
`--all`	Everything in one process: sync and all three browser tools.

The shared toolkit

The files under localhoster-common/ are the shared toolkit. They are identical across the hoster family, so a sibling hoster's local package is a short entry on top of the same engine. The entry and every tool require localhoster-common, never a file inside it, so the internal layout can change without touching a tool.

Name	Description
`localhoster-common/index.js`	The single require surface. It re-exports `loadConfig`, `toolsSite`, `recordRun`, and the UI kit, so a tool depends on the facade rather than the files behind it.
`localhoster-common/net.js`	Reads and validates the config into a frozen `{ apiBase, apiToken, insecure, contentRoot, toolsRoot }`, skips cert verification per request for a bare-IP endpoint, and discovers the server's API version so request paths follow it.
`localhoster-common/run.js`	The tools-site frame. It assembles the overview (one card per tool) and a "not run yet" status page, reading each tool's own state file so running one tool never clobbers another's card.
`localhoster-common/shell.js`	The page frame: the fixed top strip, the tabs, the per-tool status banner, and the stylesheet, so every page looks like one site.
`localhoster-common/ui.js`	The shared UI kit: stat cards, tables, chart and table toggles, pagination, and the common CSS.
`localhoster-common/format.js`	The canonical formatters: escaping, numbers, bytes, durations, and month and day labels.
`localhoster-common/io.js`	Small render and IO helpers, chiefly the footer-stripping used by the write-if-changed comparison.

The universal tools

The files under localhoster-tools/ are the two browser tools every hoster carries. Each tool is a directory with an index.js exporting { key, label, run(config) } and a private lib/. The run(config) mirrors its data down, renders its pages, and records its result for the overview card.

Name	Description
`localhoster-tools/web-logs/index.js`	The Web Logs tool. It pulls the Caddy access logs down, then builds the browser.
`localhoster-tools/web-logs/lib/pull.js`	Mirrors the access logs down incrementally. Rotated files are fetched once, and the active log has only its new tail appended by Range.
`localhoster-tools/web-logs/lib/render.js`	Renders the Web Logs pages, a static self-contained site over the mirrored access logs.
`localhoster-tools/web-logs/lib/chart.client.js`	Renders the Web Logs charts and tables in the browser from a compact per-panel data spec, so a page ships its data once instead of as inline SVG plus a duplicate table. Downloaded once, cached across the tool.
`localhoster-tools/server-logs/index.js`	The Server Logs tool. It pulls the server stats down, then builds the drill-down browser.
`localhoster-tools/server-logs/lib/pull.js`	Mirrors the server's statistics day-files down incrementally, the stats counterpart of the log pull.
`localhoster-tools/server-logs/lib/render.js`	Renders the Server Logs pages, charting every metric across days and hours.
`localhoster-tools/server-logs/lib/chart.client.js`	Renders the Server Logs charts and tables in the browser from a compact per-panel data spec, so a page ships its data once instead of as inline SVG plus a duplicate table. Downloaded once, cached across the tool.

Cronhoster's own tool

The files under cronhoster-tools/ are this hoster's own. The Cron Logs tool answers one question at a glance: are my crons healthy? Its run(config) pulls the run records down, then renders the health view joined from the job directories and the pulled records.

Name	Description
`cronhoster-tools/cron-logs/index.js`	The Cron Logs tool. It pulls the run records down, then builds the browser.
`cronhoster-tools/cron-logs/lib/pull.js`	Mirrors the server's run-record day-files locally, incrementally and append-only. A frozen past day is fetched once, and today's growing file has only its tail appended, so its history outlives the server's retention.
`cronhoster-tools/cron-logs/lib/render.js`	The Cron Logs browser. It reads the local cron directories and the pulled run records, joins them, and renders a static site: an overview of every cron with its health, and a page per cron with its configured runs and recent executions.
`cronhoster-tools/cron-logs/lib/schedule.js`	The cron-settings parser and time matcher. It turns a `cronhoster-cron-settings.json` into validated runs and tests each against the UTC clock. It is the same contract the runner uses on the server side.

`cronhoster-sync/index.js`

The sync command pushes your job directories up. It is stateless: each run it reads the content root, compares its top-level job directories to the server by a Merkle tree, and pushes only the ones the server does not yet have, pruning any it no longer keeps. A directory is uploaded whole the first time it appears and is then left untouched, so versioning is a new directory under a new name. It carries its own copy of the wire contract so the package is self-contained.

Name	Description
`cronhoster-sync/index.js`	The sync pass. `run(config)` builds the local tree, takes a root-hash fast path when nothing changed, and otherwise reconciles the top-level job directories: deletes first, then streamed uploads.
`cronhoster-sync/lib/manifest.js`	The Merkle tree the sync descends. A file's hash is derived from its metadata, so building the tree reads no file data. It carries `skipUnderscore`, so `_`-prefixed and dotted entries never sync at any level.
`cronhoster-sync/lib/version.js`	The `API_VERSION`, which forms the `/api/vN` path prefix. It is currently 2. The package pins it to its own value, so a package and server on different versions are caught with a `426` rather than a silent misparse.

config.json

The local config is one JSON file. It names the server, the token the private API checks, and the two paths the local scripts read and write. Give an absolute path everywhere a path is expected. The Local usage page walks through each key.

{
  "cronhoster-config-serverAddress": "203.0.113.5",
  "cronhoster-config-apiToken": "your-api-token",
  "cronhoster-config-contentRoot": "/home/you/cronhoster/cron",
  "cronhoster-config-tools": "/home/you/cronhoster/_tools"
}

A complete local config: the server address, the API token, and the two absolute paths.

Key	Description
`cronhoster-config-serverAddress`	Your server's raw IP. Caddy fronts the API in front of it.
`cronhoster-config-apiToken`	The bearer token the private API checks on every request.
`cronhoster-config-contentRoot`	Absolute path to the folder of cron directories the sync mirrors up.
`cronhoster-config-tools`	Absolute path to the folder the browser tools write their static site into.