Use this method for a server, container, or any machine you can run a command on. The machine generates an Ed25519 key pair, keeps the private half, and signs every request with it, so there is no credential to store or rotate. For a workflow that authenticates with a token GitHub mints for each run, see GitHub Actions. To enroll many machines from one reusable token, see Machine tokens.
Add the machine#
Open Machines and use the
+at the top right of the table.Leave the method set to Command and select Continue.
Name the machine something you will recognize later, such as its hostname or the role it fills.
Choose the Connection, described below, then select Create token.
Your Burrow shows the command to run on that machine. Copy it and keep it for the next step.
Where your Burrow is reachable from outside your own network you get two commands. Reachable from anywhere works from any network. On your network uses the Burrow's local address. Copy the one that matches where the machine lives. If only the local command appears, the Burrow states the reason underneath it.
Connection#
Connection sets how the machine trusts your Burrow when it connects. You pick it before creating the token, and it is carried in the command.
Connection | What it does |
|---|---|
Encrypted | The connection is encrypted, but the Burrow's identity is not checked. Works everywhere, including behind a tunnel or proxy. This is the default. |
Encrypted + verified | The machine checks this Burrow's identity, so nothing can impersonate it. Recommended. |
When you choose Encrypted + verified and your Burrow serves its own certificate, a second choice appears, Verify by:
Verify by | Use when |
|---|---|
Burrow identity | The Burrow is reached directly and presents its own certificate. |
System trust | The Burrow is behind a proxy or CDN that presents its own certificate. |
On a publicly-trusted certificate, for example one from Let's Encrypt, verified always uses system trust and there is nothing to choose.
Run the command#
The machine needs Node, which is what supplies npx. The dialog lists the install command for each platform:
Platform | Install Node |
|---|---|
Linux |
|
macOS |
|
Windows |
|
Then run the command you copied. It looks like this:
npx @ratelkey/cli machine bootstrap <code>The CLI generates a key pair on that machine, sends the public half to your Burrow with the invitation code, and keeps the private half locally. The machine appears on the Machines page with its key fingerprint, and the name you gave it in the dashboard is the one it keeps. From then on it signs each request with its key, so there is nothing further to configure and no credential to rotate.
Invitations you have not used yet#
Outstanding invitations sit under Active Machine Invitations below the machines table, with when they were created and when they expire. Their row menu carries Copy command, which rebuilds the command from where your Burrow is now, so an invitation still works after the Burrow moves or gains a domain, and Revoke, which cancels it.
Approval#
By default a machine is active the moment it bootstraps, since creating the invitation was the permission.
Turn on Require machine approval under Settings, Security to confirm each one yourself. New machines then arrive carrying a Pending tag and read nothing until you select Approve from their row menu.
Once the machine exists, give it access and manage it from Machine grants.