Account

App page

Account settings live in two places: Manage Account for the account as a whole, and Account Profile for your own sign-in and security.

Where to find it

The account button sits at the right of the top bar and shows your initials. It opens a menu with:

• Profile card: your name, email, role and plan. Select the plan badge to open Plan & Features.
• Manage Account: opens the account settings described below.
• Account Profile: opens your own profile and security settings.
• Log out.

What you see

Account Profile

Account Profile has two tabs.

• Profile: your display name and personal preferences. Select Save Profile to keep changes.
• Security: the Passkeys card and the Two-factor authentication card. See Two-factor authentication.

Manage Account tabs

The tabs are grouped in the left rail. Some tabs appear only for roles that can use them.

People & Access

• Team Access: team members, their roles, status and organization-group membership. The Workspace setup checklist is also here. Disable signs a member out and stops them signing in; Reactivate restores access. You cannot disable yourself. Revoking an invitation disables the invited user.
• Roles & Permissions: the standard role bundles and the account's custom roles. A custom role cannot take a standard role name. Its access comes from the standard roles it includes, not from its name. Members of an Inactive custom role have no permissions, and an Inactive role cannot be assigned. A role that includes Owner, or the role you hold, cannot be made Inactive.
• Organization Groups: groups, when the plan includes them. An Inactive group gives its members no access to its resources. The default group cannot be made Inactive.
• Sign-in policy: whether the account requires passkeys, shown read only, and SAML sign-in through your identity provider. See Single Sign-On.

Plan & Billing

• Plan & Features: the current plan and what it includes. Version history is on every plan. SAML single sign-on is on Teams and Business.
• Billing & Usage: plan changes, payment, invoices, Milo AI Usage and Registration status. See Account billing.

Resources

• Variables: global variables, including secret values and per-environment values.
• Caches: global cache entries. Builders, Admins and Owners can add, edit and delete caches. Other roles can view them.
• Message Templates: reusable templates for notifications and email actions. Builders, Admins and Owners can create, edit, import, restore and delete templates. Other roles can view and preview them.
• Webhooks: inbound webhooks that start runs. See Webhooks below.
• Log Destinations: stream the account's logs to Datadog, Grafana Loki, Elasticsearch or Splunk. See Log Destinations.
• GitHub: connect GitHub for project backup. See GitHub backup.
• Private Agent: request, enrol and install a runtime on your own server. See Private Agent below.

Governance

• Audit Log: shown to roles with audit read access. Search, filter by date and export to CSV. Covers the last 90 days.
• Notifications: the account's e-mail settings. See Notifications below.
• Configuration: IP restrictions, a link to Webhooks and a link to Human Approvals. See Configuration below.

Notifications

Owners and Admins see two cards. Other roles see that the tab is for Owners and Admins.

• Run Notifications: e-mails a report when a data pipeline run finishes. See Run notifications.
• Operational alerts: who is e-mailed when a runtime stops sending heartbeats, after how long, and how often the alert repeats. While it is on, its recipient is also added to webhook dead-letter e-mail and connection health e-mail, which Owners and Admins always receive. See Runtime unreachable alerts.

Webhooks

The tab lists every webhook in a table with its sender, project, last delivery, status and how many deliveries are in dead letter. Search by name or by the webhook ID in its URL, filter by sender, project, status or Has dead letter, and sort by name or last delivery.

• New webhook opens a panel with the create form: name, project, signature and its fields. The secret, URL or verify token is shown once in that panel after Create webhook.
• Select a webhook to open it. The panel shows its inbound URL with a copy button, the setup steps for its sender and its project, with Deliveries, Test, Settings, Rotate, Delete and, where they apply, Pages, Rotate verify token and Revoke old secret.
• Deliveries lists recent deliveries with their status, the reason for any refusal, the run each one started, and its payload. Deliveries are retried automatically; one that still fails moves to dead letter. Failed and dead-lettered deliveries can be replayed one at a time or all at once.
• A hosted form's webhook is managed by its form. Its panel offers Deliveries and Delete, and links to Hosted Forms.

