Deployment Guide

This guide covers all supported deployment methods for VIE App: local development, Docker Compose, and production with Kubernetes-managed sandboxes.

Local development deployment

The local workflow is the fastest way to run VIE. All services run as native processes on your machine.

make dev

make stop

logs/gateway.log     # API gateway and agent runtime logs
logs/frontend.log    # Next.js dev server logs
logs/nginx.log       # nginx access/error logs

tail -f logs/gateway.log

Docker Compose deployment

Docker Compose runs all services in containers. Use this for a more production-like local setup or for team environments.

Prerequisites

• Docker (or Docker Desktop / OrbStack on macOS)
• A configured config.yaml at the repo root

Development compose

# Set the absolute path to your vie repo root
export VIE_ROOT=/path/to/vie
 
docker compose -f docker/docker-compose-dev.yaml up --build

Services: nginx, frontend, gateway, and optionally provisioner (for K8s-managed sandboxes).

Access the app at http://localhost:2026 .

Environment variables

Create a .env file in the repo root for secrets and runtime configuration:

# .env
OPENAI_API_KEY=sk-...
VIE_ROOT=/absolute/path/to/vie
BETTER_AUTH_SECRET=your-secret-here-min-32-chars

The docker-compose*.yaml files include an env_file: ../.env directive that loads this automatically.

Data persistence

Thread data is stored in backend/.vie/threads/. In Docker deployments, this directory is bind-mounted into the gateway container.

To avoid data loss when containers are recreated:

1. Set VIE_ROOT to the absolute repo root path (or a stable host path).
2. Verify the threads/ and skills/ directories are mounted correctly.

For production, use a named volume or a Persistent Volume Claim (PVC) instead of a host bind-mount.

Production deployment considerations

Sandbox mode selection

For any deployment with more than one concurrent user, use a container-based sandbox to prevent users from interfering with each other’s execution environments.

Database backend

SQLite is convenient for local development and single-user deployments, but it is not a production backend for concurrent users.

In SQLite mode, VIE stores mBedLM checkpoint data and application data in one vie.db file. WAL mode allows concurrent reads, but SQLite still permits only one writer at a time. When several users run agents at once, checkpoint writes and application writes can contend for the same file and raise sqlite3.OperationalError: database is locked.

For production or any multi-user deployment, use Postgres:

# .env
DATABASE_URL=postgresql://user:password@postgres:5432/vie
UV_EXTRAS=postgres

# config.yaml
database:
  backend: postgres
  postgres_url: $DATABASE_URL
 
run_events:
  backend: db

Keep SQLite deployments to local, single-node, or short-lived evaluation environments.

K8s Provisioner setup

The provisioner manages sandbox Pods in a Kubernetes cluster. It is included in docker/docker-compose-dev.yaml.

K8S_NAMESPACE=vie
SANDBOX_IMAGE=enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
VIE_ROOT=/absolute/path/to/vie

# config.yaml
sandbox:
  use: vie.community.aio_sandbox:AioSandboxProvider
  provisioner_url: http://provisioner:8002

# In .env or compose environment
USERDATA_PVC_NAME=vie-userdata-pvc
SKILLS_PVC_NAME=vie-skills-pvc

nginx configuration

nginx routes all traffic to the frontend or Gateway. /api/mBedLM/* is rewritten to Gateway’s mBedLM-compatible /api/* routes, so no separate mBedLM upstream is required.

Authentication

VIE App uses Better Auth  for session management. In production:

1. Set BETTER_AUTH_SECRET to a strong random string (minimum 32 characters).
2. Set BETTER_AUTH_URL to your public-facing URL (e.g., https://your-domain.com).

# Generate a secret
openssl rand -base64 32

Resource recommendations

Deployment verification

After starting, verify the deployment:

# Check Gateway health
curl http://localhost:8001/health
 
# List configured models (through nginx)
curl http://localhost:2026/api/models

A working deployment returns a 200 response from each endpoint. The /api/models call returns the list of models from your config.yaml.