The plugin surface on npx vibex is pack only: take a v4 plugin directory and write a deterministic .vxp for someone else to install via desktop Import plugin.
Authoring, linked debug, and hot reload use vibex-plugin (source at packages/plugin-cli). See Development workflow.
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:
--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.
Unknown subcommands such as npx vibex plugin init raise Unknown plugin command. Init and linked debug belong to vibex-plugin, not npx vibex.
npx vibex plugin --help / npx vibex help plugin
bash
npx vibex plugin --help
npx vibex help plugin
Prints Usage: vibex plugin pack [dir] [--output file.vxp] and skips the Host.
Environment and troubleshooting
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_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.
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.
