Local

The local package is a small, dependency-free Node program that runs on your machine. It does two jobs: it syncs your queue and user definitions up to the server, and it renders the three log browsers (Web, Server and Task logs) from what the server reports. It keeps no state of its own beyond a local cache of the logs; your folders on disk are the whole truth, and only definitions are synced, never the tasks themselves.

Get the local package

Download the package zip and unpack it anywhere. It needs Node v20+ and nothing else. The whole directory is the package.

Download taskhoster-local-0.1.0.zip →

curl -fLO https://taskhoster.org/downloads/taskhoster-local-0.1.0.zip
unzip taskhoster-local-0.1.0.zip
cd taskhoster-local-0.1.0

Fetch and unpack the local package.

config.json

The config lives separately from the code. Copy config.example.json to a config.json of your own, point it at your server, and paste the master token the installer printed. Every key is prefixed taskhoster-config-; unknown keys are refused.

{
  "taskhoster-config-serverAddress": "203.0.113.7",
  "taskhoster-config-apiToken": "paste-the-master-token-from-the-installer",
  "taskhoster-config-contentRoot": "/home/you/taskhoster/queues",
  "taskhoster-config-tools": "/home/you/taskhoster/_tools"
}

The local package's config.json; values are illustrative.

Name	Type	Description
`taskhoster-config-serverAddress`	address	Your server's IP (or a full URL). The management surface is reached by bare IP over HTTPS with a self-signed certificate, which the package tolerates automatically. Required.
`taskhoster-config-apiToken`	string	The master token from `/etc/taskhoster/token`. Required.
`taskhoster-config-contentRoot`	path	Absolute path to the directory that holds your queue-host folders. Required.
`taskhoster-config-tools`	path	Absolute path where the log browsers are written. Optional; the log commands do nothing without it.

Keep config.json out of version control: the master token is a credential. Both paths must be absolute, so the config means the same thing wherever you run it from.

Lay out a queue folder

Under your contentRoot, make a folder named for the queue's domain, with a taskhoster-queues/ directory holding one JSON file per queue and a taskhoster-users/ directory holding one file per user. (See Queues for the definition format.)

/home/you/taskhoster/queues/     (contentRoot)
  task.example.com/              a queue host — one domain
    taskhoster-queues/
      resize.json                 the "resize" queue → /resize on that domain
    taskhoster-users/
      alice.json                  a user → { "taskhoster-name": "alice", "taskhoster-token": "<32 hex>" }

One domain folder, its queues and its users.

Sync your queues up

Run the package with your config and the --sync command. It validates every queue and user definition locally, reads the server's manifest, and uploads only the ones whose contents changed, deleting any the server has that you no longer keep. A broken definition is rejected before anything reaches the server, naming the file and the problem.

node taskhoster-local.js --config /home/you/taskhoster/config.json --sync

Mirror your definitions to the server. --config is required and absolute.

It does one pass and exits, so run it whenever you change a definition: by hand, from your editor's save hook, or on a timer for continuous sync.

Define users and mint their tokens

Access is granted to users you define in the domain's taskhoster-users/ folder. Each user file is { "taskhoster-name", "taskhoster-token" }; the token is a 32-character hex string you author. Any source of random hex works:

node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"
# -> 0123456789abcdef0123456789abcdef

Mint a 32-hex user token to paste into a user file.

Create task.example.com/taskhoster-users/alice.json with that token, list alice in the relevant queue's taskhoster-access rules, and --sync again. Callers then present the token as Authorization: Bearer <token> (or ?token= on a socket).

Tokens live only in your user files (synced up as plaintext). To rotate one, change it in the file and sync; to revoke a user from a queue, drop its name from that queue's access rules.

The log browsers

With taskhoster-config-tools set, the same command builds three static log browsers into that folder — pass the ones you want, or --all to do the sync and all three:

node taskhoster-local.js --config /home/you/taskhoster/config.json --all

Sync, then build the Web, Server and Task log browsers.

Command	Builds
`--web-logs`	Web Logs — Caddy's access log, per queue domain.
`--server-logs`	Server Logs — the box's CPU, memory, disk and network health.
`--task-logs`	Task Logs — every queue's durable task history, mirrored down and kept.

Each browser is a folder of static HTML under your tools directory; open its index.html in a browser. The log data is mirrored down incrementally and kept locally, so your history outlives the server's rolling window.