Vessel Configuration & `vessel.json` Guide
Vessel is a native, self-hosted deployment agent for Windows, Linux, and macOS that completely replaces Docker. It runs your apps using native runtime engines (Node.js, Nginx, Apache, and production IIS) governed by process isolation and zero-config detection.
How Vessel Reads Your Project
Placing a optional vessel.json file at your project root lets you explicitly command how Vessel builds and serves your app. If omitted, Vessel automatically inspects your folder structure to infer the correct runtime and entry point.
💡 Key Rules for Archives:
- If your uploaded zip file contains a single wrapping folder, Vessel unwraps it automatically before parsing.
- All JSON property names are case-insensitive (
buildCommandandBuildCommandare identical). - Nothing is strictly required; a blank file or empty object
{}falls back to intelligent auto-detection.
`vessel.json` Schema Reference
| Property | Aliases | Engine / Target | Description |
|---|---|---|---|
| name | — | Display only | Human-friendly project identifier. Not used for routing or ports. |
| server / runtime | runtime | Engine Selector | Selects native engine (node, nginx, apache, iis). server wins if both are set. |
| buildCommand | — | All Engines | Shell command run in the workspace root before starting. Non-zero exit code fails deployment. |
| outputDirectory | root | Nginx, Apache, IIS | The production document root folder inside your workspace where compiled assets live. |
| startCommand | start | Node.js Only | Explicit command used to launch your Node process (e.g., node server.js). |
| env | — | Node.js Only | Custom environment key-value pairs injected directly into the Node process runtime. |
Supported Runtimes & Frameworks
Node.js Process Engine
Ideal for Express, Fastify, NestJS, or custom Node servers. Automatically binds to allocated dynamic ports and injects runtime environment variables.
{ "name": "api", "server": "node", "buildCommand": "npm ci --omit=dev", "startCommand": "node server.js" }
Nginx Static Engine
Designed for lightning-fast delivery of static sites, HTML/CSS/JS, and Single Page Applications (React, Vue, Vite) with automatic SPA fallback support.
{ "name": "web", "server": "nginx", "buildCommand": "npm ci && npm run build", "outputDirectory": "dist" }
Production IIS (Windows Only)
Directly provisions full production IIS websites and app pools via Microsoft.W.Administration. Perfect for Blazor WASM and ASP.NET binaries.
{ "name": "blazor-app", "server": "iis", "buildCommand": "dotnet publish -c Release -o ./publish", "outputDirectory": "publish/wwwroot" }
Apache HTTP Server
Serves static files and raw file trees out-of-the-box using standard Apache configurations.
{ "name": "site", "server": "apache", "outputDirectory": "public" }
How Auto-Detection Works (Without a Manifest)
If you don't include a vessel.json file, Vessel inspects your workspace files automatically:
- Runtime Priority: Declared Server/Runtime →
package.json(Node) → PHP files (Apache) → Default fallback (Nginx). - Node Start Scripts: Defaults to
server.js→index.js→npm start. - Document Roots: Automatically searches
.vessel-publish/wwwroot→wwwroot→ root workspace.