Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/chaitu426/minibox/llms.txt

Use this file to discover all available pages before exploring further.

The minibox compose command orchestrates multi-container applications defined in a minibox-compose.yaml file. It reads the service graph, resolves dependencies using a topological sort (DAG), builds images that have a build context, and manages the full lifecycle of every service in the project.

​
Overview

minibox compose <subcommand> [-f <file>]
​
-f
string
default:"minibox-compose.yaml"
Path to the compose file. Defaults to minibox-compose.yaml in the current directory.

​
Example minibox-compose.yaml

name: my-app
services:
  db:
    image: redis:latest
    db_mode: true
    data: /data
    ports:
      - "6379:6379"

  web:
    build: .
    ports:
      - "8080:8080"
    depends_on:
      - db
    environment:
      - REDIS_HOST=db
Services with a build key have their image built automatically by compose before starting. The image is tagged as <project>-<service> for internal use.

​
up

Build all service images (if build is defined) and start all containers in dependency order. 
minibox compose up [-f <file>]

# Start with default compose file
minibox compose up

# Start from a specific file
minibox compose up -f ./infra/minibox-compose.yaml
up resolves the depends_on graph and starts services in topological waves — services with no dependencies start first, then their dependents. Service discovery is wired automatically: container IPs are injected into each container’s /etc/hosts so services can reach each other by name (e.g. db resolves to its container IP).

​
down

Stop and remove all containers belonging to the project. 
minibox compose down [-f <file>]

minibox compose down
down sends SIGTERM to all project containers, waits for them to exit, then removes their container records and data directories. It is the inverse of up.

​
ps

List all running containers that belong to the current project. 
minibox compose ps [-f <file>]

minibox compose ps
Output shows the service name, container ID, status, health, ports, and exit code for every service in the project.

​
logs

Stream multiplexed log output from all services in the project. 
minibox compose logs [-f <file>]

minibox compose logs
Each log line is prefixed with the service name for easy identification. The stream continues until you press Ctrl+C.

​
build

Build all service images that have a build context defined, without starting any containers. 
minibox compose build [-f <file>]

minibox compose build
Useful for pre-building images (e.g. in CI) before deploying. Calls POST /containers/build for each service with a build context.

​
start

Build all service images (if build is defined) and start all containers in dependency order. 
minibox compose start [-f <file>]

minibox compose start
start behaves identically to up — it resolves the depends_on graph, builds any services with a build context, and starts all containers. Use up or start interchangeably to bring the project online.

​
stop

Stop all running containers in the project without removing them. 
minibox compose stop [-f <file>]

minibox compose stop
Sends SIGTERM to all project containers. Container records and data directories are preserved, so start can bring them back up.

​
restart

Stop and then start all services in the project. 
minibox compose restart [-f <file>]

minibox compose restart
Equivalent to compose stop followed by compose start. Useful for applying configuration changes without a full down / up cycle.

​
Typical Compose Session

1

Write your compose file

Create minibox-compose.yaml in your project root with services, build, depends_on, ports, and environment fields.
2

Start the daemon

sudo -E miniboxd
3

Build and start all services

minibox compose up
Compose builds images, resolves the service DAG, and starts containers in order.
4

Check service status

minibox compose ps
5

Stream logs

minibox compose logs
6

Stop services (keep containers)

minibox compose stop
7

Restart services

minibox compose restart
8

Tear down completely

minibox compose down
Stops containers and removes all project container records.

​
Service Discovery

When a container starts as part of a compose project, the daemon:
  1. Fetches all other running containers in the same project.
  2. Builds a hosts-file mapping service names and container IDs to their assigned IPs.
  3. Writes the mapping to rootfs/etc/hosts before the container’s PID 1 executes.
This enables seamless name resolution between services without a separate DNS server. For example, a web service can connect to db:5432 and it will resolve to the database container’s 172.19.0.x address.

​
Database Mode in Compose

Set db_mode: true on a service to apply production-safe database defaults: 
services:
  db:
    image: postgres:15
    db_mode: true
    data: /var/lib/postgresql/data
    ports:
      - "5432:5432"
This enables:
  • /dev/shm sized at 256 MB (configurable)
  • oom_score_adj of -900 (last to be OOM-killed)
  • A persistent named volume under DataRoot/volumes/ that survives orchestration cycles
  • Capability retention so the DB entrypoint can chown data directories on first boot

Build docs developers (and LLMs) love

Get started for freeTalk to us