Local

The local package is the Taskhoster code that runs on your own machine. It is one self-contained directory, taskhoster-local-<version>, and that directory is the download: zip the folder and you have the bundle, so the tree you see here is byte-for-byte the tree in the zip. You run the one command inside it, taskhoster-local.js, which parses the command line, loads your config, and dispatches one command per line: sync (mirror your queue definitions up), the two universal browser tools, and Taskhoster's own Task Logs tool. The package is in four parts: localhoster-common/, the shared toolkit every hoster carries; localhoster-tools/, the two universal browser tools; taskhoster-tools/, this hoster's own tool; and taskhoster-sync/, the sync command. This page is the file map, then a section per part.

taskhoster-local-<version>/                  unzips from taskhoster-local-<version>.zip
  taskhoster-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, byte-identical across every hoster
    index.js                                  the single require surface (loadConfig, toolsSite, recordRun, the UI kit)
    net.js                                    config load, the API client, the version probe
    run.js                                    the tools-site frame + recordRun
    shell.js                                  the page frame: strip, tabs, status, stylesheet
    ui.js                                     the UI kit: tables, cards, charts
    format.js                                 the formatters: esc, numbers, bytes, dates
    io.js                                     small IO helpers
  localhoster-tools/                          the universal tools, one dir each
    web-logs/
      index.js                                { key, label, run(config) }: pull, then render
      lib/
        pull.js                               mirror the access logs down incrementally
        render.js                             build the Web Logs pages
    server-logs/
      index.js                                { key, label, run(config) }: pull, then render
      lib/
        pull.js                               mirror the server stats down incrementally
        render.js                             build the Server Logs pages
  taskhoster-tools/                           this hoster's own tool
    task-logs/
      index.js                                { key, label, run(config) }: pull, then render
      lib/
        pull.js                               mirror the task-event day-files down
        render.js                             build the Task Logs pages
  taskhoster-sync/                            the sync command
    index.js                                  run(config): mirror the queue-host folders up
    lib/
      scan.js                                 walk the content root into queue and user files
      schema.js                               validate a queue definition before it is pushed
      paths.js                                the fixed folder names the scan looks for
      version.js                              the pinned API version

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

Name	Type	Description
`taskhoster-local.js`	file	The one command you run. It parses the command line, loads the config, and dispatches one command per line.
`localhoster-common/`	directory	The shared toolkit, byte-identical across every hoster: the config loader, the tools-site frame, and the UI kit.
`localhoster-tools/`	directory	The two universal browser tools shared across every hoster: Web Logs and Server Logs.
`taskhoster-tools/`	directory	This hoster's own tool: the Task Logs browser and the pull and render behind it.
`taskhoster-sync/`	directory	The sync command: it mirrors your queue-host folders up, with its own self-contained copies of the scan, schema and version.
`config.json`	file	The local config: the server address, the API token, and the two paths the local package reads and writes.

taskhoster-local.js

The command you run. It takes a mandatory --config pointing at an absolute path to a .json file, validates that path before anything runs, loads it into a frozen config object, and then runs one command per switch. Each command is one explicit dispatch line, sync first, so the flow reads top to bottom. Each tool derives its own paths from the config, so running one never touches another's pages.

Switch	What it does
`--config <path>`	Absolute path to the local config JSON. Required, validated before any work, and must end in `.json`.
`--sync`	Mirror your queue-host folders up to the server.
`--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.
`--task-logs`	Mirror the task events down and build the Task Logs browser.
`--all`	Everything in one process: sync and all three browser tools.

The --config path must be a full absolute path to a .json file, and it is validated before anything else happens: a relative path, a missing path, or one that does not end in .json stops the run before any sync or render.

The shared toolkit

The files under localhoster-common/ are the shared toolkit. They are byte-identical across the hoster family, so a sibling hoster's local package is a short entry on top of the same engine. The one exception is net.js, which carries the taskhoster-config- key names. 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`	Loads and validates the config into a frozen object, the API client that talks to the private server API, and the version probe that keeps request paths on the server's API version. This is the one file that differs between hosters, carrying the `taskhoster-config-` key names.
`localhoster-common/run.js`	The tools-site frame plus `recordRun`. It assembles the overview (one card per tool) and records each tool's last run, 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, and pagination.
`localhoster-common/format.js`	The canonical formatters: escaping, numbers, bytes, durations, and date labels.
`localhoster-common/io.js`	Small render and IO helpers.

The universal tools

The files under localhoster-tools/ are the two browser tools every hoster carries. Each tool is a directory whose index.js exports { key, label, run(config) } and a private lib/. Its lib/pull.js mirrors the server data down incrementally and its lib/render.js builds the static HTML.

Name	Description
`localhoster-tools/web-logs/index.js`	The Web Logs tool, key `web`. 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`	Builds the Web Logs pages, a static self-contained site over the mirrored access logs.
`localhoster-tools/server-logs/index.js`	The Server Logs tool, key `server`. 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`	Builds the Server Logs pages, charting every metric across days and hours.

Taskhoster's own tool

The files under taskhoster-tools/ are this hoster's own. The Task Logs tool, key task and labelled "Task Logs", follows the same tool shape: its index.js exports { key, label, run(config) }, and its lib/ holds the pull and render.

Name	Description
`taskhoster-tools/task-logs/index.js`	The Task Logs tool. It pulls the task events down, then builds the browser.
`taskhoster-tools/task-logs/lib/pull.js`	Pulls the task-event day-files, and any archived payloads, from the server's `/tasks` routes into a local `_data` and `_payloads` cache, incrementally so its history outlives the server's short retention.
`taskhoster-tools/task-logs/lib/render.js`	Renders the Task Logs browser from the local cache: an overview, a page per queue, and a page per task with its full event timeline.

taskhoster-sync

The sync command mirrors your queue-host folders up to the server. Its index.js is the command; its lib/ holds its own self-contained copies of the scan, the schema and the fixed folder names, plus the pinned API version. It requires no file outside the package, so the directory is complete on its own.

Name	Description
`taskhoster-sync/index.js`	The sync command. `run(config)` reads the content root, compares each queue host to the server, and pushes the definitions that differ.
`taskhoster-sync/lib/scan.js`	Walks the content root into each queue host's queue and user files, its own copy of the scan.
`taskhoster-sync/lib/schema.js`	Validates a queue definition before it is pushed, its own copy of the schema check the server also runs.
`taskhoster-sync/lib/paths.js`	The fixed folder names the scan looks for inside a queue host: `taskhoster-queues/` and `taskhoster-users/`.
`taskhoster-sync/lib/version.js`	The pinned `API_VERSION`, which forms the `/api/vN` path prefix. 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 package reads and writes. Both paths must be absolute, and any key not below is refused. The Local usage page walks through each key, and the download is taskhoster-local-0.1.0.zip.

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

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

Name	Type	Description
`taskhoster-config-serverAddress`	address	The server's IP or full URL. Required.
`taskhoster-config-apiToken`	string	The master token from `/etc/taskhoster/token`. Required.
`taskhoster-config-contentRoot`	path	Absolute path to your queue-host folders. Required.
`taskhoster-config-tools`	path	Absolute path where the log browsers are written. Optional.

Both taskhoster-config-contentRoot and taskhoster-config-tools must be absolute paths, and an unknown key is refused before the run begins.