Skip to main content

​
Installation

MachinaOs runs locally with the machina CLI. For production, deploy to a cloud VM with machina deploy.

​
Prerequisites

  • Node.js 22+
  • Python 3.12+
  • uv (Python package manager)
  • Git

​
Quick Install

Install MachinaOs globally and start it:
npm install -g machina
machina start
The app will be available at:
  • Frontend: http://localhost:3000
  • Backend: http://localhost:3010
  • Node.js executor: http://localhost:3020
  • WhatsApp: http://localhost:9400
  • Temporal Web UI: http://localhost:8080
You can also run it without installing by using npx machina start.

​
CLI Commands

The machina CLI (also available as npx machina) drives every lifecycle action:
CommandDescription
machina startStart all services (production mode, clean output)
machina devStart with hot-reload for development
machina buildInstall dependencies and build for production
machina serveServe API + WebSocket + SPA on a single public port
machina stopStop all running services
machina cleanClean build artifacts
machina deployProvision a cloud VM running MachinaOs
Useful flags: --verbose / -v (full service logs), --skip-whatsapp (skip the WhatsApp service).

​
Environment Configuration

Copy the environment template: 
cp .env.template .env

​
Key Settings

​
VITE_CLIENT_PORT
number
default:"3000"
Frontend development server port
​
PYTHON_BACKEND_PORT
number
default:"3010"
Backend API server port
​
AUTH_MODE
string
default:"single"
Authentication mode: single (first user is owner) or multi (open registration)
​
REDIS_ENABLED
boolean
default:"false"
Enable Redis cache. Set to true for production.
​
VITE_ANDROID_RELAY_URL
string
WebSocket URL for remote Android device connections

​
Full Environment Example

# Ports
VITE_CLIENT_PORT=3000
PYTHON_BACKEND_PORT=3010

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

# Cache (production)
REDIS_ENABLED=false
REDIS_URL=redis://localhost:6379

# Optional API Keys
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
GOOGLE_AI_API_KEY=
GOOGLE_MAPS_API_KEY=

​
Verify Installation

  1. Open http://localhost:3000 in your browser
  2. You should see the MachinaOs workflow editor
  3. Check the backend health: curl http://localhost:3010/health
If you see the workflow canvas with the component palette, installation is complete!

​
Production Deployment

The recommended way to run MachinaOs in production is machina deploy, which provisions a login-gated cloud VM (currently Google Cloud) using your cloud CLI plus Terraform, then runs MachinaOs on a single port via machina serve under systemd: 
machina deploy up --provider gcp --owner-email you@example.com   # provision + install + print URL/creds
machina deploy status                                            # show URL + health
machina deploy destroy                                           # tear down
Docker Compose is a legacy/optional path and is no longer the recommended deployment method. If you need the container topology for reference, use machina docker:up from source.

​
Troubleshooting

Change the port in .env:
VITE_CLIENT_PORT=3001
PYTHON_BACKEND_PORT=3011
MachinaOs also uses ports 3020 (Node.js executor), 9400 (WhatsApp), 7233 (Temporal gRPC), 8080 (Temporal Web UI), and 6379 (Redis, when enabled).
The backend is managed by uv. Sync the environment from the lock file:
cd server
uv sync
This creates server/.venv against server/uv.lock. Make sure uv is installed and on your PATH first.
Stop everything cleanly, then start again with full logs:
machina stop
machina start -v
If a build looks stale, run machina clean before machina build.

​
Next Steps

Quick Start

Build your first workflow in 5 minutes