Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Creating your account

Create the first administrator account, then sign piquelctl in with it.

You sign in with a passkey instead of a password. Your phone, laptop, password manager or security key keeps it, so there’s nothing to choose, remember or leak.

Before you start

  • piqueld is installed, and you’ve chosen the address of its dashboard.
  • Your browser can create passkeys: a device with a PIN or biometrics, a password manager with passkey support, or a security key.

Create the first account

  1. On the piqueld host, print the setup link:

    piquelctl setup-link

    It prints a link such as https://piqueld.<tailnet>.ts.net/dashboard/auth#invite=…. Add --open to also open it in the host’s browser. Only root and members of the piqueld group can get the link, because it’s only served on the host’s socket.

  2. Open the link in your browser. Choose a Username, and optionally a display name. Under Passkey name, keep My passkey or name the device that keeps it, such as Laptop.

    The “Create your account” page, with the username alice, the display name Alice, and the passkey name Laptop

  3. Select Create account with a passkey, and save the passkey when your browser asks.

The dashboard opens, signed in. Your account has admin on every application. The link only works once: when the first account exists, setup is closed for good. Invite other people from the dashboard’s Accounts page or with piquelctl account invite; see invite someone.

To sign in later, open the dashboard and select Sign in with a passkey. You don’t need to type your username.

Sign piquelctl in

On the host, piquelctl connects to the daemon’s socket. Root doesn’t need to sign in there: sudo piquelctl acts as the host operator. Members of the piqueld group sign in as themselves.

On another machine, first tell piquelctl the dashboard’s address, in the shell you’ll run the following commands in:

export PIQUELD_URL=https://piqueld.<tailnet>.ts.net

With the localhost option, keep the SSH tunnel open and use http://localhost:7845. To keep the address for good, save it as a connection profile.

  1. Start the login:

    piquelctl login

    It prints a link, a code, and where the daemon sees the request coming from: your machine’s network address, or the daemon’s local Unix socket on the host.

  2. Open the link and sign in. The link carries the code, so the page shows the login request straight away.

  3. Check that the code and Requested from match what your terminal printed, then select Approve CLI login.

Check who you’re signed in as:

piquelctl whoami

Next, deploy your first application.

Troubleshooting

  • piquelctl setup-link says setup is already completed. An account exists already. If nobody can sign in with it any more, see recovering administrator access.
  • The browser won’t create or use the passkey. Passkeys need HTTPS, or localhost, and only work at the address they were created on: the one you chose when installing piqueld. Open the dashboard at exactly that address.
  • You can’t run piquelctl on the host. The daemon also writes the setup link to the file setup-link in its data directory, /var/lib/piqueld by default. Only root and the daemon’s user can read it.