npx vibex plugin packs a deterministic .vxp and installs, lists, updates, uninstalls, and publishes packages on the current Host and the official marketplace. Templates and harness tests use vibex-plugin (source at packages/plugin-cli). Bind a Host with vibex plugin run server, then vibex plugin run dev from the plugin directory. See Development workflow.

When desktop or npx vibex serve is running, the command finds the local Host token. If no Host is up, add writes snapshots to ~/.vibex/imports/ and linked directories to ~/.vibex/imports/links.jsonl; the next launch imports them. Default URL is http://127.0.0.1:17891; override with VIBEX_URL / VIBEX_TOKEN. list, update, remove, gc-runtimes, and test --host need a running Host.

npx vibex plugin pack

npx vibex plugin pack
npx vibex plugin pack .
npx vibex plugin pack ./my-plugin
npx vibex plugin pack ./my-plugin --output ./dist/office.vxp

The first argument is the plugin root; it defaults to the current directory. That directory must contain .vibex-plugin/plugin.json, README.md, and the rest of the layout in Package layout.

Order of work: full validation first (summary, schema, content index, integration refs). Failures print each code: message line and exit. On success a .vxp is written and stdout prints two lines:

/absolute/path/dist/<plugin-id>-<version>.vxp
sha256:<packageDigest>

--output sets the result file. The default is dist/<plugin-id>-<version>.vxp inside the plugin directory.

The same source packed twice with npx vibex plugin pack should yield the same sha256. Published npx packages embed plugin-cli under plugin-cli/. A missing directory raises VibeX Plugin CLI is unavailable; reinstall or upgrade the vibex npm package.

npx vibex plugin add

