Running Locally

Run Backflow directly on your machine without Docker or cloud services. Everything uses SQLite for storage — no external databases required.

Computer (macOS / Linux / Windows)

Prerequisites

• Node.js 20+

Install & Run

npm install -g @backflow/server
backflow init
backflow start

This creates a fully offline instance:

Component	Provider
Database	SQLite (./data/backflow.db)
Cache	SQLite (./data/cache.db)
Job Queue	SQLite (./data/queue.db)
File Storage	Local filesystem (./storage/)

The server starts at http://localhost:3000.

With Redis (optional)

If you have Redis installed, you can use it for caching and job queues:

backflow init --redis
backflow start

This uses Redis for cache (via ioredis) and queues (via BullMQ) while keeping SQLite for the database and local filesystem for storage.

With Vector Search (optional)

To enable AI embeddings and vector search locally:

backflow init --qdrant
backflow start

This connects to a Qdrant instance. Run Qdrant locally with Docker:

docker run -p 6333:6333 qdrant/qdrant

Or use the built-in SQLite vector store (no external service needed) by setting vectorStore.type to "sqlite" in your config.

Standalone Binary

Build a single executable with no Node.js dependency:

# In the backflow repo
npm run bundle:mac     # macOS (ARM64 + x64)
npm run bundle:linux   # Linux (x64)
npm run bundle:windows # Windows (x64)

The binary is output to dist-bin/ and can be distributed as a single file.

Android (Termux)

Run Backflow on Android using Termux — a terminal emulator with a full Linux environment.

Install Termux

Download from F-Droid (the Play Store version is outdated).

Install & Run

pkg install nodejs-lts
npm install -g @backflow/server
backflow init
backflow start

Access the server from your Android browser at http://localhost:3000.

With Redis on Android

pkg install redis
redis-server &
backflow init --redis
backflow start

Native Module Compilation

If better-sqlite3 needs to compile from source:

pkg install build-essential python
npm install -g @backflow/server

iOS

Not currently available. iOS does not allow background processes or local servers in user-installed apps.

Configuration

The backflow init command generates a config.json configured for local/offline use:

{
  "databaseProvider": "sqlite",
  "sqlite": {
    "filename": "./data/backflow.db"
  },
  "storageProvider": "local",
  "localStorage": {
    "basePath": "./storage"
  },
  "cache": {
    "enabled": true,
    "provider": "sqlite",
    "sqlite": { "dbPath": "./data/cache.db" }
  },
  "queue": {
    "enabled": true,
    "type": "sqlite",
    "sqlite": { "dbPath": "./data/queue.db" }
  }
}

Switching providers

You can mix local and cloud providers. For example, use SQLite for the database but R2 for file storage:

{
  "databaseProvider": "sqlite",
  "storageProvider": "r2",
  "r2": {
    "accountId": "...",
    "accessKeyId": "...",
    "secretAccessKey": "...",
    "bucket": "my-bucket"
  }
}

Or use Supabase for the database but keep local file storage:

{
  "databaseProvider": "supabase",
  "supabase": {
    "url": "https://your-project.supabase.co",
    "anonKey": "your-key"
  },
  "storageProvider": "local"
}

CLI Reference

Command	Description
backflow init	Initialize with SQLite-only defaults
backflow init --redis	Initialize with Redis for cache + queues
backflow init --qdrant	Initialize with Qdrant vector search
backflow start	Start the server
backflow start config.json 8080	Start with custom config and port
backflow status	Show server and provider status

Directory Structure

After backflow init:

./
├── config.json          # Server configuration
├── data/
│   ├── backflow.db      # SQLite database
│   ├── cache.db         # SQLite cache
│   └── queue.db         # SQLite job queue
└── storage/             # Local file storage