Skip to main content

​
Docker (Legacy Reference)

This is a legacy reference, not the recommended path. The Docker Compose files, the docker/ directory, and the scripts/docker.js wrapper have been removed from the MachinaOs repository. This page documents the historical 4-container topology for reference and self-hosting only.The current deployment path is the built-in self-deploy CLI (machina deploy up). See Production Deployment for the supported, one-command workflow.
For local development you do not need Docker at all. Run everything with the machina CLI: npx machina dev (hot reload) or npx machina start. See Installation for the full local setup (Node.js 22+, Python 3.12+, uv).

​
Prerequisites

  • Docker 20.10+
  • Docker Compose 2.0+
  • 2GB RAM minimum

​
Historical Quick Start

The npm run docker:* scripts and the compose files below are no longer present in the repo. These commands are shown only to describe how the legacy stack was built and started.
# Clone the repository
git clone https://github.com/trohitg/MachinaOS.git
cd MachinaOs

# Build images (legacy — scripts removed)
npm run docker:build

# Start all services (legacy — scripts removed)
npm run docker:up
The legacy stack ran 4 containers:
  • frontend - React app on port 3000
  • backend - FastAPI server on port 3010
  • whatsapp - Go WhatsApp service on port 9400
  • redis - Cache on port 6379 (optional)
This container topology does not include Temporal, which the current runtime supervises in-process (gRPC on 7233, Web UI on 8080) via the pooch-downloaded temporal CLI, nor the persistent Node.js executor sidecar (port 3020) the backend now runs alongside itself.

​
Container Overview

ContainerImagePortPurpose
frontendmachinaos-frontend3000React UI (nginx)
backendmachinaos-backend3010FastAPI API server
whatsappmachinaos-whatsapp9400WhatsApp bridge
redisredis:7-alpine6379Cache (optional)

​
Configuration

​
Environment Variables

MachinaOs bootstraps its configuration from .env.template (copy it to .env and override). For the legacy container stack, the relevant variables were: 
# Ports
VITE_CLIENT_PORT=3000
PYTHON_BACKEND_PORT=3010
WHATSAPP_RPC_PORT=9400

# Authentication
AUTH_MODE=single
JWT_SECRET_KEY=your-secret-key-min-32-chars

# Cache (optional)
REDIS_ENABLED=false

# AI API keys are entered in the Credentials modal at runtime (encrypted at rest),
# not required as environment variables.
API keys for LLM providers are managed in the app’s Credentials modal and stored encrypted in a separate credentials.db. You do not set OPENAI_API_KEY / ANTHROPIC_API_KEY as environment variables.

​
Redis (Optional)

Redis is disabled by default for local development. To enable: 
# In .env
REDIS_ENABLED=true
Then start with Redis profile: 
docker-compose --profile redis up -d

​
Common Commands

# Start services
npm run docker:up

# View logs
npm run docker:logs

# Stop all services
npm run docker:down

# Rebuild after code changes
npm run docker:build && npm run docker:up

# Stop and remove volumes (clean slate)
docker-compose down -v

# View specific service logs
docker-compose logs -f backend

# Restart specific service
docker-compose restart backend

​
Accessing Services

After starting, access:
ServiceURL
Frontendhttp://localhost:3000
Backend APIhttp://localhost:3010
Health Checkhttp://localhost:3010/health
WebSocketws://localhost:3010/ws/status

​
Health Checks

All containers include health checks: 
# Check container health
docker-compose ps

# Check backend health
curl http://localhost:3010/health
Expected health response (the version field reflects the installed package version): 
{
  "status": "healthy",
  "redis_enabled": false,
  "version": "0.0.92"
}

​
Troubleshooting

Check logs for errors:
docker-compose logs backend
docker-compose logs frontend
Common issues:
  • Port already in use: Change port in .env
  • Missing environment variables: Check .env file exists
  • Verify both containers are running: docker-compose ps
  • Check network: containers should be on same network
  • Check CORS settings in backend .env
# Check WhatsApp logs
docker-compose logs whatsapp

# Restart WhatsApp service
docker-compose restart whatsapp
Clean up Docker resources:
docker system prune -af
docker builder prune -af

​
Resource Usage

Typical resource consumption:
ContainerMemoryCPU
frontend~50 MBLow
backend~150 MBMedium
whatsapp~30 MBLow
redis~10 MBLow

​
Data Persistence

Data is stored in Docker volumes:
VolumePurpose
backend-dataSQLite database, uploads
whatsapp-dataWhatsApp session
redis-dataCache data
To backup data: 
docker cp machinaos-backend-1:/app/data ./backup

​
Development Mode

For local development you do not use Docker. Run everything with the machina CLI: 
npx machina dev    # Frontend + backend with hot reload
# or
npx machina start  # Start all services
This starts the client (3000), backend (3010), the Node.js executor sidecar (3020), the WhatsApp bridge (9400), and the supervised Temporal dev server (gRPC 7233, Web UI 8080).

​
Next Steps

Production Deployment

The recommended path: one-command machina deploy up to a cloud VM

Installation

Local setup and full configuration reference