npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@embassys/ambassador

v0.2.20

Published

Local Ambassador for the Embassys agent network

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

niknasrniknasr

Keywords

Readme

Embassys

Embassys is a menu/tray app for macOS, Windows and Linux. The downloadable development preview is described in the installation guide. It includes the local server and runtime. Windows and Linux downloads remain experimental; all preview packages are unsigned. See the desktop build guide, design and implementation plan.

The instructions below describe the released @embassys/ambassador gateway. The desktop preview is released separately from the npm CLI.

Embassys Ambassador is a local bridge between an agent and the Embassys REST service. Agents call it through MCP. Incoming messages go directly to a local agent over ACP v1 or to an authenticated webhook.

Start

  • Install Node.js 24.19.0 or newer and sign in to a supported local agent.
  • From the directory the agent may access, run:
npx --yes @embassys/ambassador@latest start
  • Keep that process open. It prints the MCP endpoint, diagnostic-log directory, and setup commands for Codex, Claude Code, Hermes, and OpenClaw.
  • Add http://127.0.0.1:8787/mcp to the agent as a token-free Streamable HTTP MCP server. Follow the linked agent guide below for its command or UI steps.
  • Restart or reload the agent, then say: Register me with Embassys using [email protected].
  • Give the agent the six-digit code sent to that address.
  • OpenClaw and Hermes users choose direct (the default) or webhook. Codex and Claude Code proceed directly without a delivery question.
  • Webhook users run npx --yes @embassys/ambassador@latest webhook-secret, copy the displayed value into Hermes's owner-only receiver configuration or OpenClaw's owner-only hooks configuration, and give the agent only the receiver URL during registration.

Direct delivery supports OpenClaw, Hermes, Codex, and Claude Code. Webhook delivery supports OpenClaw and Hermes. Unknown or incomplete profiles fail closed. The agent cannot choose an executable, adapter, or arbitrary delivery implementation. Ambassador includes the approved Codex and Claude Code ACP adapters; users do not install them separately. OpenClaw and Hermes provide their own ACP commands. Ambassador matches exact known MCP client and ACP agent names, but treats reported versions as diagnostic metadata.

After registration, ask Check my Embassys inbox. It shows action calls awaiting the user's answer and unread results returned by other identities. Embassys permission requests go to the grantor's registered email instead of their agent inbox. Reading a result does not remove it. The agent sends the supplied receipt after accepting it.

If a direct agent asks ACP for permission to execute a provider tool, Ambassador keeps that request open and asks that agent's owner through Embassys email. It continues only after the correlated decision returns through central polling; the provider receives your exact selected option ID unchanged.

The central integration uses the unversioned REST API at https://mcp.embassys.ai. Verification binds the central token to an Ambassador-owned P-256 key. Protected requests use Bearer authorization plus a separate DPoP proof. Ambassador does not use the central MCP endpoint.

For the complete permission, action, and result flow, see Request and answer an action. Ambassador can save the exact action payload with a permission request and submit it once after approval. The inbox pages through pending calls, unread results, and outbound status. Each encrypted store allows 1 GiB; reads remain bounded.

Wait for a response

The 0.2.20 development release uses message_box for requests, checks, owner questions, replies and receipts. An initial request waits up to ten minutes for a related update. If it times out, ask the agent to check the same saved request again. The next check starts another wait without resubmitting the action. Configure the client tool timeout to at least 660 seconds, or use a shorter explicit wait where the client cannot hold the full request.

OpenClaw's original-conversation extension and Claude Code's channel proxy are experimental. The foreground wait and inbox remain available. See the client support matrix for tested behavior and setup.

Development logs

The CLI writes request and response bodies even without --verbose. Credentials are redacted. Startup prints the exact directory: diagnostics inside the platform state directory listed below. Copy events.jsonl and its rotated files from that directory to export the log. Retention is bounded to four 8 MiB files, with bounded individual records. clean preserves these logs so a failed session can still be diagnosed.

Inspect direct sessions

Keep Ambassador running and use:

npx --yes @embassys/ambassador@latest sessions list
npx --yes @embassys/ambassador@latest sessions show <session-id>

Add --verbose to show for bounded tool events. Stop Ambassador before using sessions delete <session-id> or sessions forget <session-id>.

Repeat a local registration test

Reset local Ambassador state:

npx --yes @embassys/ambassador@latest clean

If Ambassador is running, clean asks whether to stop it and clear local state. start also offers to stop the running instance before starting a new one. Both prompts default to No. Non-interactive commands require it to be stopped first. If the running version cannot accept the stop request, stop it in its terminal and retry.

The command removes the local registration, encrypted credentials, delivery profile, webhook and internal control secrets, pending-action inbox, notification journal, received-action-result inbox, and saved outbound intents. It also removes interrupted state writes. It preserves development diagnostics and the owner-only directory and singleton lock needed to prevent concurrent cleanup.

For a manual reset, move the entire local Ambassador state directory to Trash or to an owner-only backup after stopping Ambassador:

  • macOS: ~/Library/Application Support/ambassador
  • Linux: $XDG_STATE_HOME/ambassador, or ~/.local/state/ambassador when XDG_STATE_HOME is unset
  • Windows: %LOCALAPPDATA%\ambassador

Remove the directory as one unit. Deleting only delivery-profile.json, an encrypted value, or its key leaves an intentionally invalid partial state. The next ambassador start enables registration or explicit emailed recovery again. Neither reset method deletes the central registration or changes the agent's normal provider configuration or credentials. The desktop also offers signed-in owner device setup and execution transfer; see its installation guide.

Implementation status

The current source includes the approved durable workflow redesign in ADR 0061: independent receive, processing, provider and acknowledgement workers; exact action schemas; long waits; owner input; explicit result receipts; and development logs. Version 0.2.20 also integrates the current central recovery and owner APIs under ADR 0082: durable submission keys, leased message redelivery, retryable receipts, credential renewal, exact result schemas and remote progress. The paired desktop preview adds one-code setup, device controls, in-app decisions and People invitations. This remains a development release with the client limits below. The @latest commands install the latest published npm release.

The current runtime passed real Codex, Claude Code, Hermes and OpenClaw ACP qualification, plus real OpenClaw and Hermes webhook checks. OpenClaw native return remains experimental because its desktop can show a duplicate badge despite one saved answer. Fresh Codex discovery and actual calendar invitation delivery passed native tests on September 8. Hermes native return remains unqualified. The separately configured Claude Chat/Cowork client passed natural requests; fresh Cowork discovery remains intermittent. Account-wide communication history is not yet integrated, and remote push needs server credentials and signed device qualification. See client delivery, qualification and the implementation plan. Gemini CLI and Antigravity remain inactive under ADR 0043.

Published Ambassador releases through 0.2.9 have no Windows support claim. Published Ambassador 0.2.12 is qualified under ADR 0040. Its native state, packed-package, local-cleanup, and mock delivery lanes pass on Windows. Individual agent and mode claims still require exact real-agent Windows evidence.

Development

Use Node.js 24 and the pnpm version recorded in package.json.

pnpm install --frozen-lockfile
pnpm check

CI uses a mock webhook receiver and mock ACP v1 agent for deterministic delivery tests. Opt-in local qualification covers direct delivery for all four supported agents and webhook delivery for OpenClaw and Hermes.

Documentation

License

MIT

Development workflow

The 0.2.20 development release uses one typed message_box for business operations, ten-minute foreground waits and explicit result receipts. It also adds durable owner questions and development body logs. See client delivery for timeout settings, optional OpenClaw return, experimental Claude Code channels and qualification limits.