Volcengine Vefaas

volcengine-vefaas: Volcengine FaaS CLI

vefaas is the command-line tool for Volcengine Function Service (veFaaS). It enables serverless application deployment, function management, and configuration through a streamlined workflow.

Installation

npm i -g https://vefaas-cli.tos-cn-beijing.volces.com/volcengine-vefaas-latest.tgz

Verify installation:

vefaas --version

Core Workflow

The typical deployment pattern:

1. Check Node.js: node --version (requires >= 18, recommended 20+)

• If version is too low, switch using nvm (nvm use 20) or fnm (fnm use 20), or manually install a newer version

2. Check CLI: vefaas --version to verify installation 3. Check Auth: vefaas login --check to verify login status

• If not logged in, run vefaas login --sso (opens browser, auto-completes when user authorizes - no manual input needed)

4. Deploy: vefaas deploy --newApp <name> --gatewayName $(vefaas run listgateways --first) --yes 5. Access: vefaas domains to view URLs

Quick Commands

Global Options

Cookbooks

Step-by-step guides for common scenarios:

• [Template Quickstart](references/cookbooks/template-quickstart.md) - Create and deploy from official templates
• [Deploy Existing Code](references/cookbooks/deploy-existing-code.md) - Deploy your existing project
• [Manage Functions](references/cookbooks/manage-functions.md) - Manage functions (pull code, upload and deploy)

References

Detailed documentation on specific topics:

• [Authentication](references/authentication.md) - Login methods and credentials
• [Configuration](references/configuration.md) - Config files and settings
• [Environment Variables](references/environment-variables.md) - Managing env vars
• [Framework Detection](references/framework-detection.md) - Supported frameworks and auto-detection
• [MCP Deployment](references/mcp-deployment.md) - MCP protocol, run.sh, proxy, and path-selection checks
• [Troubleshooting](references/troubleshooting.md) - Debug mode, common issues, and solutions

Important Notes

• Always use --yes for non-interactive mode in CI/CD and AI coding scenarios
• Use $(vefaas run listgateways --first) to get an available gateway
• Config is stored in .vefaas/config.json after linking
• Use --debug or -d to troubleshoot issues

Authentication Reference

Authentication Methods

1. Interactive Login

vefaas login

Prompts for:

• Access Key ID (AK)
• Secret Access Key (SK)

Credentials are saved to ~/.vefaas/auth.json.

2. Non-Interactive Login

vefaas login --accessKey YOUR_AK --secretKey YOUR_SK

# With STS session token (optional)
vefaas login --accessKey YOUR_AK --secretKey YOUR_SK --sessionToken YOUR_TOKEN

3. Environment Variables (Recommended for CI/CD)

export VOLC_ACCESS_KEY_ID="YOUR_AK"
export VOLC_SECRET_ACCESS_KEY="YOUR_SK"

# Optional: STS token
export VOLC_SESSION_TOKEN="YOUR_STS_TOKEN"

When env vars are set, CLI uses them automatically without requiring vefaas login.

4. OAuth/OIDC Token

vefaas login --token YOUR_OAUTH_TOKEN

5. SSO Login

vefaas login --sso

Opens browser for SSO authentication. Useful for organizations with centralized identity management.

Credential Management

Check Current Status

vefaas login --check

Logout

vefaas logout

Clears stored credentials from ~/.vefaas/auth.json.

Obtaining Credentials

1. Log in to Volcengine Console 2. Navigate to IAM > Access Key Management 3. Create new AK/SK pair 4. Ensure account has veFaaSFullAccess policy

CI/CD Configuration

GitHub Actions

env:
  VOLC_ACCESS_KEY_ID: ${{ secrets.VOLC_ACCESS_KEY_ID }}
  VOLC_SECRET_ACCESS_KEY: ${{ secrets.VOLC_SECRET_ACCESS_KEY }}

Troubleshooting

Configuration Reference

Config File Location

After linking, config is stored in .vefaas/config.json in your project root.

Config File Structure

{
  "version": "1.0",
  "function": {
    "id": "func-xxxxx",
    "runtime": "native-node20/v1",
    "region": "cn-beijing",
    "application_id": "app-xxxxx"
  },
  "triggers": {
    "type": "apig",
    "system_url": "https://xxx.apigateway-cn-beijing.volceapi.com/",
    "id": "gw-xxxxx"
  }
}

Field Reference

Commands

View Config

vefaas config list

Pull Config from Cloud

# By app name
vefaas config pull --app my-app

