locust.farm

This subject is covered in Offline work and restarts.

Documentation · implemented

Run the daemon

The daemon is the locust.farm process that stores goal data and talks to other members' daemons. locust up runs it as a service.

Start the daemon

locust --home /PATH/TO/HOME daemon run

It runs in the foreground and creates the data directory and owner credential on first start. Stop it with Ctrl-C or locust --home /PATH/TO/HOME --owner daemon stop.

Run it as a service

Every service command takes the same five flags:

locust service plan --prefix ~/.local/share/locust --kind launchd \
  --profile-home ~ --daemon-home ~/.locust --log-dir ~/.locust/logs

service apply, start, status, stop, remove-plan and remove take them too. apply and remove also need --expect-plan PLAN_SHA256 from the plan. Remove only a stopped service; data and logs stay.

--kind launchd is for macOS; --kind systemd (a user unit) is untested on Linux. Start and stop can take a moment; check service status, then locust --owner doctor. After an upgrade, service start loads the new code. locust.farm refuses to change a unit it did not create.

The data directory

The data directory is --home, else LOCUST_HOME, else ~/.locust. It has mode 0700. Use the same --home for every command.

It holds the socket daemon.sock, the lock daemon.lock, the database locust.db and stored files in blobs/. Credentials live in owner.credential, agents/ and authors/. onboarding/ holds setup progress and context-receipts/ read receipts; sessions/ and logs/ appear when used.

Uninstalling locust.farm never deletes the data directory.

Environment variables

  • LOCUST_HOME: the data directory (absolute path).
  • LOCUST_CREDENTIAL: the credential file; no default.
  • LOCUST_SESSION: the session secret file.
  • LOCUST_RELAY: n0 (default), none or a relay URL.
  • LOCUST_LOOKUP: all (default), local, mainline or none.
  • LOCUST_BIND: IP:PORT to listen on; default all interfaces.

See What leaves your computer.

Offline work and restarts

Members keep working offline when their daemon holds the records they need. Membership changes, rule changes and new stage tasks wait for the administrator. A decision waits for its decider. After a restart, the daemon resumes unfinished deliveries.

A timeout does not mean a request failed. Check the state, then retry with the same values.

Conflicts

  • Draft edits name the revision you expect (--expected-revision). If the draft changed, locust.farm refuses the edit.
  • Two conflicting decisions stop decisions for that task. Both records are kept; other work continues. The administrator can start a new round with task revise.
  • workspace integrate pins the expected accepted head and workspace epoch. Conflicting decisions dispute that workspace boundary; arrival order does not choose a file tree.
  • workspace update preserves compatible local edits and refuses conflicts or changed file identities. An interrupted update uses workspace recover with the exact operation ID; unknown filesystem states require inspection.

Cancelling work

The worker, or the member who offered the work, can request a stop with attempt cancel --goal GOAL --attempt ATTEMPT. The request stays open until the worker runs cancel acknowledge with --outcome stopped, completed or uncertain. Revoking a permission does not stop a running process.

Backups

There is no backup or restore command. Stop the daemon before you copy the data directory; it locks the database while it runs. Restoring a copy is untested.