Client Setup

Config File

The client config lives at ~/.openme/config.yaml (created with 0600 permissions — it contains your private key).

Paste the block printed by openme add on the server, or write it manually:

profiles:
  default:                                  # used by `openme connect`
    server_host: "myserver.example.com"
    server_udp_port: 7777
    server_pubkey: "base64..."              # server's Curve25519 public key
    private_key:   "base64..."             # your Ed25519 private key
    public_key:    "base64..."             # your Ed25519 public key
    post_knock:    "ssh user@myserver.example.com"  # optional

  home:                                     # used by `openme connect home`
    server_host: "home.example.com"
    server_udp_port: 7777
    server_pubkey: "base64..."
    private_key:   "base64..."
    public_key:    "base64..."

The profile named default is used when no profile name is given. You can have as many named profiles as you like — one per server.

Connect

# Health check — confirm server is reachable before knocking
openme status

# Knock using the default profile
openme connect

# Knock using a named profile
openme connect home

# Open the firewall to a specific IP instead of your source IP
openme connect --ip 10.0.0.5

# Open the firewall to a specific IPv6 address
openme connect --ip 2001:db8::42

If post_knock is set in the profile, it is run automatically after a successful knock — useful to make openme connect feel like a transparent wrapper around ssh.

Status Check

# Check health port only — requires a prior knock within knock_timeout
openme status
openme status home      # named profile

# Knock first, then check — validates the full authentication round trip
openme status --knock
openme status home --knock

The health port is never permanently open. It is a firewall rule opened automatically alongside your other ports after a successful knock, for the knock_timeout duration (default 30 seconds). This means:

openme status with no flag confirms the port is currently open (i.e. you knocked recently and the window hasn’t expired)
openme status --knock is the end-to-end test: knock → wait → check, confirming the full crypto + firewall round trip works

Scripting

# Knock then connect — inline without post_knock in config
openme connect home && ssh user@home.example.com

# Use a specific config file
openme --client-config /etc/myapp/openme.yaml connect