DIN

Docs

Console settings

The local console (din console) can change this install's settings for you, so a paid install never needs a terminal: activating a key, webhooks, capture, autostart, agents and fields. Every control runs the installed din command named beside it, on this machine, and shows you exactly what that command printed. Nothing is changed any other way, so the console and the terminal always agree.

These controls are new in 1.0.32. On an earlier release, run the same din commands in a terminal.

Where the controls are, and who can use them

They are on the local console only: Plan and billing has the activate box, and Settings has the rest. The public demo and a hosted console have neither, and their servers do not answer the settings requests at all.

The local console listens on this machine's loopback address only. A settings request is accepted only from the console's own page: it must carry a random key the console creates each time it starts and puts in the page, and it must come from the console's own address. A page on any other site cannot use them. If the console restarts while a page is open, the page's key is out of date: reload the page. Every settings request, accepted or refused, is written to the console's log by command; a licence key never is.

The rest of the local console is guarded too: it answers only requests addressed to 127.0.0.1, localhost or [::1] on its own port (so a site that re-points its own name at your machine reads nothing), and a billing request from another site's page is refused before it reaches the billing service.

These guards stop web pages, not people with an account on this machine. Every account on a machine can reach its loopback address, and the console serves its page, key included, to whoever asks. On a shared machine another user can therefore read your records through the console and use these settings as you: for example Add agent with its confirmation ticked, which runs the plugin's installer as you, or a webhook to an address of their own. Run the local console on a machine only you log in to, or only while you are using it.

Activate a key (Plan and billing)

Paste your licence key and press Activate. The console runs din activate - with the key on its standard input, never on a command line. It shows your tier, what it turns on and when the current period ends, or the error din gave, and the plan on the screen updates without a restart. See Activate a paid licence for what din activate checks and writes.

Capture and startup

Paths are absolute and matched as a prefix of the directory your agent works in, on whole folder names. On Windows a drive path (C:\work) or a share path (\\server\share\work) is fine and is matched in any case and with either slash; the lists are separated by ; there, so such a path cannot hold a ; or a ". On Linux and macOS the lists are separated by :, so a path there cannot hold a :. Secrets are removed before anything is written, whatever these settings say.

Agents and fields

Webhooks

Webhooks are a paid feature. On the free plan the panel shows what it does and links to the plans, and the console does not run anything for it.

On a paid plan the panel lists your subscriptions and lets you add or remove one (an endpoint URL, a name, and any of the events your field sends: record.new, collision.detected, needs_human.raised, decision.superseded, security.exposed, dependency.changed; the checkboxes come from din webhooks list, so a new event appears with no console update; none ticked means all of them). Send test event posts one event named webhook.test to that endpoint, the way the field sends a real one, and shows the status it answered.

The panel runs din webhooks list, add, remove and test, which write the file your field reads: the one named by FIELD_WEBHOOKS, or webhooks.json beside the field program when that is not set. A running field reads that file again on its next rescan, so adding or removing a subscription needs no restart. If you set FIELD_WEBHOOKS yourself, set it before the field starts (in the environment, or in the install's field.env, which din field start hands to the field).

Use https:// for any endpoint off this machine. The field sends it over TLS with the receiver's certificate and name verified against the Mozilla root store, and a receiver that fails the check gets nothing (the failure shows in din webhooks deliveries). Plain http:// works only for an endpoint on this machine (localhost, 127.x.x.x, [::1]); any other http:// URL is refused when you add it. din webhooks test sends from the terminal over plain http:// only, so for an https:// subscription it tells you to watch din webhooks deliveries after the next event.

An endpoint on this machine (localhost, 127.x.x.x, [::1]) may be unsigned. Any other host needs a signing secret of 16 to 512 characters. The console's form takes it and hands it to din on stdin; from a terminal, pipe it in one line:

printf '%s\n' "$SECRET" | din webhooks add https://host/path --secret-stdin

The secret is never printed or shown again, the console keeps any that are already in the file, and a test event is signed with it like a real one. Signing does not encrypt: over http:// the event travels in clear text.

Each event is a pointer (an id, the project, a timestamp), never a copy of a record.

Verifying deliveries

Every delivery is a POST of a JSON body with these headers:

To verify one: read the raw body before parsing it, compute the HMAC over <X-DIN-Timestamp>.<raw body>, and compare it with the header in constant-time. Then refuse a timestamp outside your replay window (five minutes either side of your clock is the usual choice; the field sets none of its own), and drop a X-DIN-Delivery you have already handled. Answer with a 2xx status; anything else is retried with backoff, and a delivery that never gets through is written to the field's dead-letter file.

From 1.0.39, din webhooks deliveries [id] [--last N] [--json] prints the field's delivery counters since it started and the deliveries that never got through (its dead-letter file), newest last, and the console shows the same as a Deliveries card. Send test event and din webhooks test are refused on a plan without webhooks, and send nothing.