Bootstrap

How Bootstrap Works

The bootstrap command registers a new machine with your vault. The script runs on the target machine and:

1. Generates an Ed25519 keypair using openssl genpkey -algorithm Ed25519
2. Extracts the raw 32-byte public key
3. Sends the public key, the bootstrap token, and the machine's hostname to SikkerKey
4. Receives back a machine ID and vault ID
5. Stores the private key and identity file at /etc/sikkerkey/vaults/{vaultId}/
6. Sets directory permissions to chmod 700 and file permissions to chmod 600

The private key never leaves the machine. Only the public key is transmitted during registration.

Requirements

The bootstrap script checks for three dependencies before running:

• Root access (sudo). Required to write to /etc/sikkerkey/.
• openssl. Used to generate the Ed25519 keypair and extract the public key.
• curl. Used to register with the SikkerKey API.

If any are missing, the script exits with an error.

Running the Bootstrap

From the dashboard, go to Machines and click + Validate. Copy the command:

curl -sSL https://api.sikkerkey.com/v1/bootstrap/YOUR_TOKEN | sudo sh

The token is single-use and expires in 10 minutes.

Inspect Before Running

If you prefer to review the script before executing it:

curl -o bootstrap.sh https://api.sikkerkey.com/v1/bootstrap/YOUR_TOKEN
cat bootstrap.sh
sudo sh bootstrap.sh

Setting File Ownership

By default, files are owned by the user behind sudo (detected via $SUDO_USER). To specify a different user:

sudo sh bootstrap.sh --user myapp

This runs chown -R myapp /etc/sikkerkey/ so your application process can read the identity and private key without root.

Identity Files

After bootstrap, the following structure is created:

/etc/sikkerkey/                          chmod 700
  vaults/                                chmod 700
    vault_a1b2c3d4e5f6g7h8/             chmod 700
      identity.json                      chmod 600
      private.pem                        chmod 600

identity.json

{
  "machineId": "a7f3c2e1-9b4d-4f8a-b6d5-3e1c7a9f2b4d",
  "machineName": "api-server-1",
  "vaultId": "vault_a1b2c3d4e5f6g7h8",
  "apiUrl": "https://api.sikkerkey.com",
  "privateKeyPath": "/etc/sikkerkey/vaults/vault_a1b2c3d4e5f6g7h8/private.pem"
}

The machineName is set to the machine's hostname (hostname -s) at registration time. You can rename the machine later from the dashboard.

Re-registration

If a machine was previously registered with the same vault, the bootstrap script automatically replaces the old identity. It prints the old and new machine IDs so you can verify the change. The old machine ID becomes invalid immediately.

You will need to approve the new registration from the dashboard.

After Bootstrap

The machine is registered but cannot do anything yet. Three steps remain:

1. Approve the machine from the Machines page. It appears with a "pending" status.
2. Add it to a project from the project's machines page.
3. Grant it access to specific secrets using "Configure access" on the project machines page.

The machine cannot read any secrets until all three steps are complete.

Machine Name

The bootstrap script uses hostname -s as the machine name. If the hostname is not available, it falls back to "unknown". You can rename the machine at any time from the dashboard. Name changes are versioned and audit-logged.

Troubleshooting