# By app ID
vefaas config pull --id app-xxxxx

# By function name
vefaas config pull --func my-function

# By function ID
vefaas config pull --funcId func-xxxxx

Update Settings

vefaas config --buildCommand "npm run build" --outputPath dist --command "node dist/index.js" --port 8000

Available Settings

Configuration Priority

From highest to lowest:

1. Command line flags (--buildCommand, --port, etc.) 2. Cloud function config (synced via config pull or deploy) 3. Local detection (via vefaas inspect) 4. Default values

Ignore Files

.vefaasignore

Controls which files are excluded from upload. Format is similar to .gitignore:

# Local config
*.local
.env.local

# Dependencies
node_modules/
__pycache__/
.venv/

# Build cache
.next/
dist/

Default Ignore Rules

These are always ignored (no config needed):

Cookbook: Deploy Existing Code

Deploy your existing project to veFaaS with automatic framework detection.

Prerequisites

• vefaas CLI installed
• Valid credentials (AKSK/SSO)
• Existing project with supported framework

Scenario A: Simple Deployment (No Env Dependencies)

For projects without database or external service dependencies.

One-liner Deployment

cd your-project

# Deploy with auto-detection
vefaas deploy --newApp my-app --gatewayName $(vefaas run listgateways --first) --yes

The CLI will: 1. Auto-detect framework (Next.js, Nuxt, FastAPI, etc.) 2. Configure build command and output path 3. Run local build 4. Package and upload 5. Deploy and return access URL

[!NOTE]

- Static sites: Auto-detected static projects (Vite, Vitepress, etc.) will be served via auto-generated Caddyfile

- Server apps: If your app requires server logic, ensure it listens on port 8000 by default

Verify Detection

# Check what vefaas detected
vefaas inspect

# Output:
# > Detected Settings:
# > - Build Command: npm run build
# > - Output Directory: .next
# > - Start Command: node server.js
# > - Port: 3000
# > - Runtime: native-node20/v1
# > - Framework: next.js

Scenario B: With Environment Dependencies

For projects requiring database connections, API keys, etc.

Step 1: Link Without Deploying

cd your-project

# Create app and link, but don't deploy yet
vefaas link --newApp my-app --gatewayName $(vefaas run listgateways --first) --yes

Step 2: Configure Environment Variables

# Set individual variables
vefaas env set DATABASE_URL "postgres://user:pass@host:5432/db"
vefaas env set API_KEY "your-api-key"

# Or import from .env file
vefaas env import ./.env.prod

Example .env.prod file:

PGHOST=db.volces.com
PGDATABASE=mydb
PGUSER=admin
PGPASSWORD=secret
API_KEY="your-api-key"

Step 3: Deploy

vefaas deploy

Scenario C: Custom Build Configuration

When auto-detection doesn't match your setup.

Override via Command Line

vefaas deploy \
  --newApp my-app \
  --gatewayName $(vefaas run listgateways --first) \
  --buildCommand "npm run build" \
  --outputPath dist \
  --command "node dist/index.js" \
  --port 3000 \
  --yes

Or Configure Persistently

# Set config first
vefaas config --buildCommand "npm run build" --outputPath dist --command "node dist/index.js" --port 3000

# Then deploy
vefaas deploy --newApp my-app --gatewayName $(vefaas run listgateways --first) --yes

Scenario D: Deploy to Existing Application

When you already have a veFaaS application.

# By app name
vefaas deploy --app my-existing-app --yes

# By app ID
vefaas deploy --appId app-xxxxx --yes

Supported Frameworks

Cookbook: Manage Functions

Pull, modify, and redeploy existing veFaaS functions.

Prerequisites

• vefaas CLI installe
• Valid credentials (AKSK/SSO)
• Existing function in veFaaS console

Scenario A: Pull and Modify Function Code

Step 1: Pull Function Code

# By function name
vefaas pull --func my-function-name

# By function ID
vefaas pull --funcId func-xxxxx

This creates a directory with the function code:

my-function-name/
├── app.py (or index.js)
├── requirements.txt (or package.json)
├── run.sh
└── .vefaas/
    └── config.json

Step 2: Modify Code

cd my-function-name
# Edit your code

Step 3: Redeploy

vefaas deploy
# or with explicit function reference
vefaas deploy --func my-function-name --yes

Scenario B: Push Code to Existing Function

[!NOTE]

push only uploads code without triggering deployment. For most cases, use deploy instead.

# Push code only (no deployment)
vefaas push --func my-function-name --yes

Scenario C: Manage Environment Variables

