2. Add a Client

Keywords

openme add client, provision SPA client, openme keygen, openme QR code, Ed25519 key provisioning, client onboarding

Run openme add on the server to register a new client. It generates an Ed25519 keypair, adds the public key to the server config, and prints a ready-to-use client config block.

Basic Usage

sudo openme add alice

Output:

Client "alice" added to server config.

──── Client config for alice — profile "default" (copy to ~/.openme/config.yaml) ────
profiles:
    default:
        server_host: myserver.example.com
        server_udp_port: 54154
        server_pubkey: "base64..."
        private_key:   "base64..."
        public_key:    "base64..."
────────────────────────────────────────────────────────────────
Key fingerprint: a3f1c2d4e5b60718

The YAML block is ready to paste into ~/.openme/config.yaml on the client machine. The key under profiles: is the profile name — by default "default".

Profile Names

The profile name is the key under profiles: in the generated client config. It is also the argument you pass to openme knock <profile>.

By default the profile is named "default". You can change this two ways:

Per-command — pass --profile NAME to openme add:

sudo openme add alice --profile home
# generates:  profiles:\n    home:\n        ...

Server-wide — set default_profile in server: block of /etc/openme/config.yaml:

server:
  host: myserver.example.com
  default_profile: home   # every 'openme add' will use 'home' unless --profile overrides it

The --profile flag always takes precedence over server.default_profile.

Port Access Modes

By default, a client can open only the server’s default ports (SSH on 22).

# Default ports only — just SSH
sudo openme add alice

# Default + extra ports — SSH plus custom ports
sudo openme add bob --ports default,2222/tcp,8080/tcp

# Only custom ports — no SSH
sudo openme add ci-runner --ports 443/tcp

Key Expiry

# Expires at end of 2026
sudo openme add contractor --expires 2026-12-31T23:59:59Z

If --expires is omitted, the key never expires.

QR Code Provisioning

For mobile clients, generate a QR code containing the full client config:

# Print QR in terminal (⚠ includes private key — treat as secret)
sudo openme add alice --qr

# Write QR to a PNG file
sudo openme add alice --qr-out /tmp/alice.png

# QR without private key (mobile app generates its own keypair)
sudo openme add alice-mobile --qr --no-privkey

Warning

A QR code with the private key included must be treated as a secret. Show it briefly to the user and do not store the image. Use --no-privkey if you prefer the mobile device to generate its own keypair — the user then sends you their public key to register separately.

Managing Clients

# List all registered clients
openme list

# Revoke a client immediately (takes effect on next knock attempt)
sudo openme revoke alice

Next: Client Setup →