Agent skill

vinkius-deploy

How to deploy MCP servers to Vinkius Edge using `vurb deploy`. Use this skill whenever deploying, configuring remote settings, preparing an entrypoint for edge deployment, or troubleshooting deploy-related errors. Activate when the user says "deploy", "publish to edge", "vurb deploy", "push to Vinkius", mentions .vurbrc, VURB_DEPLOY_TOKEN, or any edge deployment topic.

View SKILL.md on GitHub Repository
Stars 244
Forks 21

Install this agent skill to your Project

npx add-skill https://github.com/vinkius-labs/vurb.ts/tree/main/.claude/skills/vinkius-deploy

Metadata

Additional technical details for this skill

tags
deploy, edge, cloud, cli
author
vinkius-labs
version
1.0

SKILL.md

Deploying to Vinkius Edge

vurb deploy bundles your MCP server into a self-contained fat bundle, compresses it, and uploads it to Vinkius Edge where it runs inside a V8 Isolate.

Quick Start

bash
# 1. Configure the remote (once per project)
vurb remote --server-id <uuid-from-dashboard>

# 2. Set the deploy token in .env
echo "VURB_DEPLOY_TOKEN=<connection-token-from-dashboard>" >> .env

# 3. Deploy
vurb deploy

The server UUID and connection token are obtained from the Vinkius Cloud dashboard after creating a server instance.

Configuration Files

.vurbrc (auto-generated by vurb remote)

json
{
  "remote": "https://cloud.vinkius.com",
  "serverId": "abc-123-def"
}
  • Auto-added to .gitignore
  • remote defaults to https://cloud.vinkius.com (omit to use default)
  • serverId is the target server UUID from the dashboard

.env (deploy token)

env
VURB_DEPLOY_TOKEN=your-connection-token-here

The token authenticates the deploy request. It can also be passed via --token <value> flag.

Edge Constraints — CRITICAL

V8 Isolates do NOT have filesystem or process access. The following patterns are incompatible with edge deployment:

❌ autoDiscover() — Requires fs.readdir

typescript
// WRONG — autoDiscover() scans the filesystem at runtime
await autoDiscover(registry, fileURLToPath(new URL('./tools', import.meta.url)));

// CORRECT — explicit imports for edge
import { listUsers } from './tools/users.js';
import { getInvoice } from './tools/billing.js';
registry.register(listUsers);
registry.register(getInvoice);

❌ SandboxEngine — Requires child_process and fs

SandboxEngine cannot run inside V8 isolates. Remove it for edge deploys — tool code runs directly in the isolate.

❌ Inspector / @vurb/inspector — Requires Node.js IPC

The TUI inspector cannot run inside V8 isolates.

⚠️ fast-redact — Uses Function constructor

May have limited support. Verify it works in your isolate before deploying.

Edge-Compatible Server Entrypoint

See references/example-edge-server.ts for a complete example.

Key differences from a standard server.ts:

diff
- import { autoDiscover } from '@vurb/core';
+ // Explicit imports — no filesystem in V8 isolates
+ import { listProducts } from './tools/product.js';
+ import { getInvoice } from './tools/billing.js';

  const registry = f.registry();
- await autoDiscover(registry, ...);
+ registry.register(listProducts);
+ registry.register(getInvoice);

Deploy Pipeline — What Happens Under the Hood

read .vurbrc + .env
       ↓
resolve entrypoint (src/server.ts → src/index.ts → server.ts → index.ts)
       ↓
check for edge-incompatible APIs (autoDiscover, SandboxEngine, Inspector)
       ↓
esbuild bundle (IIFE, platform: browser, es2022, tree-shaking, minify)
       ↓
size check (max 500KB raw)
       ↓
gzip compress + SHA256 hash
       ↓
POST /servers/:serverId/deploy (Bearer token)
       ↓
response: { deployment_id, server_name, url }

Bundle Characteristics

Property Value
Format IIFE (Immediately Invoked Function Expression)
Platform browser (no Node.js APIs)
Target ES2022
Max bundle size 500KB (raw, before gzip)
Dependencies All bundled inside (zod, vurb, MCP SDK)
Node.js modules Aliased to edge stubs (AST-compatible, never called)

CLI Reference

vurb deploy

Bundle, compress, and deploy to Edge.

