Minibox Compose Service Discovery via /etc/hosts Injection

Minibox Compose gives every container in a project an automatic, zero-configuration hostname based on its service name. There is no embedded DNS server — instead, the daemon writes a custom /etc/hosts file into each container’s rootfs before PID 1 starts, mapping every sibling service name to its assigned IP address.

How /etc/hosts Injection Works

When a container starts as part of a Compose project the daemon follows these steps:

Allocate a container IP

Each container is assigned a private IP address in the 172.19.0.x subnet, allocated from the minibox0 bridge.

Query sibling container state

The daemon reads the runtime state.json to find all other containers that share the same project name and are currently running.

Generate the hosts file

A hosts file is constructed that maps every service name (and container ID short-form) to its IP address, alongside the standard localhost entries.

Write before PID 1 starts

The generated file is written to containers/<id>/rootfs/etc/hosts inside the container’s overlay filesystem before the init process executes, so the mappings are available from the very first moment the application runs.

IP Address Assignment

All Minibox containers share the 172.19.0.0/24 address space managed by the minibox0 bridge:

Address	Role
`172.19.0.1`	`minibox0` bridge (host gateway)
`172.19.0.2`	First container allocated
`172.19.0.3`	Second container allocated
`172.19.0.x`	Subsequent containers

The bridge and address range are configured once during daemon startup (or lazily on first use when MINIBOX_BRIDGE_ON_STARTUP=0).

Example Hosts File

For a project named shop with services db, cache, and api, the hosts file injected into the api container would look like:

127.0.0.1   localhost
::1         localhost ip6-localhost ip6-loopback

# minibox compose — shop
172.19.0.2  db
172.19.0.3  cache
172.19.0.4  api

Every service sees the same entries, so db can also reach api by name.

Connection String Examples

Because service names resolve as hostnames, your application code connects to siblings exactly the same way it would connect to a named host on any network.

Node.js
Python
Go

// Redis client
const redis = require("redis");
const client = redis.createClient({ url: "redis://cache:6379" });

// PostgreSQL client
const { Pool } = require("pg");
const pool = new Pool({
  connectionString: "postgres://user:pass@db:5432/mydb",
});

import redis
import psycopg2

# Redis
r = redis.Redis(host="cache", port=6379)

# PostgreSQL
conn = psycopg2.connect(
    host="db",
    port=5432,
    dbname="mydb",
    user="user",
    password="pass",
)

import (
    "database/sql"
    "github.com/redis/go-redis/v9"
    _ "github.com/lib/pq"
)

// Redis
rdb := redis.NewClient(&redis.Options{
    Addr: "cache:6379",
})

// PostgreSQL
db, err := sql.Open("postgres",
    "host=db port=5432 user=user password=pass dbname=mydb sslmode=disable")

Inject the service name as an environment variable in minibox-compose.yaml (e.g. REDIS_HOST=cache) so your application reads it from the environment rather than hard-coding it.

Persistent Volumes with db_mode

Database services commonly need data to survive compose down / compose up cycles. Setting db_mode: true together with a data path tells Compose to provision a named persistent volume that is reused across runs.

services:
  db:
    image: postgres:16-alpine
    db_mode: true
    data: /var/lib/postgresql/data   # mounted from DataRoot/volumes/myapp-db-data

The volume directory is stored under DataRoot/volumes/<project>-<service>-data on the host. Because it lives outside the container’s overlay filesystem, its contents survive container removal.

db_mode also relaxes the default capability-drop policy. The container retains capabilities required for database engines to chown internal data directories. Enable this only for trusted database workloads.

Limitations

Keep these constraints in mind when designing your service topology.

Static injection — hosts entries are written once at container start. If a sibling container is replaced (e.g. compose restart of one service), already-running containers will continue to resolve the old IP until they are restarted too. Use compose restart on the whole project to refresh all entries.
Same-project scope — service name resolution only works within a single Compose project. Containers from different projects cannot reach each other by service name.
172.19.0.0/24 capacity — the subnet supports up to 253 containers. Projects larger than this are not currently supported.
No SRV or port records — only A-record-style hostname-to-IP mappings are injected. Port information must be encoded in connection strings by the application.

Get Started

Building Images

Running Containers

Compose Orchestration

Operations

Minibox Compose Service Discovery via /etc/hosts Injection

How /etc/hosts Injection Works

IP Address Assignment

Example Hosts File

Connection String Examples

Persistent Volumes with db_mode

Limitations

Build docs developers (and LLMs) love

Get Started

Building Images

Running Containers

Compose Orchestration

Operations

Documentation Index

​How /etc/hosts Injection Works

​IP Address Assignment

​Example Hosts File

​Connection String Examples

​Persistent Volumes with db_mode

​Limitations

Build docs developers (and LLMs) love

How /etc/hosts Injection Works

IP Address Assignment

Example Hosts File

Connection String Examples

Persistent Volumes with db_mode

Limitations