Vendo Cloud: hosted sharing, publishing, and API keys

Vendo Cloud is the hosted backend for cloud-gated surfaces: sharing frozen app copies, publishing app versions, and org-scoped keys and members. Local development never needs it. Reach for it when you want cross-host sharing, published copies, or a machine key for CI.

Prerequisites

A Vendo Cloud account at https://console.vendo.run.
The vendo bin on your PATH (npx vendo also works).

vendo cloud login <email> sends a 6-10 digit code to your inbox, prompts for it on stdin, and stores the returned session at ~/.vendo/cloud-session.json (file mode 0600). The exact code length depends on your Vendo Cloud project’s OTP configuration. The user commands reuse that session; the machine commands (validate, share, publish, pin-ship) authenticate with --key or VENDO_API_KEY instead.

vendo cloud login you@example.com
# Enter the code sent to you@example.com: 12345678
# { "loggedIn": true, "mode": "email", "email": "you@example.com" }

If you already hold a Vendo Cloud access token, skip the OTP and store it directly:

vendo cloud login --token <jwt>

Sign out with vendo cloud logout. Check that the session works with vendo cloud whoami, which prints the organizations it can reach.

Provide an API key to the runtime

Cloud-gated runtime calls read VENDO_API_KEY from the host process. When it is unset or empty, vendo.apps.share() and vendo.apps.publish() throw cloud-required and the mapped HTTP status is 402. Set it wherever your handler runs:

export VENDO_API_KEY=vnd_live_...

Create and rotate keys from the CLI:

vendo cloud keys create --org <orgId> --name "ci-publisher"
vendo cloud keys list --org <orgId>
vendo cloud keys revoke --org <orgId> --id <keyId>

--org is optional only when your account has exactly one organization. API keys use the format vnd_ followed by 40 hex characters. The machine commands (validate, share, publish, pin-ship) reject malformed keys before making any network call.

Validate an API key

vendo cloud validate checks a key against the hosted API and prints the organization, plan, capability grid, and quota meters it grants. Use it to confirm that a key is live before wiring it into CI, or to see how much headroom the key has left on metered resources.

vendo cloud validate --key vnd_...

By default the command renders a human-readable report:

Vendo Cloud key: valid
Org: acme (org_...)   Plan: pro

Capabilities
  cloud.share         ✓
  cloud.publish       ✓
  cloud.pin_ship      ✓
  ...

Quotas
  shares_per_month    [████████░░░░░░░░░░░░]   412 / 1,000
  publishes_per_month [██░░░░░░░░░░░░░░░░░░]    47 / 500
  storage_gb          [█████░░░░░░░░░░░░░░░]   2.4 / 10

Pass --json to get a machine-readable envelope instead — useful in CI or when piping into other tools:

vendo cloud validate --key vnd_... --json

The JSON envelope is stable across every path (live, stale cache, or degraded fallback) so scripts can key off the same fields regardless of connectivity.

Offline behavior and the entitlements cache

validate is live-first: it always tries to revalidate against the hosted API and only falls back to the cache when the network fails. The cache lives at ~/.vendo/entitlements.json (directory 0700, file 0600). Entries are keyed by a hash of the API URL and key, so no key material is written to disk. Behavior when the hosted API is unreachable:

503 or network error, within the stale window — serves the last known entitlements and prints a stale banner. Exit code stays 0.
503 or network error, past the stale window — degrades to a fail-closed free contract (all capabilities false, meters exhausted) and prints Vendo Cloud key: unverified (offline). Exit code stays 0 so scripts can branch on the JSON envelope.
401 Unauthorized — evicts the cached entry immediately and exits with Invalid or revoked API key (401).

Free-tier keys can report storage_gb as exhausted on day one — that renders as no remaining headroom, not an error, and the exit code stays 0.

Point at a different Vendo Cloud URL

By default the runtime and CLI both target https://console.vendo.run. Set VENDO_CLOUD_URL to override, for example against a staging environment:

export VENDO_CLOUD_URL=https://console.staging.vendo.run

Individual CLI commands also accept --api-url <url> for a one-off override. With VENDO_API_KEY set, the composition’s apps runtime calls the hosted API:

import { createVendo } from "@vendoai/vendo/server";

const vendo = createVendo({ /* model, principal, store, ... */ });

const snapshot = await vendo.apps.share(appId, ctx);
const record = await vendo.apps.publish(appId, ctx);

