Self-improving AI Employees for everyone
Vercel Service
Self-contained plugin at server/nodes/vercel/
wrapping the official Vercel CLI (npm package vercel, pinned in
_install.py). One dual-purpose node — vercelAction (workflow node +
AI tool vercel) — with four operations: deploy, inspect, list,
and a custom raw-command passthrough (the Stripe passthrough idiom, so
env vars / logs / rollback / promote / domains / aliases / projects all
work without additional code). No trigger node in v1: the Vercel CLI
has no listen-style daemon; a vercelReceive (account webhooks or
vercel ls polling) is a documented follow-up.
It is the second in-repo reference for the CLI-managed-auth
pattern (see node_creation.md → CLI-managed auth
and stripe_service.md) — specifically the
device-flow variant, where the CLI's login is a single blocking
process rather than Stripe's two-step --non-interactive /
--complete <url> pair.
File map
| File | Role |
|---|---|
__init__.py |
Wiring only: register_ws_handlers(WS_HANDLERS) + register_output_schema("vercelAction", VercelActionOutput); node class auto-registers on import |
vercel_action.py |
VercelActionNode(ActionNode), usable_as_tool=True, tool_name="vercel", gmail-style multi-@Operation dispatch on operation: Literal["deploy","inspect","list","custom"] |
_handlers.py |
vercel_login / vercel_logout / vercel_status WS handlers; device-flow driver; marker-token write + broadcast_credential_event |
_service.py |
Config-dir pinning, is_logged_in() sniff, global_argv() / vercel_env() builders, ANSI-strip + login-URL/code parsers |
_install.py |
ensure_vercel_cli() — pinned bun add vercel@<X> (core.js_runtime.add_package) into the shared packages tree (<DATA_DIR>/packages/), run on bun (no Node or npm involved; vercel 54.21.1 verified on bun with no Node on PATH); system PATH preferred; one-shot telemetry disable post-install |
_credentials.py |
VercelCredential(Credential) thin marker (auth="custom"); resolve() returns the optional vercel_token api-key row |
meta.json |
Node color. No co-located icon.svg — the icon is the official brand glyph via visuals.json: {"vercelAction": {"icon": "lobehub:Vercel", "skill": "vercel-skill"}}; a folder SVG would silently override it (first hit in get_plugin_icon_path), and its absence is locked by test_vercel_plugin.py::test_plugin_folder_assets. A lowercase "vercel" alias entry (icon + color) also exists because the skill's allowed-tools token is the tool name vercel, not the node type's snake_case — without the alias, skill_loader._parse_skill_metadata resolves an empty icon/color and the Master Skill row renders blank (the naming-contract escape hatch documented in plugin_system.md). |
Paired skill: server/skills/vercel/vercel-skill/SKILL.md
(auto-attached when the tool connects to an agent, via the
visuals.json skill map).
Auth — two independent paths
Either path is sufficient; the token wins when both exist.
- Access token (headless-safe): the catalogue entry declares one
fieldsrow,vercel_tokenwith"required": false. Stored as a plain api-key row; injected as theVERCEL_TOKENenv var on every invocation — never argv, so it stays out of process lists. - CLI login (browser device flow):
vercel_loginspawnsvercel logindirectly withasyncio.create_subprocess_exec(stdin=PIPEleft un-written — the claude-login EOF guard).run_cli_commandis unusable here: it buffers viacommunicate()until exit, and the device flow blocks for up to 10 minutes while the URL is needed immediately. The banner reader is chunk-based (stream.read(4096), notreadline()— spinner\rrepaints overrun the StreamReader line limit) and its pumps deliberately outlive the handler, draining both pipes for the process lifetime so the CLI never blocks on a full pipe buffer. The first code-embedding URL is returned as{success, url, verification_code}— the frontend opensurlAND rendersverification_codeprominently in the modal's info box (useCredentialPanel.oauthLogin→OAuthConnect, the generic device-flow display shipped with the GitHub plugin; prefer a code-embedding URL anyway so the user rarely needs to type it). A background task (strong-ref'd — asyncio holds only weak refs) awaits process exit; the success gate isauth.jsonmtime advanced past the pre-login snapshot ANDis_logged_in()(exit codes are not trusted; Stripe precedent). On success the handler writes thecli-managedmarker OAuth tokens and broadcastscredential.oauth.connected.
Config-dir pinning
Every invocation appends --global-config <DATA_DIR>/vercel/ (plus
--no-color; env gets NO_COLOR=1). The CLI's default
com.vercel.cli location varies wildly by OS — pinning makes the
auth.json sniff deterministic and isolates OpenCompany-managed auth
from the user's own system vercel login (the
CLAUDE_CONFIG_DIR = data_path("claude") idiom). The path is composed
inline in _service.vercel_config_dir() per the core.paths rule.
Credentials modal
Catalogue entry (server/config/credential_providers.json):
kind:"oauth", category deployment (new, order 10), no
status_hook — the marker tokens satisfy the plain kind=="oauth"
stored-derivation in handle_get_credential_catalogue, and the
connected badge falls back to config.stored in OAuthPanel.
icon_ref: "lobehub:Vercel" (official brand icon; registered in
client/src/assets/icons/index.ts LOBEHUB_BRANDS).
Frontend gating change that shipped with this plugin:
OAuthConnect.tsx now gates the Login button on required fields
only (config.fields?.some(f => f.required)), so Vercel's optional
token field renders without blocking Login. Existing providers are
unchanged (Google/Twitter/Telegram all declare required: true on
their gating fields).
Operations
| Op | argv shape | Notes |
|---|---|---|
deploy |
deploy --yes [--prod] [--prebuilt] [--archive=tgz] [--project X] [--scope X] <extra_args> |
cwd = path param (relative → resolved against ctx.workspace_dir) or the workspace itself; stdout carries only the deployment URL (progress → stderr), returned as url; 600 s timeout |
inspect |
inspect <deployment> [--logs] [--wait [--timeout T]] |
300 s subprocess timeout when --wait, else 60 s |
list |
list [project] [--prod] [--status S] --yes |
Human table in stdout (no --json upstream) |
custom |
<command verbatim, shlex-split> |
cwd = workspace when present; JSON-capable commands (logs --json, project ls --format=json) come back parsed in result |
Shared per-op plumbing: _preflight() (no token AND not logged in →
PermissionError annotated provider="vercel" / reason="missing" / auth="oauth2", which produces the credential envelope + the
credential.oauth.runtime_failed broadcast) → ensure_vercel_cli() →
run_cli_command(..., env=vercel_env(token), cwd=...) → non-zero exit
→ NodeUserError carrying the stderr tail (user/LLM-correctable, one
WARN line, no traceback).
Output shaping: _shape never ships raw stdout alongside a
server-side-parsed JSON result (pre-stringified duplication violates
the output contract) and omits empty keys entirely (exclude_unset
preserves the producer's key set). The node declares
ui_hints = {"outputMode": "terminal"} so the Output panel renders
its textual output preformatted instead of through ReactMarkdown.
First-deploy project guard: an unlinked deploy (no project
param, no .vercel/project.json in the cwd, no VERCEL_PROJECT_ID,
no --project in extra_args) raises a NodeUserError up front with
the remediation, instead of letting Vercel derive a project name from
the cwd — workflow workspace dirs (AI_Assistant_1) violate Vercel's
lowercase naming rules and would 400 only after the upload. No
name is invented and no naming rules are re-implemented — Vercel stays
the authority; the LLM/user supplies a valid name and retries.
Framework touch (one)
run_cli_command (server/services/events/cli.py) gained a
cwd: Optional[str] = None kwarg (keyword-only, backward compatible)
— deploys are directory-scoped.
Tests
server/tests/test_vercel_plugin.py:
argv builders per operation (--global-config + --yes presence,
token → env not argv), device-flow banner parsing against recorded
fixtures (ANSI included), marker-token flip + catalogue broadcast,
install-path resolution, PermissionError annotation attrs, the
first-deploy project guard, catalogue-entry shape (required: false
on the token field), and the no-folder-icon contract. The generic
test_plugin_contract.py / test_plugin_self_containment.py
invariants pick the plugin up automatically.
Runtime caveat
The device-flow banner format is parsed from the pinned CLI version's
output; Vercel changed login flows in early 2026 (email / --github /
--oob removed). If the URL regex ever misses, vercel_login returns
the raw CLI output lines in error so the failure is diagnosable from
the modal. Re-verify against vercel login --help when bumping the
pinned version.