bash
vurb deploy                        # auto-detect entrypoint
vurb deploy --server ./src/app.ts  # explicit entrypoint
vurb deploy --token <token>        # override VURB_DEPLOY_TOKEN
vurb deploy --allow-insecure       # suppress HTTP plaintext warning

vurb remote

Configure the target server and API endpoint.

bash
vurb remote                              # show current config
vurb remote --server-id <uuid>           # set server ID (uses default cloud)
vurb remote https://custom.api.com       # override API endpoint
vurb remote https://custom.api.com --server-id <uuid>  # both at once

vurb dev

Start HMR dev server with auto-reload (for local development).

bash
vurb dev --server ./src/server.ts
vurb dev --server ./src/server.ts --dir ./src/tools

vurb lock

Generate or validate capability lockfile.

bash
vurb lock                               # generate/update lockfile
vurb lock --check                       # verify (CI gate)

vurb create

Scaffold a new Vurb server project.

bash
vurb create my-server
vurb create my-server -y                 # skip prompts
vurb create my-server --vector prisma --transport sse

vurb inspect

Launch the real-time TUI dashboard (requires @vurb/inspector).

bash
vurb inspect --demo            # built-in simulator
vurb insp --pid 12345          # connect to server PID

Troubleshooting

Error Cause Fix
run: vurb remote --server-id <uuid> No .vurbrc or missing serverId Run vurb remote --server-id <uuid>
set VURB_DEPLOY_TOKEN=<token> in .env Token not found Add token to .env or pass --token
connection token revoked or invalid (401) Invalid or expired token Generate a new token in the dashboard
connection token does not belong to this server (403) Token/server mismatch Check your server-id matches the token
server not found (404) Invalid server UUID Verify the server exists in the dashboard
bundle too large: NNNkb (max 500KB) Fat bundle exceeds limit Remove unused imports, check tree-shaking
autoDiscover() uses fs.readdir Edge-incompatible API Switch to explicit registry.register()
DNS resolution failed Wrong remote URL Check vurb remote config
connection refused API not running Verify the remote URL is reachable

Entrypoint Auto-Detection

When --server is not provided, the CLI probes these paths in order:

  1. src/server.ts
  2. src/index.ts
  3. src/server.js
  4. src/index.js
  5. server.ts
  6. index.ts
  7. server.js
  8. index.js

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

vinkius-labs/vurb.ts

vurb-ts-development

How to build production MCP servers with Vurb.ts using the MVA (Model-View-Agent) pattern. Use this skill whenever writing, modifying, or reviewing Vurb.ts code — including tools, Presenters, Models, middleware, prompts, routers, tests, or server configuration. Activate even when the user just says "create a tool", "add an endpoint", "write a Presenter", or mentions @vurb/core, defineModel, definePresenter, initVurb, FluentToolBuilder, or any Vurb.ts API. This skill covers the entire framework surface.

244 21
Explore
davila7/claude-code-templates

verl-rl-training

Provides guidance for training LLMs with reinforcement learning using verl (Volcano Engine RL). Use when implementing RLHF, GRPO, PPO, or other RL algorithms for LLM post-training at scale with flexible infrastructure backends.

23,776 2,298
Explore
davila7/claude-code-templates

openrlhf-training

High-performance RLHF framework with Ray+vLLM acceleration. Use for PPO, GRPO, RLOO, DPO training of large models (7B-70B+). Built on Ray, vLLM, ZeRO-3. 2× faster than DeepSpeedChat with distributed architecture and GPU resource sharing.

23,776 2,298
Explore
davila7/claude-code-templates

gguf-quantization

GGUF format and llama.cpp quantization for efficient CPU/GPU inference. Use when deploying models on consumer hardware, Apple Silicon, or when needing flexible quantization from 2-8 bit without GPU requirements.

23,776 2,298
Explore
davila7/claude-code-templates

Claude Code Guide

Master guide for using Claude Code effectively. Includes configuration templates, prompting strategies "Thinking" keywords, debugging techniques, and best practices for interacting with the agent.

23,776 2,298
Explore
davila7/claude-code-templates

qdrant-vector-search

High-performance vector similarity search engine for RAG and semantic search. Use when building production RAG systems requiring fast nearest neighbor search, hybrid search with filtering, or scalable vector storage with Rust-powered performance.

23,776 2,298
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results