Quick Start Guide

Get your LiteBin running and deploy your first app in under 5 minutes.

commands for

Install Master

Orchestrator + Dashboard + Caddy

Create Admin Account

Set up dashboard access

Add Worker Nodes (Optional)

Scale to multiple servers

Install Master

SSH into your Linux VPS and run:

curl -fsSL https://l8b.in | bash

Fresh VPS? Optionally harden it before installing — SSH keys, firewall, fail2ban: basic security setup script →

The installer will prompt for:

→Domain (e.g. example.com)
→Dashboard subdomain (default: l8bin)
→Routing mode: master_proxy or cloudflare_dns (default: master_proxy)

Choose Deployment Method

How do you want to deploy your apps?

AI Agent

Deploy from Cursor or Claude

Deploy via CLI

Build on your machine, stream the image to your server. No registry needed.

Install CLI locally:

Option A: Prebuilt binary (easiest)

curl -fsSL https://l8b.in | bash -s cli

Option B: Build from source (requires Cargo)

git clone https://github.com/mtsandeep/l8bin.git
cd l8bin
./setup/build.sh
bash install.sh cli

Option A: Prebuilt binary (easiest)

iex "& { $(irm https://l8b.in/windows.ps1) } -Cli"

Option B: Build from source (requires Cargo)

git clone https://github.com/mtsandeep/l8bin.git
cd l8bin
.\setup\build.ps1
powershell -File .\install-windows.ps1 cli

Verify Installation (PATH)

The installer automatically configures your PATH. Open a new terminal and run l8b --version to verify.

If 'l8b' command not found (Troubleshooting)

Add ~/.local/bin to your shell profile manually:

# bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

# zsh (macOS default)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

l8b login --server https://l8bin.example.com

Note: If running LiteBin locally, use http://localhost:5080 as the server. Cloud-hosted instances work normally over HTTPS.

Interactive deploy (auto-detects Dockerfile or uses Railpack):

l8b ship

Or deploy non-interactively:

l8b deploy --project myapp

Port is auto-detected from EXPOSE. Use --port to override.

Deploy from GitHub

Push to your repo and the site updates itself. Let LiteBin wire it up, or write the workflow yourself.

Recommended: Connect GitHub — zero YAML, zero secrets to paste

Create your GitHub App

Dashboard → Settings → GitHub → Create GitHub App. It's your own private app — you own it, and you choose which repos it can see.

Pick a repo and a project

LiteBin commits the workflow (.github/workflows/litebin-<project>-deploy.yml) and sets the secrets (L8B_SERVER + L8B_TOKEN_<PROJECT>) for you.

Choose the trigger

Auto-deploy on every push to your branch (builds run on GitHub-hosted runners), or keep it manual — trigger deploys from the GitHub Actions tab or the LiteBin dashboard.

Manual: write the workflow yourself

Exactly what Connect GitHub commits for you — same workflow, same secrets, done by hand. Create .github/workflows/deploy.yml:

name: LiteBin Deploy
on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: mtsandeep/l8bin-action@v0.2.0
        with:
          server: ${{ secrets.L8B_SERVER }}
          token: ${{ secrets.L8B_TOKEN_MYAPP }}
          project_id: myapp

Required GitHub Secrets:

L8B_SERVERhttps://l8bin.example.com (orchestrator URL)
L8B_TOKEN_MYAPPOne token per project (L8B_TOKEN_<PROJECT>). Generate from Dashboard → Settings → API Tokens

Every push to main will now auto-deploy to your LiteBin cluster.

Docker Compose (Optional)

Deploy multi-service apps with docker-compose.yml. LiteBin auto-detects it when you run l8b ship or upload it from the dashboard.

Sample: API + Postgres

