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.

Minibox Compose lets you define, build, and run multi-container applications from a single minibox-compose.yaml file. With one command every service is created, networked, and started in the correct order — no manual sequencing required.

​
Quick Start

The example below wires a Redis store to an application container. The app service declares depends_on: [db], so Compose guarantees Redis is running before the application process starts.
1

Write minibox-compose.yaml

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

  app:
    build: .
    ports:
      - "3000:3000"
    depends_on:
      - db
    environment:
      - REDIS_HOST=db
2

Start the project

minibox compose up
Minibox builds the app image from the local MiniBox file, pulls redis:latest, resolves the dependency graph, and starts both containers.
3

Inspect and follow logs

minibox compose ps
minibox compose logs
4

Tear everything down

minibox compose down

​
Compose Subcommands

Minibox Compose exposes eight subcommands that map directly to the container lifecycle.

compose up

Builds images (when build is set), creates containers, and starts all services in dependency order. Accepts -f <file> to use an alternate compose file.

compose down

Stops and removes every container in the project. Accepts -f <file> to target a specific compose file.

compose start

Starts all services in the project. Equivalent to up — builds and starts containers in dependency order.

compose stop

Stops all running containers without removing them, preserving state for a future start.

compose restart

Restarts all services (equivalent to down followed by up).

compose build

Builds images for every service that defines a build context, without starting the containers.

compose ps

Lists containers associated with the project. Accepts -f <file> to filter by project name.

compose logs

Streams multiplexed logs from all services with color-coded, per-service name prefixes.
All subcommands default to minibox-compose.yaml in the current directory. Pass -f <path> to use any alternate file.

​
DAG Dependency Resolution

Minibox Compose builds a Directed Acyclic Graph (DAG) from the depends_on fields across all services. It then performs a topological sort to produce a safe startup sequence.
  • Services with no dependencies start in the first batch.
  • Each subsequent batch starts only after all services in the previous batch are running.
  • Circular dependencies are rejected at parse time.
# depends_on declares edges in the DAG
services:
  cache:
    image: redis:latest

  api:
    build: ./api
    depends_on:
      - cache       # cache must be running before api starts

  worker:
    build: ./worker
    depends_on:
      - api         # api must be running before worker starts
      - cache
In this example the resolved order is: cache → api → worker.

​
Automated Builds

When a service specifies a build path instead of (or alongside) an image, Compose automatically triggers POST /containers/build before running that service. The resulting image is tagged <project>-<service> for internal use. 
services:
  web:
    build: ./frontend          # triggers a build; image tagged my-project-web
    ports:
      - "8080:80"
The build value must be a directory containing a MiniBox file. The build context path must fall under an allowed prefix — see Configuration for MINIBOX_BUILD_PREFIXES.

​
Service Naming

Containers are named <project>-<service>, where project defaults to the current directory name when the name field is omitted from the compose file.
Compose fieldContainer name
name: shop + service apishop-api
(no name) + service workermydir-worker
This naming scheme feeds directly into service discovery — each service name resolves to its container’s IP inside every other container in the same project. See Service Discovery for details.

​
Architecture

The diagram below shows how the CLI orchestrator, daemon build API, and runtime backend collaborate during a compose up. The CLI is purely an HTTP client — all heavy lifting (builds, namespace setup, networking, hosts injection) happens inside miniboxd.

Build docs developers (and LLMs) love

Get started for freeTalk to us