share returns a ShareSnapshot (a frozen copy: id, doc, createdAt). publish returns a PublishRecord with the assigned version (id, appId, version, createdAt). Both responses are validated against the frozen wire schemas (shareSnapshotSchema, publishRecordSchema) before they resolve. To share or publish from CI without loading the composition, upload the app document directly. The file needs a string id, or pass --app <id>:

vendo cloud share ./app.json
vendo cloud publish ./app.json

Deploy local automations to hosted

vendo cloud deploy pushes the automations you built locally (in .vendo/data) to a Vendo Cloud hosted instance so they run on Vendo’s schedulers and webhook endpoints instead of your machine. Reach for it once an automation is stable locally and you want it to keep firing without your dev process running. The command opens the project’s default PGlite store, selects a subject, and sends every enabled automation for that subject plus the active automation grants that apply to those apps. It uses machine-key auth, so set VENDO_API_KEY or pass --key <vnd_...>.

export VENDO_API_KEY=vnd_live_...
vendo cloud deploy

The default output prints the org, instance status, an applied-count table (apps, grants, secrets), and any hosted webhook URLs the deploy provisioned. Pass --json to receive the raw hosted deploy response instead.

Options

--app <id> — deploy only this automation. Repeat the flag to send several. An explicitly selected disabled automation is still sent (with enabled: false); without --app, only enabled automations are included.
--subject <id> — required when .vendo/data contains more than one subject. Vendo never combines apps or grants from different subjects into one deploy.
--secret NAME=VALUE — supply a secret value referenced by one of the selected apps. Repeat for each secret. Only names actually referenced by the deployed apps are forwarded; a referenced name without a matching flag prints a warning but does not fail the deploy. Sending secrets requires an HTTPS Vendo Cloud URL.
--key <vnd_...> — machine-key override for this call.
--api-url <url> — target a non-default Vendo Cloud (for example a staging environment).
--json — print the raw response.

Example

Deploy two specific automations with the API keys they need:

vendo cloud deploy \
  --app app_daily_digest \
  --app app_stripe_webhook \
  --secret STRIPE_KEY=sk_live_... \
  --secret RESEND_KEY=re_...

Limitations

Automations whose steps use fn: tools (calls back into the host application’s process) print a warning during deploy. Hosted sandboxes cannot reach your machine in v1, so those steps will fail or park when the automation fires in the cloud. Either replace them with tools the hosted runtime can execute, or keep those automations running locally.

Error handling

Cloud calls surface the shared error taxonomy (see Troubleshooting):

cloud-required (HTTP 402): no VENDO_API_KEY, or the key’s org lacks the entitlement for the requested surface.
validation, not-found, conflict, blocked: propagated from the hosted API with the same codes the wire uses.

Handle cloud-required by setting VENDO_API_KEY, or for interactive tools by running vendo cloud login and creating a key with vendo cloud keys create.

Hosted sandboxes

vendoSandbox() is the hosted sandbox adapter for app rungs 2 through 4. Reach for it when you want server-backed apps without provisioning E2B or Modal yourself. The adapter authenticates with VENDO_API_KEY and talks to the broker at VENDO_CLOUD_URL (default https://console.vendo.run), so the same key that unlocks sharing and publishing also unlocks hosted sandboxes.

import { createVendo } from "@vendoai/vendo/server";
import { vendoSandbox } from "@vendoai/apps/vendo";

const vendo = createVendo({
  // model, principal, store, ...
  sandbox: vendoSandbox(),
});

vendoSandbox(options) accepts:

apiKey — Vendo Cloud API key. Defaults to VENDO_API_KEY.
baseUrl — broker base URL override for tests or self-hosted brokers. Defaults to VENDO_CLOUD_URL.
timeoutMs — default control-plane and command timeout in milliseconds. Defaults to five minutes.

Snapshot references returned by hosted machines are prefixed vendo: and resume only against a broker that recognizes them. Errors map to the shared taxonomy: missing or invalid keys surface as cloud-required, exhausted plans surface as cloud-required with an upgrade message, and broker outages surface as sandbox-unavailable. See Server API for the SandboxAdapter seam and Generated UI and apps for the rung ladder. For the full CLI surface, see CLI.

​Prerequisites

​Sign in from the CLI

​Provide an API key to the runtime

​Validate an API key

​Offline behavior and the entitlements cache

​Point at a different Vendo Cloud URL

​Share and publish

​Deploy local automations to hosted

​Options

​Example

​Limitations

​Error handling

​Hosted sandboxes