dvm

The agent-first command-line client for Digital Vending Machines: pay-per-use HTTPS services that need no account or API key.

Install

npm install --ignore-scripts --global @dvmkit/dvm-cli
dvm init

If the earlier @dvmkit/cli package is installed globally, remove it first with npm uninstall --global @dvmkit/cli and then install @dvmkit/dvm-cli, because both packages declare the same dvm binary.

The bundled agent skill is exported as @dvmkit/dvm-cli/skill. That export resolves its entry file; copy the whole containing directory into your agent's skill directory so its calling, wallet, credit, and recovery procedures are available too. Keep the skill and CLI on the same package version. The agent setup guide has installation commands for supported harnesses.

Community

Bug reports and discussions are welcome, but this repository does not accept unsolicited pull requests, including documentation and typo fixes. Send reproducible defects through the bug report form, take features and design questions to Discussions, and report suspected vulnerabilities only through the private route in SECURITY.md.

See CONTRIBUTING.md for the contribution policy, SUPPORT.md for support boundaries, the Code of Conduct, and TRADEMARKS.md for the distinction between Apache-licensed code and dvmkit names and marks.

Portable job access

status, messages, message, and cancel can follow a job from another machine when both its provider endpoint and job token are available. Prefer environment variables so the bearer token does not enter shell history or the process list:

DVM_JOB_ENDPOINT=https://provider.example \
  DVM_JOB_TOKEN=<64-character-hex-token> \
  dvm status <job-id>

The same values are accepted as --endpoint <url> and --job-token <hex>. Each command resolves flags first, then DVM_JOB_ENDPOINT / DVM_JOB_TOKEN, then the local job record; overrides apply only to that invocation and are never saved. pay accepts the same overrides but still requires the submitting machine's local pending request and spending policy, so an endpoint and token alone can never authorize a payment.

Protocol compatibility

Every request to a DVM or the managed dvmkit platform identifies the caller version and protocol generation and advertises a sorted set of additive client capabilities. Servers gate behavior on those capabilities, not on SemVer alone: a numerically newer client does not imply support for a named behavior. An HTTP 426 response names the capabilities or minimum version the caller must add before retrying.

Development

Use the exact Node.js release in .nvmrc. Install with node scripts/pinned-npm.mjs ci --ignore-scripts, then run the same local gate as CI with node scripts/pinned-npm.mjs run verify. The bootstrap downloads the exact npm release declared in package.json, verifies its integrity before every extraction, and keeps it under the ignored repository-local .tooling/ directory.

npm run verify checks repository metadata in the checkout, copies only tracked and unignored source into an isolated directory, installs its locked dependencies, and runs lint, build, typecheck, the full test suite, package/upgrade smoke, packed-artifact safety, and release checks there. The clean source tree owns the only complete build and test pass, so verification cannot reuse the checkout's node_modules or pre-existing dist; after every check passes, its verified dist replaces the checkout's build output for release packaging.

The repository scan leaves an ignored, untracked root .kiln/ runtime directory in place. Git-tracked runtime files, nested directories with the same name, explicit scan roots, and packed-package contents remain subject to the public-safety checks.

Release automation is documented in docs/releasing.md. It prepares a reviewed release pull request and only a separately signed immutable tag can enter the GitHub-hosted npm trusted-publishing path.

License

Apache-2.0. See LICENSE and NOTICE.