Owners and Admins manage webhooks. Other roles see the list and each webhook's details only.

Configuration

• IP restrictions: limit sign-in to networks you approve. Other roles see the mode and the networks. See IP restriction.
• Webhooks: Open webhooks goes to the Webhooks tab.
• Human Approvals: Open approvals goes to the Human Approvals page, which lists approval requests created by Approval nodes, filtered by status (Pending, Approved, Rejected, TimedOut) and date. You can approve, reject, and resend the approve and reject links through the request's channel there.

Controls that only Owners and Admins can use are not shown to other roles. The card says Owner and Admin only instead.

Roles

• Owner: full access; owns the account.
• Admin: manages team access, billing and account settings. Owners are managed only by an Owner.
• Builder: designs and deploys data pipelines and manages connections.
• Viewer: read-only across the platform.
• Auditor: read-only, with audit log export.

Only an Owner can include the Owner role in a custom role.

Only an Owner can change an Owner's role, disable or reactivate an Owner, or edit or delete a custom role that includes Owner. These controls are hidden from Admins.

An account always keeps at least one active Owner. Disabled Owners do not count. A change that would remove the last active Owner is refused. Promote or reactivate another Owner first.

When a change is refused, the reason is shown.

Variables

Two scopes:

• Global variables apply across the account. Use them for values many flows share, such as an API key.
• Per-environment values let DEV, QA and Production use different values under the same variable name.

Give a variable the secret type to mask it after save. A secret value is never returned to the browser.

Session timeout

Sessions time out on inactivity, not on total length. A session stays open as long as you keep using the app.

After a period with no activity, a Session expiring soon panel locks the page and counts down. It shows how long you have been inactive and how long is left. Choose Continue Session to carry on, or Logout Now. When the countdown reaches zero you are signed out.

Common tasks

Write a message template

Open Manage Account > Message Templates and choose a scope:

• Global: account-level reusable templates.
• Project: templates tied to one project. Select the project before you create or edit one. When organization groups are on, a project template is visible only to members of the project's group, and to Owners.

Templates are available in Notification actions and SMTP email target actions. Each template has a name, description, scope, format (text, HTML or Markdown), subject template, body template, an optional DataLug HTML wrapper, and version history.

Template syntax includes {{var.exec.runId}}, {{sys.project.name}}, and {% if %} and {% for %} blocks.

How each format is delivered:

• Text: sent as plain text.
• HTML: email receives the HTML body, with a plain-text copy for mail clients that do not show HTML.
• Markdown: email receives the Markdown converted to HTML, with the Markdown source as the plain-text copy. Slack, Teams and Discord receive the Markdown source, which they format themselves.

The DataLug HTML wrapper applies to HTML and Markdown email.

In HTML and Markdown templates, variable values are inserted as plain text, so a value cannot add markup or links. In Markdown templates, HTML tags written in the template show as text, and links work only when they start with http://, https:// or mailto:.

The preview renders the template with global, project, execution and system variables before you save it. Sensitive values are masked in the preview.

Search and export the audit log

Open Manage Account > Audit Log. When audit logging is on, the log records every change made in the account: who did what, when, and to which object. Search by user, action, entity type, entity name or route, filter by date, and export to CSV. A search with more than 10,000 matches shows the row count as More than 10,000.

The audit log in the app covers the last 90 days. Older entries are kept in an archive; contact support to request them.

Set up a Private Agent

Request one, create a claim code and a registry token, then install the agent on your server. Each step is under Private Agent below.

Private Agent

A Private Agent is a DataLug runtime you run on your own server. It connects out to DataLug and accepts no inbound connections, so it can reach systems that are not published to the internet.

Private Agents are available on the Teams and Business plans. The plan includes one Private Agent host, which serves one agent per environment.

Requesting one

Go to Manage Account > Private Agent and submit a request. Describe the server you plan to run the agent on, and why you need one. DataLug does not provision that server.

