Setup and first deploy

Install the CLI

npm i -g runlot
runlot login

runlot login opens your browser to sign in to your account. The issued token is stored per control plane URL in ~/.runlot/credentials.json, with file permissions set to 0600.

Create a project

npm create runlot@latest my-app
cd my-app

The template contains only runlot.json, src/index.ts, public/hello.txt, .gitignore, and the directories you need. It stays minimal so you can see the whole deploy setup — runlot.json, the worker entry point, and the static assets directory — at a glance.

The directory name becomes the project name, and the project name becomes the first label of your deploy URL. It therefore has to match ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$. If it doesn't, the setup walks you through it.

Deploy

runlot deploy

The command builds a bundle, uploads it, and serves the new version. If the project doesn't exist yet it is created automatically, so there's nothing to set up before your first deploy.

When the deploy finishes, you'll see a URL like this.

my-app.me.runlot.app

The format is <project>.<organization>.runlot.app. See Deploy URL for the naming rules.

Turn on the database

Add one line to runlot.json and deploy. There is no command to turn it on. The deploy reads the declaration and creates what is missing.

{
  "name": "my-app",
  "main": "src/index.ts",
  "database": true
}

runlot deploy

Login and file storage go in the same place. Declare only the ones you need.

{
  "database": true,
  "auth": true,
  "storage": true
}

App auth requires a database, so "auth": true on its own creates the database as well. The deploy output says what it created, and it never creates something that already exists.

After the deploy, your worker can use env.db, env.auth, and env.storage right away. There are no connection strings or secrets to configure. psql connection details are in runlot pg connect.

What to read next

• Project structure — what runlot.json and the entry point do
• env.db — how to use the database
• Deploy URL — the rules that determine your URL