List Variables

vefaas env list
# Output:
# > Environment Variables:
# DATABASE_URL=postgres://...
# API_KEY=xxx

Get Single Variable

vefaas env get DATABASE_URL

Set Variables

# Set single variable
vefaas env set NEW_KEY "new-value"

# Update existing variable
vefaas env set DATABASE_URL "new-connection-string"

Import from File

vefaas env import .env

Scenario D: View and Update Configuration

View Current Config

vefaas config list

# Output:
# > Config Summary:
# - Application ID: app-xxxxx
# - Function ID: func-xxxxx
# - Region: cn-beijing
# - Gateway ID: gw-xxxxx
# - System URL: https://xxx.apigateway-cn-beijing.volceapi.com/
#
# > Remote Function Settings:
# - Build Command: npm run build
# - Output Directory: dist
# - Start Command: node dist/index.js
# - Port: 3000

Pull Config from Cloud

# By app name
vefaas config pull --app my-app

# By function name
vefaas config pull --func my-function

Update Settings

vefaas config --buildCommand "npm run build:prod" --port 8080

Scenario E: Debug Issues

Enable Debug Mode

vefaas --debug deploy
# or
vefaas -d inspect

View Debug Logs

# Logs are saved to ~/.vefaas/logs/
ls -lt ~/.vefaas/logs/ | head -5

# View latest log
cat ~/.vefaas/logs/$(ls -t ~/.vefaas/logs/ | head -1)

Common Issues

Authentication Failed:

vefaas login --check
vefaas login  # Re-authenticate

Framework Not Detected:

vefaas inspect  # Check detection
vefaas deploy --buildCommand "..." --command "..." --port 8000 --yes

Cookbook: Template Quickstart

Create and deploy a serverless application from official templates.

Prerequisites

• vefaas CLI installed
• Valid credentials (AKSK/SSO)

Scenario: Create a FastAPI Application

Step 1: Login

# Interactive login
vefaas login

# Or non-interactive
vefaas login --accessKey YOUR_AK --secretKey YOUR_SK

# Or via environment variables (recommended for CI)
export VOLC_ACCESS_KEY_ID="YOUR_AK"
export VOLC_SECRET_ACCESS_KEY="YOUR_SK"

Step 2: Initialize from Template

# Interactive - shows template list
vefaas init

# Non-interactive - specify template name
vefaas init --template FastAPI

# With auto dependency install
vefaas init --template FastAPI --installDeps

Available templates include:

• FastAPI - Python web framework for APIs
• Express - Node.js web framework
• Vitepress - Static documentation generator
• Next.js - React framework
• Nuxt - Vue framework

Step 3: Deploy

cd <project-directory>

# One-liner deployment
vefaas deploy --newApp my-fastapi-app --gatewayName $(vefaas run listgateways --first) --yes

Step 4: Access Your Application

vefaas domains
# Output:
# > Access URL: https://xxxxxxx.apigateway-cn-beijing.volceapi.com/

Complete Example

# Full workflow
vefaas login --check

vefaas init --template FastAPI
cd fastapi

vefaas deploy --newApp fastapi-demo --gatewayName $(vefaas run listgateways --first) --yes

vefaas domains

Local Development

After initialization, develop locally before redeploying:

Python (FastAPI/Django/Flask):

pip install -r requirements.txt
python main.py
# or: uvicorn app:app --reload

Node.js (Express/Next.js/Nuxt):

npm install
npm run dev

Then redeploy changes:

vefaas deploy

Environment Variables Reference

Overview

Environment variables are managed remotely on the function and can be accessed in code via:

• Node.js: read from the process environment, for example with bracket access.
• Python: read from os.environ.

Commands

List All Variables

vefaas env list

# Output:
# > Environment Variables:
# DATABASE_URL=postgres://user:pass@host:5432/db
# API_KEY=your-api-key
# NODE_ENV=production

Get Single Variable

vefaas env get DATABASE_URL
# Output: postgres://user:pass@host:5432/db

Set Variable

vefaas env set KEY VALUE

# Examples:
vefaas env set DATABASE_URL "postgres://user:pass@host:5432/db"
vefaas env set API_KEY "your-api-key"
vefaas env set NODE_ENV "production"

Import from File

vefaas env import ./env.prod

File Format

The import command supports .env file format:

# Comments are ignored
KEY=VALUE

# Quoted values
API_KEY="your-api-key"
SECRET='single-quoted'

# With export prefix
export NODE_ENV=production