The DataLug team reviews each request. Until then the request reads Awaiting DataLug review.

Once approved, the request reads Waiting for the agent to enrol. It reads Active once an agent enrols with a claim code, and the request's environment then runs on that agent.

Claim codes

Once a request is approved, an Owner creates a claim code and the agent uses it to enrol.

• Choose the environment the agent serves, then select Create a claim code. The environment named in the request is chosen for you. With one environment it is chosen for you.
• If the account has no environments, create one under Environments first.
• Only an Owner can create a claim code. Admins can see and revoke them. Other roles do not see the list.
• Only an Owner can get the install file and the bundle.
• The code is shown once and cannot be retrieved. Create another if you lose one.
• A code expires 15 minutes after it is created, and can be used once.
• Revoke an unused code from the same screen.

Registry tokens

The agent image is pulled from the DataLug registry. Each server signs in with a registry token that starts with dlrt_.

• Only an Owner can create a registry token. Admins can see and revoke them. Other roles do not see the list.
• Name each token after the server that uses it.
• The token is shown once and cannot be retrieved. Create another if you lose one.
• The list shows each token's first characters, its status, when it was created and when it was last used.
• An account can have up to 10 active tokens.

To create one, go to Manage Account > Private Agent > Registry tokens, enter a name and select Create token. Copy the token before you leave the page.

To revoke one, select Revoke next to the token and confirm. Servers using that token cannot pull the agent image. An agent that is already running keeps running. Create a new token and sign in again before the next pull.

Installing with one command on Linux

Manage Account > Private Agent > Install with one command shows a command for your DataLug address. Create a claim code first: while the code is on screen, the command includes it. Copy the command and run it on the server as root within 15 minutes of creating the code.

The installer supports Ubuntu 22.04 and 24.04 and Debian 12 and 13, on x64 with systemd. On any other system it stops before changing anything. It:

1. Installs the agent's prerequisites from their vendors' signed package repositories if they are missing.
2. Downloads the Private Agent bundle with the claim code. The code is sent as a request header and is never written to a file or a log. A code that is expired, used or revoked is refused, and so is an account whose plan does not include a Private Agent.
3. Checks every file against the SHA-256 hashes in MANIFEST.json, pulls the image by its pinned digest and checks the digest it received.
4. Asks for a registry token when the server has no registry sign-in. To skip the prompt, add --pull-token-file <file> to the command.
5. Installs the agent in /opt/datalug-agent, starts it once with the claim code, waits for it to enrol, then runs it as the datalug-agent service.

Running it again with a new claim code is safe. It replaces the files, keeps .env and the agent's identity, and does not enrol again.

Add --dry-run to check the server and the bundle without changing anything.

The SHA-256 of the installer script is shown beside the command. To check it first, save the script, compare its sha256sum with that value, then run it with sudo sh and the same options.

The command downloads the script from /install/agent.sh on your DataLug address, and its SHA-256 is at /install/agent.sh.sha256.

Installing on Windows

The Windows installer needs Windows 10 22H2 or Windows 11 on x64. It needs WSL 2 and Docker Desktop set to Linux containers, and checks both. It stops if either is missing, and does not install them.

Select Windows under Install with one command and run the command in PowerShell as Administrator within 15 minutes of creating the claim code. Download agent.ps1 saves the script, with its SHA-256 shown beside it. The script is also at /install/agent.ps1 on your DataLug address.

The installer downloads and checks the bundle as on Linux, installs the agent in C:\ProgramData\DataLug\Agent, readable only by Administrators, SYSTEM and you, and adds two scheduled tasks for your user: one starts the agent when you sign in, and one applies updates when auto-update is on. The agent runs only while a user is signed in.

To remove the agent, run the script with -Uninstall. The agent's identity is kept for a reinstall. Add -RemoveData to delete it; the agent then needs a new claim code.

Installing the agent

The server needs Linux with systemd, Docker Engine with the Compose plugin, and outbound HTTPS (port 443) to your DataLug address and the registry host. No inbound ports.

