referenceupdated
vbtnl.json reference
Every field of vbtnl.json, the settings file in the project root that tells vbtnl how to build, start and schedule your app.
Each project has a vbtnl.json file in its root. Your AI agent writes it for you; this page explains what is inside.
Example
json
{
"stack": "python",
"start": "uvicorn main:app --host 0.0.0.0 --port $PORT",
"release": "alembic upgrade head",
"database": "postgres",
"cron": [
{ "schedule": "0 9 * * 1", "run": "python report.py" }
]
}
Fields
| Field | Required | Meaning |
|---|---|---|
stack | yes | python (3.12), node (22) or static. |
start | python, node | The production command. It must listen on 0.0.0.0 and the port from $PORT. |
dev | no | The command for the draft. Defaults to start. |
release | no | Runs once per publish before traffic switches, usually database migrations. If it fails, production keeps the old version. |
build | no | Python: a custom install command. Node.js: the build command, by default npm run build --if-present. |
static_dir | no | Static sites: the folder to serve. Defaults to the project root. |
database | no | "postgres" if the app uses the project database. |
cron | no | Up to 10 scheduled commands. Each has schedule (five-field cron, UTC) and run. |
Stacks
python. Dependencies in requirements.txt or pyproject.toml. In the draft they install automatically when the file changes.
node. Dependencies in package.json. Production runs the build command, then start (by default npm start).
static. Plain files, served as they are.
There is no Dockerfile to write: vbtnl builds the image itself. System packages cannot be installed with apt-get; use pip or npm packages.
Environment variables
| Variable | Value |
|---|---|
PORT | The port the app must listen on. |
DATABASE_URL | The Postgres address. The draft and production have separate databases. |
VBTNL_ENV | dev in the draft, prod in production. |
VBTNL_URL | The public address of the app. |
Your own keys are added as secrets and appear as environment variables too.
Limits
- HTTP and HTTPS only, no custom ports.
- Outgoing connections: ports 80, 443, 465, 587 and common database ports. Port 25 is closed.
- CPU, memory and disk per project depend on your plan.