zerobased

zerobased

Zero-config Docker service router. Watches docker.sock for container events, auto-classifies ports, creates Unix sockets + HTTP routes. Cleans up when containers stop.

No config files. No Docker labels. No setup scripts. No external dependencies. Your existing docker-compose.yml works as-is.

Install

npm install -g zerobased

Or build from source:

git clone https://github.com/lagz0ne/zerobased.git
cd zerobased && make install

Quick start

# Start the daemon (background)
zerobased start -d

# Your existing workflow — unchanged
docker compose up -d

# See what was discovered
zerobased ps

Example output:

acountee:
  postgres        socket 5432 → postgresql://postgres@/postgres?host=~/.zerobased/sockets/acountee
  nats            http   80   → http://nats-80.acountee.localhost
  nats            http   8222 → http://nats-8222.acountee.localhost
  nats            port   4222 → localhost:26987

CLI

zerobased [flags] <command> [args...]

Flags:
  -H, --docker-host <host>   Docker daemon socket
  --prefix <prefix>          Env var prefix (default: ZB; "" for no prefix)
  --profile <names>          Route profiles from zerobased.routes.yaml (comma-separated)

Commands:
  start [-d]                               Start daemon (-d for background)
  stop                                     Stop daemon + cleanup
  logs [-f]                                Show daemon logs (-f to follow)
  run [-p port] [name] <cmd>               Wrap dev server, register route
  env [--export] [project]                 Print connection strings
  ps                                       Show all discovered services
  get <service> [-t template] [-v k=v]     Print one connection string
  domain add <domain> [--ttl 2h]           Add external domain (default TTL: 4h)
  domain add <domain> --persistent         Add domain that never expires
  domain list                              Show configured domains + TTL
  domain rm @N                             Remove domain by index
  share [@N]                               Show shareable URLs for all/one domain
  unshare @N | --all                       Remove domain(s) + deregister routes

Daemon

zerobased start              # foreground (Ctrl+C to stop)
zerobased start -d           # background, auto-follows logs (Ctrl+C detaches)
zerobased logs -f            # follow daemon logs
zerobased stop               # stop + cleanup

Wrapping dev servers

zerobased run acountee pnpm dev           # auto-detects port from stdout/stderr
zerobased run -p 3000 acountee pnpm dev   # explicit port

Port is auto-detected by scanning the child process output for http://localhost:XXXX. Works with Vite, Next, Nuxt, or any framework that prints its URL. Use -p if auto-detect doesn't work.

Also injects ZB_* env vars for all project services:

ZB_POSTGRES_5432=postgresql://postgres@/postgres?host=~/.zerobased/sockets/acountee
ZB_NATS_4222=localhost:26987
ZB_NATS_80=http://nats-80.acountee.localhost

Path-based routing (routefile)

Drop a zerobased.routes file next to your docker-compose.yml to get a single gateway with path routing instead of one hostname per service:

# zerobased.routes
/api     api
/ws      ws
/        frontend

This creates myapp.localhost/api, myapp.localhost/ws, myapp.localhost/ — each routing to the named docker-compose service. The gateway hostname is derived from your Compose project name.

No routefile = existing hostname-per-service behavior. Nothing breaks.

Profiles & external upstreams

Use zerobased.routes.yaml for profiles with inheritance and external service targets:

# zerobased.routes.yaml
profiles:
  default:
    routes:
      /api: api
      /ws: ws
      /: frontend

  debug:
    extends: [default]
    routes:
      /db: postgres://staging-db.example.com:5432

  staging:
    extends: [default]
    routes:
      /api: https://api.staging.example.com
      /ws: wss://ws.staging.example.com

zerobased start --profile debug          # local app + staging DB
zerobased start --profile staging,debug  # merge multiple profiles

Supported external targets: https://, wss://, postgres://, nats://, redis://. Profiles merge left-to-right with last-write-wins on conflicting paths.

Connection strings

# Default
zerobased get postgres
# postgresql://postgres@/postgres?host=~/.zerobased/sockets/acountee

# With template + user vars
zerobased get postgres \
  -t 'postgresql://{{user}}:{{pass}}@/{{db}}?host={{socket_dir}}' \
  -v user=postgres -v pass=secret -v db=mydb

# Just the socket directory
zerobased get postgres -t '{{socket_dir}}'

# NATS with scheme
zerobased get nats -t 'nats://{{host}}:{{port}}'

Template variables: project, service, container_port, method, conn, url, socket, socket_dir, host, port

Shell eval