An Owner selects Download bundle under Manage Account > Private Agent to save datalug-private-agent.zip. It holds docker-compose.yml, an .env file, the datalug-agent.service systemd unit, the datalug-agent-update updater with its service and timer, the Windows updater datalug-agent-update.ps1, a README.md and a MANIFEST.json with the pinned image and a SHA-256 hash of each file. The bundle contains no secret. If your plan does not include a Private Agent, the download is refused with a message saying so.

1. Create a registry token, as above.

2. Unzip the bundle on the server. From the unpacked folder, sign in to the registry and pull the image. Paste the token at the prompt that read -rs opens. The user name is always datalug, and the registry host is shown under Manage Account > Private Agent.

   read -rs DATALUG_PULL_TOKEN
   printf '%s' "$DATALUG_PULL_TOKEN" | sudo docker login <registry host> -u datalug --password-stdin
   unset DATALUG_PULL_TOKEN
   
   sudo mkdir -p /opt/datalug-agent
   sudo cp docker-compose.yml .env /opt/datalug-agent/
   sudo chmod 600 /opt/datalug-agent/.env
   sudo docker compose -f /opt/datalug-agent/docker-compose.yml pull

3. Create a claim code under Manage Account > Private Agent > Claim codes, choosing the environment the agent serves. Set it in /opt/datalug-agent/.env as DLR_AGENT_CLAIM_CODE:

   sudoedit /opt/datalug-agent/.env

4. Install and start the service within 15 minutes of creating the claim code:

   sudo install -m 0755 datalug-agent-update /opt/datalug-agent/
   sudo cp datalug-agent.service datalug-agent-update.service datalug-agent-update.timer /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable --now datalug-agent
   sudo systemctl enable --now datalug-agent-update.timer

5. Once the agent shows online, clear DLR_AGENT_CLAIM_CODE in .env. The agent keeps its identity in the datalug-agent-data volume, so later starts do not need a code. Keep that volume. If it is deleted, create a new claim code.

DLR_API_BASE in .env is your DataLug address. It is filled in for you.

Get the install file downloads the compose file on its own, for a server that runs the agent without the systemd unit.

To stop the agent, run sudo systemctl disable --now datalug-agent.

Checking the agent is live

Go to Environments and select the environment you chose for the claim code. The agent card on the Overview tab shows its latest heartbeat, and the environment badge reads Runtime Ready once the first heartbeat arrives. Until then it reads Runtime Unreachable, and the environment list shows NO HEARTBEAT. See Environments for the heartbeat states.

On the server, sudo systemctl status datalug-agent shows whether the service is running, and sudo journalctl -u datalug-agent -f follows its log.

Versions and updates

Manage Account > Private Agent > Versions and updates lists each Private Agent with the version it runs and the latest version.

• Update available appears as soon as a newer version is published. After 14 days the agent reads Update reminder and the page shows how many agents are behind, and after 30 days it recommends the update.
• Security update required: 90 days after a newer version with a security fix is published, an agent still on an older version stops taking new work until it is updated.
• Below minimum version: DataLug sets a minimum version, rarely and with notice. An agent below it stops taking new work until it is updated.

In both cases a run already in progress finishes, and the agent's log says why it is not taking new work.

Update to shows the command to run on the server, for Linux and for Windows. It moves the agent to the new image by its digest:

sudo /opt/datalug-agent/datalug-agent-update --image <image>@sha256:<digest>

Roll back shows the same command for each of the last three images the agent ran. A rollback is never automatic. The updater keeps the previous configuration file beside the current one.

Auto-update is off unless an Admin or Owner turns it on for an agent:

• Patch updates moves the agent to the newest release with the same major and minor version.
• Minor updates moves it to the newest release with the same major version.

An automatic update never moves to a new major version. The server checks for an update every 30 minutes. If the agent does not start on the new image, the updater prints the command to go back.

Release webhook

Manage Account > Private Agent > Release webhook sends a POST request to your endpoint when a new Private Agent version is published. Owners and Admins set it up.