# Database configuration
PGHOST=db.volces.com
PGDATABASE=mydb
PGUSER=admin
PGPASSWORD=secret123

Supported formats:

• KEY=VALUE - Basic format
• KEY="VALUE" or KEY='VALUE' - Quoted values
• export KEY=VALUE - With export prefix
• # comment - Lines starting with # are ignored

Usage in Code

Node.js

const dbUrl = process.env["DATABASE_URL"];
const apiKey = process.env["API_KEY"];

// With default value
const port = process.env["PORT"] || 3000;

Python

import os

db_url = os.environ["DATABASE_URL"]
api_key = os.environ["API_KEY"]

# With default value
port = int(os.environ["PORT"]) if "PORT" in os.environ else 8000

Common Patterns

Database Connection

vefaas env set PGHOST "db.volces.com"
vefaas env set PGDATABASE "mydb"
vefaas env set PGUSER "admin"
vefaas env set PGPASSWORD "secret"
vefaas env set PGPORT "5432"

API Keys

vefaas env set API_KEY "your-api-key"
vefaas env set JWT_SECRET "your-jwt-secret"

Feature Flags

vefaas env set NODE_ENV "production"
vefaas env set DEBUG "false"

Best Practices

1. Never commit secrets - Use vefaas env instead of config files 2. Use separate env files - env.dev, env.staging, env.prod 3. Import before deploy - For apps with dependencies:

   vefaas link --newApp my-app --gatewayName $(vefaas run listgateways --first) --yes
   vefaas env import ./env.prod
   vefaas deploy

Framework Detection Reference

Overview

vefaas automatically detects project frameworks and configures:

• Build command
• Output directory
• Start command
• Port
• Runtime

Use vefaas inspect to see detected settings.

Inspect Command

vefaas inspect

# Output:
# > Detected Settings:
# > - Install Command: npm ci
# > - Build Command: npm run build
# > - Output Directory: .next
# > - Start Command: node server.js
# > - Port: 3000
# > - Runtime: native-node20/v1
# > - Framework: next.js

JSON output:

vefaas inspect --json

Supported Frameworks

Python

Node.js

Static Sites

Static sites use Caddy as the web server. The Caddyfile is auto-generated.

Override Detection

When auto-detection doesn't match your setup:

Via Command Line

vefaas deploy \
  --buildCommand "npm run build:prod" \
  --outputPath dist \
  --command "node dist/server.js" \
  --port 8080 \
  --yes

Via Config

vefaas config \
  --buildCommand "npm run build:prod" \
  --outputPath dist \
  --command "node dist/server.js" \
  --port 8080

Detection Files

The CLI looks for these files to detect frameworks:

Build Environment

Current behavior:

• Node.js: Build runs locally, output is packaged and uploaded
• Python: Code is uploaded, dependencies installed remotely via requirements.txt

Troubleshooting

Framework not detected:

# Check what's detected
vefaas --debug inspect

# Manually specify
vefaas deploy --buildCommand "..." --command "..." --port 8000 --yes

Wrong build command:

# Override in config
vefaas config --buildCommand "npm run build:production"

Missing dependencies:

# Ensure package.json or requirements.txt exists
# For Node.js, run npm install first
npm install
vefaas deploy

MCP Deployment

Use this reference when the user wants to deploy an MCP project to Volcengine.

Deployment path

For MCP projects, prefer:

1. veFaaS: default path for MCP HTTP exposure and session-keeping support. 2. ECS: fallback when veFaaS does not fit the runtime, dependency installation, or system-control needs. 3. VKE: do not recommend by default. Use only when the user explicitly asks for Kubernetes and already has a session-affinity plan.

Protocol detection

Treat MCP as STDIO by default unless the code, docs, or startup command clearly shows an SSE or Streamable-HTTP service.

• STDIO: no explicit HTTP listener, transport="stdio", mcp.run(..., transport="stdio"), or a command that communicates through stdin/stdout.
• SSE / Streamable-HTTP: the code or startup command clearly starts an HTTP service and exposes a path such as /mcp, /sse, /api/mcp, or /api/sse.

run.sh checks

• run.sh must be in the selected MCP module root.
• The first line must be #!/bin/bash.
• Make it executable before deployment:

chmod +x run.sh

STDIO MCP

STDIO MCP must be wrapped with mcp-proxy before deployment to veFaaS. In veFaaS, mcp-proxy is a built-in tool that converts STDIO MCP to Streamable-HTTP MCP.

