Enrolling hosts with join keys

An enrollment code enrolls one host, which you create ahead of time. A join key is a reusable enrollment code: any number of machines can enroll with it, and each one joins as a new host with the key’s network, role, and tags. Join keys suit machines that come and go without anyone creating a host for them first, like CI runners, autoscaling groups, and devices rolled out through mobile device management (MDM).

Creating a join key

Go to Settings > Host join keys in the admin panel and add a key. Fill in:

• Name: identifies the key, and names hosts that don’t report a hostname (see How enrolled hosts are named). It may contain only lowercase letters, digits, and hyphens, and can’t start or end with a hyphen.
• Network: the network every enrolled host joins.
• Role (optional): the role every enrolled host gets.
• Tags (optional): the tags every enrolled host gets.
• Also assign an IPv4 address to enrolled hosts: shown for dual-stack networks. Check it to give each host an IPv4 address as well as an IPv6 one.
• Expiration: when the key stops enrolling hosts. Hosts it already enrolled stay enrolled.

After you save, the admin panel shows the key’s token, which starts with dnjoin-. The token is shown only once, so copy it somewhere safe before leaving the page.

The network, role, tags, and IPv4 setting can’t be changed after the key is created. Only the name and expiration can be edited. To enroll hosts with a different configuration, create a new key.

Enrolling a machine

Install DNClient on the machine, then enroll it with the join key’s token the same way you would with a single-use enrollment code:

sudo dnclient enroll -code dnjoin-XXXX

With the DNClient Docker image, pass the token in the DN_ENROLLMENT_CODE environment variable:

docker run \
    --name dnclient \
    --network host \
    --cap-add NET_ADMIN \
    --volume defined:/etc/defined \
    --env DN_ENROLLMENT_CODE="dnjoin-XXXX" \
    --rm \
    definednet/dnclient

The token is only needed on the first run, since the volume keeps the host’s configuration across restarts. Without the volume, every run enrolls as a new host. Nothing removes the earlier hosts, so they keep their IP addresses and count against your host limit.

How enrolled hosts are named

A host enrolled with a join key is named after the machine’s hostname, converted to lowercase letters, digits, hyphens, and dots. If another host on the network already has that name, a random suffix is added, like runner-a1b2c3.

If the machine doesn’t report a usable hostname, the host is named after the key instead, with a random suffix: a key named ci-runner enrolls hosts like ci-runner-k3x9q2ab.

Revoking and expiring join keys

To stop a key from enrolling more machines, open it from the Host join keys page and revoke it. A key also stops working once it passes its expiration date.

Either way, hosts the key already enrolled stay enrolled. To remove them from your network, delete or block them like any other host.

A network or role can’t be deleted while a join key still references it. Revoke the key first.

Keeping tokens safe

Treat a join key token like a password: anyone who has it can add machines to your network. Store it where your tooling keeps other secrets, such as your CI provider’s secret store or your MDM’s configuration payload, and avoid committing it to source control or baking it into images that are shared outside your organization. Setting an expiration limits how long a leaked token is useful.

To rotate a join key:

1. Create a new join key with the same network, role, and tags.
2. Update your CI secrets, MDM payloads, or launch templates with the new token.
3. Revoke the old key.

Join keys in the audit log

When a machine enrolls with a join key, the audit log records the new host with the join key as the actor, so you can trace each host back to the key that enrolled it. Creating, editing, and revoking join keys are recorded too.

Managing join keys with the API

Join keys can also be managed with an API key. Grant it the join-keys scopes it needs, for example join-keys:create for a script that creates keys. See Create join key and the other join key operations in the API reference.