1. Enter an HTTPS Endpoint URL, leave Enabled on, and select Save.
2. Copy the signing secret. It is shown once and cannot be retrieved later.
3. Select Send test to send a test delivery. The card shows whether it was delivered and the HTTP status your endpoint returned.

The card shows the last delivery: its status (delivered, failed or retrying), when it was sent and the version it announced. Turn Enabled off to pause deliveries without removing the webhook.

Rotate secret creates a new signing secret and shows it once. The previous secret stops working, so update your endpoint with the new one.

Each delivery is a JSON body with one of two event types:

• agent.release.published: a new Private Agent version is available.
• agent.release.test: a test sent with Send test.

When several versions are published together, one delivery is sent for the newest. A delivery that gets a 408, 429 or 5xx response, or no response, is retried with the same delivery id. Any other 4xx response is not retried.

Payload fields

Both event types have the same fields. A test delivery describes the newest published version.

Field	Type	Meaning
type	string	agent.release.published or agent.release.test.
id	string	Delivery id. The same on every retry of one delivery.
createdAt	string	When this attempt was sent, ISO 8601 in UTC.
release	object or null	The version announced. null on a test when no version is published.
release.version	string	Version number, for example 1.4.2.
release.digest	string	Image digest, sha256: followed by 64 hex characters.
release.publishedAt	string	When the version was published, ISO 8601 in UTC.
release.security	boolean	true when the version contains a security fix.
release.notesUrl	string or null	Release notes link, or null when there is none.
minimumVersion	string or null	Oldest version that may still run work, or null when none is set.
agents	object	Counts over the account's Private Agents.
agents.total	number	Private Agents on the account.
agents.behind	number	Private Agents with a newer version available.

{
  "type": "agent.release.published",
  "id": "arwd_1762430400000_3f9a1c",
  "createdAt": "2026-11-06T12:00:00.000Z",
  "release": {
    "version": "1.4.2",
    "digest": "sha256:<64 hex characters>",
    "publishedAt": "2026-11-05T00:00:00.000Z",
    "security": false,
    "notesUrl": "https://example.com/notes/1.4.2"
  },
  "minimumVersion": "1.2.0",
  "agents": { "total": 3, "behind": 1 }
}

Headers

Header	Meaning
X-DataLug-Event	The event type, the same as type.
X-DataLug-Delivery	The delivery id, the same as id. Use it to ignore a repeat.
X-DataLug-Signature	t=<unix timestamp>,v1=<signature>. See below.
Content-Type	application/json.
User-Agent	DataLug-Webhooks/1.

Verify the signature

Every delivery carries an X-DataLug-Signature header:

X-DataLug-Signature: t=<unix timestamp>,v1=<signature>

The signature is the hex-encoded HMAC-SHA256 of <t>.<body>, keyed with your signing secret, where <t> is the timestamp from the header and <body> is the raw request body exactly as received. To verify a delivery:

1. Split the header on , and read t and v1.
2. Compute HMAC-SHA256 over the string <t>.<body> with your signing secret.
3. Compare your result with v1 using a constant-time comparison.
4. Reject the delivery if t is more than a few minutes old.

import crypto from "node:crypto";

function verify(header, rawBody, secret) {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return (
    fresh &&
    expected.length === String(parts.v1).length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
  );
}

Network requirements

• Outbound HTTPS from the server to your DataLug address and the registry host. No inbound ports.
• The agent signs every request with its own key. It never needs a DataLug sign-in token.
• If your network inspects TLS, make your proxy's CA certificate available to the agent and set NODE_EXTRA_CA_CERTS to its path.

If your plan changes

If you move to a plan without Private Agents, the agent keeps working for 14 days. After that it finishes any run it has already started and stops taking new work. Its certificate is not revoked, so you can still use it to move data off the server.

What a Private Agent run shows

Run status is accurate. Node row counts, sample rows and logs stay on your own server until the run finishes. See Runtime Executions for stopping a run on a Private Agent.