Skip to content

mmalmi/nostr-vpn

v0.1.1MIT

Set up and inspect a Nostr VPN private mesh with the nvpn CLI. Use local keys and signed administrator approval instead of a VPN provider account. Connecting requires host networking permissions.

GitHubOpen Website

Nostr VPN agent plugin

The plugin teaches an agent to use the existing command line tool. It contains one portable skill, no background hooks, and no hosted service or API key. Install the tool on the agent's execution host using the workflow guide. Installing the plugin alone does not install binaries or start a service.

Codex and ChatGPT desktop

codex plugin marketplace add mmalmi/nostr-vpn
codex plugin add nostr-vpn@nostr-vpn-plugins

Restart the agent session and select Nostr VPN, or ask it to use the nostr-vpn skill. For a local checkout, replace the repository argument with . while in this repository. The repository also exposes the plugin through .agents/plugins/marketplace.json in supported desktop clients.

OpenAI marks plugins that call local programs as Desktop only. A dot needs a supported local task on a connected computer for this plugin; installing it does not give a cloud-only dot access to your computer or networking privileges. Public-directory submission is separate from installing this repository.

Claude Code

claude plugin marketplace add mmalmi/nostr-vpn
claude plugin install nostr-vpn@nostr-vpn-plugins

Start a new session, then invoke /nostr-vpn:nostr-vpn with your request. For local evaluation, run claude --plugin-dir ./plugins/nostr-vpn from this checkout.

Grok Build and Grok Bot

Grok Build supports Claude-compatible plugins. From this checkout:

grok plugin install ./plugins/nostr-vpn
grok inspect --json

Start a new session and use its plugin/skills menu to select the workflow. Grok Bot is a separate surface: give it the workflow guide and ask it to perform the task with its terminal, then save the verified procedure as a skill. This repository is not automatically listed in Grok Bot's Connect apps directory.

Hermes Agent

Hermes supports the root plugin.json Agent Plugins v1 package directly:

hermes plugins install mmalmi/nostr-vpn/plugins/nostr-vpn --no-enable
hermes plugins enable nostr-vpn

Start a new session and ask Hermes to load nostr-vpn:nostr-vpn using skills_list and skill_view. No Hermes-specific Python extension or MCP server is needed. The terminal environment must have the CLI and persistent storage for its identity. Plugin updates must not replace that identity.

Other Agent Skills clients

Install plugins/nostr-vpn/skills/nostr-vpn from the repository using your client's skill installer. Keep the whole folder together. The skill is the canonical workflow; platform manifests all refer to it.

What it accesses

When asked to connect, the agent invokes nvpn with a chosen persistent local configuration and connects to configured relays and peers. Starting a VPN changes host interfaces and routes and requires operating-system privileges. Signed enrollment requires an administrator; the plugin grants no network access by itself. The CLI manages keys; the skill does not read or expose key sidecars. The daemon remains running until stopped. No telemetry is added.

Versions and updates

The plugin and nvpn have separate versions. Plugin installation and updates do not upgrade the CLI. A fresh latest/unpinned setup uses that channel's current release; existing binaries change only through a separate upgrade. Preserve the identity and data directories when upgrading.

A compatible CLI release needs no plugin update while the documented commands, JSON fields, permissions, and setup still work. When instructions or package metadata change, bump both manifests' version together, validate, and publish a new ZIP or catalog revision. Catalog review and each client's update settings govern delivery; changing the repository does not update every installed copy.

Package and validate

From a committed checkout, create a small distribution ZIP without app sources, build artifacts, identities, or configuration:

git archive --format=zip --output=nostr-vpn-plugin.zip HEAD:plugins/nostr-vpn
claude plugin validate plugins/nostr-vpn

Keep generated ZIPs outside commits. Validate an extracted ZIP too, and run the workflow with a fresh test identity before submitting to a directory. Public catalogs have separate review requirements; a valid package is not a listing.

Packaging references: OpenAI, desktop execution, Claude, Grok, and Hermes.