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.

This guide walks you through building and running your first container with MiniBox. You will install the minibox CLI and miniboxd daemon, write a MiniBox file for a Node.js application, build an OCI image, and run it as an isolated container.
MiniBox requires Linux. The daemon (miniboxd) must run as root for networking and overlayfs mounts. Test in a VM before deploying to shared machines.

​
Prerequisites

  • Linux (kernel 5.11+ recommended for cgroups v2)
  • Go 1.21+ (only needed if building from source)
  • Root or sudo access
1

Install MiniBox

Clone the repository and install the binaries to ~/.local/bin:
git clone https://github.com/chaitu426/minibox.git
cd minibox
make install-user
export PATH="$HOME/.local/bin:$PATH"
To install system-wide to /usr/local/bin, run make install-system instead.
2

Start the daemon

The daemon manages images, containers, and networking. Start it with root privileges:
sudo -E miniboxd
Verify connectivity in a second terminal:
minibox ping
# Daemon is running
3

Write a MiniBox file

Create a project directory with a simple Node.js app:
mkdir myapp && cd myapp
Create index.js:
index.js
const http = require('http');
const port = process.env.PORT || 3000;
http.createServer((req, res) => {
  res.end('Hello from MiniBox!\n');
}).listen(port, () => console.log(`Listening on ${port}`));
Create package.json:
package.json
{ "name": "myapp", "version": "1.0.0", "main": "index.js" }
Create the MiniBox file:
MiniBox
BASE alpine

BLOCK runtime
    pkg nodejs
    pkg npm

BLOCK source
    workdir /app
    copy . /app

BLOCK deps
    NEED runtime
    NEED source
    auto-deps

BLOCK config
    NEED deps
    env PORT=3000
    env NODE_ENV=production
    port 3000

START node index.js
4

Build the image

From your project directory, build and tag the image:
minibox build -t myapp .
You will see DAG build logs showing blocks executing in parallel waves:
[build] START tag=myapp
[dag] wave=1 ready=runtime,source
[block] DONE runtime
[block] DONE source
[dag] wave=2 ready=deps
[block] DONE deps
[dag] wave=3 ready=config
[block] DONE config
[build] DONE tag=myapp
Verify the image:
minibox images
5

Run the container

Start the container in detached mode with port mapping:
minibox run -d -p 3001:3000 myapp
# a1b2c3d4
Test the application:
curl http://localhost:3001
# Hello from MiniBox!
Stop and clean up:
minibox stop a1b2c3d4
minibox rm a1b2c3d4

​
Next Steps

MiniBox File Format

Learn all directives: BASE, BLOCK, NEED, BNEED, RUN, COPY, AUTO-DEPS.

Compose Orchestration

Run multi-container apps with minibox-compose.yaml.

Build docs developers (and LLMs) love

Get started for freeTalk to us