npx vibex plugin add --web <git-or-url[#ref]> [--plugin ID] [--yes]
npx vibex plugin add --profile <file.vxp|archive> [--plugin ID] [--yes]
npx vibex plugin add --dev <dir> [--yes] [--detach]

--web accepts a marketplace page, Git repository, GitHub Release, or archive URL. #tag, #branch, and #commit pin the tree. A GitHub Release that ships a .vxp verifies SHA-256 when a digest or sibling .sha256 is present. --profile installs a local archive. --dev links a development directory: it builds first, then the Host watches the digest; without --detach it prints Worker stderr; --detach returns after linking. HMR is started by vibex plugin run dev. Use only one of the three modes. Without a flag, the command infers directory, file, or URL.

Add --plugin when the archive contains more than one package. Use --yes when stdin is not a TTY.

User path: Install a Plugin from the marketplace. Linked development: Development workflow.

npx vibex plugin list / update / remove

npx vibex plugin list [--json]
npx vibex plugin update <id> [--ref tag] [--yes]
npx vibex plugin remove <id> [--yes] [--delete-data]
npx vibex plugin gc-runtimes

list is the Installed catalog, including source and lock. update fetches another snapshot from the locked origin; linked development plugins edit the source directory instead. remove uninstalls an installed package and keeps config by default; --delete-data deletes the Host-managed snapshot and config, and reclaims unreferenced Runtimes. A linked development directory is not deleted. gc-runtimes deletes Host-managed Runtimes that no plugin references.

Unknown subcommands such as npx vibex plugin init raise Unknown plugin command. Init belongs to vibex-plugin.

npx vibex plugin publish

npx vibex plugin publish [dir|file.vxp]
npx vibex plugin publish --web <github-owner/repo[#tag]>

Submit a packed package or a GitHub repository into the official marketplace review queue. Register a marketplace account first. The GitHub owner must match the marketplace username.

Credentials come from --owner / --password, or VIBEX_MARKET_OWNER / VIBEX_MARKET_PASSWORD. The default catalog is https://vibex.xforever.xin; override with VIBEX_MARKETPLACE_URL. Packed uploads can pass --show-tree to show the package tree; GitHub listings show it by default.

After review, one owner/plugin-name card keeps version history. A listed GitHub repository adds a version when a new tag is pushed and keeps older versions. Hosts that installed from that card or repository show an update affordance.

npx vibex plugin test --host

npx vibex plugin test --host
npx vibex plugin test --host ./my-plugin

Runs link, enable, chrome / structure contribution appear-and-withdraw, Skill reload, and uninstall against a running Host. Looks up a local Host token when VIBEX_TOKEN is unset.

npx vibex plugin --help / npx vibex help plugin

npx vibex plugin --help
npx vibex help plugin

Prints usage for pack / add / publish / list / update / remove / gc-runtimes / test --host / run and skips the Host.

Variables read when starting the Host

These apply when running npx vibex or npx vibex serve.

VIBEX_HOST_FAMILY_TAG: GitHub Release tag to download. Default is v plus the CLI version, for example v0.1.3. Pin a Host build so scripts keep a matching binary.

VIBEX_HOST_FAMILY_BASE: URL prefix for the tarball. Default https://github.com/Xircth/VibeX/releases/download/<tag>. An internal mirror places the full archive on its own HTTP directory and sets this.

VIBEX_HOST_FAMILY_DIR: already extracted family directory (must contain SHA256SUMS, vibex-server, web/). When set, download is skipped.

VIBEX_GITHUB_REPO: GitHub owner/name, default Xircth/VibeX.

VIBEX_STATIC_ROOT: Web UI static file root. npx vibex points it at packaged web/. When you start vibex-server yourself and need the browser UI, point this at a web/ tree.

VIBEX_SERVER_ALLOW_LAN: set to 1 and even npx vibex (loopback start) listens on every NIC. npx vibex serve --local on the command line still binds loopback only.

VIBEX_SERVER_LISTEN: a port number such as 18080, or ip:port. Overrides the default 17891. Command-line --port also overrides the default port.

VIBEX_SERVER_TOKEN: Host token used at start. When non-empty, the saved token in the data directory is ignored.

VIBEX_DEBUG: any non-empty value prints a JavaScript stack on CLI failure.

VIBEX_DATA_DIR: Host data directory. npx vibex serve, npx vibex list, and npx vibex install share this SQLite. Unset, the machine default data directory is used.

Variables read by control commands

VIBEX_URL: Host root URL, default http://127.0.0.1:17891. A trailing / is stripped. Change this after a port change or an HTTPS reverse proxy.

VIBEX_TOKEN: Bearer token, required. Missing it raises VIBEX_TOKEN is required. Copy it from the Token block of npx vibex serve, or from desktop Settings → Remote connection.

Control commands also accept --json, --operation-id, and --timeout. See Control-plane conventions.

Common failures

Unsupported platform: this OS/CPU pair is outside the six published combinations (linux/mac/windows × x64/arm64). Use a supported machine, or open GitHub Releases and confirm that platform’s archive.

Host family download failed: network, firewall, or a bad tag. Check VIBEX_HOST_FAMILY_TAG and open the Release page for vibex-host-family-<platform>.tar.gz.

Checksum mismatch: a corrupt cache or a truncated download. Delete ~/.vibex/host-family/<tag>/ and retry, or point at a verified VIBEX_HOST_FAMILY_DIR.

Host family is missing vibex-server: the extracted tree is incomplete. Download again; copy the full archive, not a subset of files.

VIBEX_TOKEN is required: the token is unset. Run npx vibex serve and copy from the terminal, or copy from the desktop remote-connection page.

Timed out after Ns: the turn or workflow was still non-terminal. Raise --timeout, or inspect with npx vibex conversation show / npx vibex workflow show.

Missing required --x: a required flag is absent. Compare with npx vibex help conversation (or the matching resource).

Plugin validation failed: the plugin pack failed validation. Fix by the printed code, see Package layout, then run npx vibex plugin pack again.

Port in use: switch to npx vibex serve --port 18080, or stop the process holding 17891.

pass --yes to install without a prompt: npx vibex install ran without a terminal and without --yes. Use npx vibex install AGENT_ID --yes.

npm was not found / uv was not found: the local installer needs Node/npm or uv already on this machine. Install the toolchain, then run npx vibex install. Full write-up: Install Agents locally.

npx vibex help
npx vibex --version