vinkius-deploy

# 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](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`