services:
  api:
    image: node:24-alpine
    ports:
      - "3000"              # LiteBin routes HTTP to this port
    environment:
      - DATABASE_URL=${DATABASE_URL:-postgres://postgres:password@db:5432/myapp}
    working_dir: /app
    volumes:
      - app-data:/app/data   # Named volume (scoped to litebin_<project>_app-data)
      - ./logs:/app/logs     # Bind mount (under projects/<project>/logs/)
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 256M
          cpus: "0.5"
    labels:
      litebin.public: "true" # Mark as the public service (optional)

  db:
    image: postgres:16-alpine
    ports:
      - "5432"              # Only accessible within the Docker network
    environment:
      - POSTGRES_DB=myapp
      - POSTGRES_PASSWORD=${DB_PASSWORD:-password}
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  app-data:
  pgdata:

✓ Supported

image, build (context + dockerfile)
command, entrypoint
working_dir, user
environment (with ${VAR} interpolation)
ports (TCP + UDP, with protocol)
depends_on (long form with conditions)
volumes (named volumes + bind mounts)
healthcheck
restart (no, always, unless-stopped)
stdin_open, tty
deploy.resources.limits (memory + cpus)
shm_size, tmpfs, read_only
cap_add, cap_drop, extra_hosts
labels (litebin.public to pick public service)

! Differences from standard Docker Compose

networks — Ignored. LiteBin creates one managed network per project and connects all services to it.
container_name — Ignored. LiteBin auto-generates container names.
ports host binding — Host port and IP are ignored. Only the container port is used. LiteBin binds the public service's port internally and routes via Caddy.
configs — Not supported.
secrets — Use projects/<project>/.env for runtime secrets. LiteBin auto-detects changes and recreates the container on next wake. See env-secrets.md.
Auto-wake — Only HTTP traffic through Caddy triggers auto-wake. Hitting the public HTTP port wakes all services in the project (including non-HTTP ones). But direct traffic to non-HTTP ports bypasses Caddy and won't trigger a wake.
Non-HTTP ports — Enable "Allow raw ports" in dashboard settings to bind all compose ports directly on the host (bypasses Caddy).
volumes — Named volumes are scoped with a litebin_<project>_ prefix. Bind mounts with relative paths are stored under projects/<project>/.

Public Service Detection

LiteBin picks one service as the public HTTP endpoint (routed through Caddy with TLS). Detection order:

Service with litebin.public: "true" label
Service exposing port 80 or 443
If only one service declares ports, that service is picked

If multiple services have ports and none match the above, l8b ship asks you to pick the public service. For CI (l8b deploy), the first service is auto-selected.

Dockerfile (Optional)

If a Dockerfile exists in your project root, l8b ship uses it to build your image. Otherwise, Railpack auto-detects your framework.

Sample: Node.js App

FROM node:24-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

FROM node:24-alpine
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

i How it works

Detection: l8b ship checks for Dockerfile in your project root. If found, it builds with Docker. Otherwise, it uses Railpack.
Multi-stage builds: Fully supported. Use FROM ... AS builder pattern as shown above.
Custom Dockerfile: Use l8b ship --dockerfile Dockerfile.dev to specify a different filename.
Build secrets: Use l8b ship --secret .env to pass secrets at build time (baked into the image).
Cross-platform: The CLI auto-detects the target server's architecture and builds for the correct platform. No manual --platform flag needed.
Port: l8b ship auto-detects the port from EXPOSE in your Dockerfile. If multiple ports are exposed, the first one is used. If none, you'll be prompted (default: 3000).

Quick Start Guide

Install Master

Create Admin Account

Add Worker Nodes (Optional)

Linux Only (Agent)

Choose Deployment Method

CLI

Dashboard UI

GitHub

AI Agent

Deploy via CLI

Verify Installation (PATH)

Dashboard UI

Deploy from GitHub

Docker Compose (Optional)

Sample: API + Postgres

✓ Supported

! Differences from standard Docker Compose

Public Service Detection

Dockerfile (Optional)

Sample: Node.js App

i How it works