Faux

Faux is a small CLI for local development stacks. You describe the services your app depends on and the external systems you want to mock in faux.yaml, and Faux turns that into a Docker Compose setup you can validate, start, inspect, and wire into your app quickly.

Its most useful developer features live around the daily workflow: faux validate catches config footguns before startup, and faux env prints local connection variables from the same config you use to boot the stack so you do not have to manually translate ports into .env values every time you start working.

What Faux Does Well

• Runs local dependency services like Postgres and Redis from a small config file.
• Creates lightweight HTTP and MQTT mock endpoints for third-party integrations.
• Validates Faux-owned config before startup and env export.
• Captures mock traffic so you can inspect requests in the dashboard.
• Prints canonical local connection variables with faux env.

Installation

Install Faux globally:

npm install -g @lumiotech/faux

Or run it directly with npx:

npx @lumiotech/faux start

Quick Start

Create a faux.yaml file in your project:

services:
  postgres:
    image: postgres:15
    port: 5432
    environment:
      - POSTGRES_PASSWORD=secret

  redis:
    image: redis:7
    port: 6379

external_mocks:
  stripe:
    type: http
    port: 9001

  github:
    type: http
    port: 9002

Validate the config first:

faux validate

Start the local stack:

faux start

Print the local connection variables Faux derives from that config:

faux env

Example output:

# Faux local environment
# Copy the values you need into your app config.

# Services
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
REDIS_HOST=localhost
REDIS_PORT=6379

# External mocks
STRIPE_HOST=localhost
STRIPE_PORT=9001
STRIPE_URL=http://localhost:9001
GITHUB_HOST=localhost
GITHUB_PORT=9002
GITHUB_URL=http://localhost:9002

Launch the dashboard to inspect running containers and captured mock requests:

faux ui

The default dashboard URL is http://localhost:4000.

Validation And Failure Behavior

Use faux validate when you want a quick preflight in the terminal or CI:

faux validate

Example output when the config has both blocking and non-blocking issues:

Errors:
- external_mocks.mailer.type: Mock type must be either "http" or "mqtt".

Warnings:
- team: Unknown top-level key. Faux ignores this key.

Validation rules in this version focus on Faux-owned behavior:

• services and external_mocks must be mapping objects when present.
• Service and mock ports must be integers between 1 and 65535.
• Mock type must be http or mqtt.
• Published ports cannot collide across services and mocks.
• Unknown top-level keys are warnings, not errors.
• mode supports sbc, and profile: lightweight remains accepted for backward compatibility.

faux start and faux env run this validation automatically. Errors stop the command with a non-zero exit code. Warnings print to stderr, but the command continues.

How To Use Faux With Your App

Faux intentionally prints generic, zero-config variables based on your service and mock names. That keeps the feature predictable and avoids rewriting your app config behind your back.

If you want a helper file for your local session, redirect the output:

faux env > .env.faux

From there you can copy the values you need into your app's .env, or source the file in your own local workflow. Faux does not generate DATABASE_URL or other app-specific aliases in this version; it gives you stable building blocks like POSTGRES_HOST, POSTGRES_PORT, and STRIPE_URL.

Because validation warnings go to stderr, redirecting faux env to a file keeps the dotenv output clean on stdout.

Commands

• faux start starts the stack defined in faux.yaml.
• faux validate checks Faux-owned config rules before you start services or export env vars.
• faux env prints local connection variables in dotenv format.
• faux ui starts the local dashboard on port 4000 by default.
• faux status shows docker compose ps output for the generated stack.
• faux logs tails logs from the running stack.
• faux stop stops and removes the generated stack.
• faux import <docker-compose.yml> converts an existing Compose file into a basic faux.yaml.

Configuration

services

Use services for local dependencies such as databases, caches, or internal tooling containers. Faux passes most service configuration through to Docker Compose. If you want faux env to export a service, give it an explicit port.

external_mocks

Use external_mocks for systems you do not want to hit for real during development.

• type: http creates a local HTTP mock endpoint and captures requests in the dashboard.
• type: mqtt creates a local MQTT broker and captures published messages in the dashboard.
• If type is omitted, Faux treats the mock as HTTP.

mode

Set mode: sbc if you want Faux to apply lightweight resource limits and ARM-oriented platform hints for small Linux devices such as Raspberry Pi boards.

Example Workflow

faux validate
faux start
faux env > .env.faux
faux ui

This gives you:

• running local dependencies
• local mock endpoints for integrations
• inspectable request history
• a single place to discover the localhost values your app needs

Roadmap

Ideas that are still future work:

• app-specific alias mapping such as DATABASE_URL
• optional env file writing as a first-class command behavior
• auto-port collision resolution

Contributing

Contributions are welcome. Before opening a pull request:

npm install
npm test -- --runInBand
npm run lint

See CONTRIBUTING.md for the development process.