• If a STDIO MCP is not started through mcp-proxy, report: MCP needs to be started through mcp-proxy.
• mcp-proxy must include:

--host 0.0.0.0 --port 8000

• For a STDIO binary, wrap it with exec:

mcp-proxy --host 0.0.0.0 --port 8000 -- exec ./server

8000 is the mcp-proxy wrapper port. It is not a global veFaaS port rule.

SSE / Streamable-HTTP MCP

If the MCP already serves SSE or Streamable-HTTP, do not add mcp-proxy.

Check that:

• The service listens on 0.0.0.0.
• The listening port matches the veFaaS deployment configuration.
• The endpoint path is clear from code or startup arguments.

Do not force port 8000 unless the startup command or veFaaS config explicitly uses 8000. If host, port, or endpoint path cannot be confirmed, ask for confirmation instead of failing the deployment.

Python MCP

If run.sh starts MCP with python3:

• requirements.txt must exist in the MCP module root.
• The first line of requirements.txt must be . so the module itself is installed.

Node.js MCP

• Add -y when using npx to avoid interactive prompts.
• For Node.js STDIO MCP, first try wrapping it with mcp-proxy; if that cannot work, suggest changing the MCP to SSE or Streamable-HTTP.

Unsupported or manual-confirmation paths

• Do not use uv and uvx; veFaaS not support this MCP run Mode.
• Kotlin, Java, Swift, C#, Ruby, and PHP MCP projects are not default deployment paths.

Output

After deployment, print the MCP service URL.

• With mcp-proxy, treat the protocol as Streamable-HTTP and use:

{AccessUrl}/mcp

• Without mcp-proxy, print the actual endpoint path from code or startup arguments.

Client example:

{
  "mcpServers": {
    "<function-name>": {
      "url": "<AccessUrl>/mcp"
    }
  }
}

Troubleshooting Reference

Enable Debug Mode

When encountering issues, first enable debug mode with --debug or -d:

vefaas --debug deploy
# or
vefaas -d inspect

Debug mode outputs:

• Framework detection: Detected framework, runtime, build command
• Shell execution: Commands, working directory, exit codes
• Packaging: Ignore rules, file count, package size
• HTTP requests/responses: API call parameters and results

Debug Log Files

Debug logs are automatically saved to files:

# Log file location
~/.vefaas/logs/YYYYMMDD-HHMMSS.txt

# View recent logs
ls -lt ~/.vefaas/logs/ | head -5

# View latest log
cat ~/.vefaas/logs/$(ls -t ~/.vefaas/logs/ | head -1)

Log files contain full JSON response data (terminal shows preview only).

Common Issues

1. Authentication Failed

Symptoms: InvalidAccessKey or SignatureDoesNotMatch error

Steps:

# Check credential status
vefaas login --check

# Re-login
vefaas login

Common causes:

• Incorrect AK/SK
• Expired credentials
• Sub-account missing veFaaSFullAccess policy

2. Framework Detection Failed

Symptoms: Incorrect build command or runtime

Steps:

vefaas --debug inspect

Common causes:

• Missing package.json or requirements.txt
• Non-standard project structure

Solution: Manually specify configuration:

vefaas deploy --buildCommand "npm run build" --outputPath dist --command "node dist/index.js" --port 3000

3. Build Failed

Symptoms: command exited with code X error

Steps:

# View full error with debug mode
vefaas --debug deploy

# Test build command locally
npm run build

Common causes:

• Dependencies not installed (run npm install first)
• Node.js version incompatible
• Missing environment variables

4. Deploy Timeout

Symptoms: dependency install timeout error

Steps:

vefaas --debug deploy

Common causes:

• Too many Python dependencies or large packages
• Network issues causing slow downloads

Solution: Reduce unnecessary dependencies, or pin versions in requirements.txt.

5. Gateway Not Found

Symptoms: No running gateways found error

Steps:

vefaas run listgateways

Solution: Create an API Gateway instance in the API Gateway console.

--app vs --func

• Use --app for application-level operations (includes triggers, domains)
• Use --func or --funcId for function-level operations (code updates only)

Find function name/ID in the function details page, then use pull and deploy to manage.

Submit Feedback

If issues persist, collect this information:

# 1. CLI version
vefaas --version

# 2. Debug log
vefaas --debug <command> 2>&1 | tee debug.log

# 3. Latest log file
cat ~/.vefaas/logs/$(ls -t ~/.vefaas/logs/ | head -1)

# 4. Environment info
node -v
uname -a

Include:

• Operating system version
• Node.js version
• Project framework type