Skip to main content

​
Frequently Asked Questions

Common questions and troubleshooting for MachinaOs.

​
General

MachinaOs is an open-source workflow automation platform inspired by n8n. It lets you create visual workflows that connect AI models, messaging services, devices, and APIs using a drag-and-drop interface.
Yes, MachinaOs is open-source and free to self-host. You only pay for external services you use (AI API calls, cloud hosting, etc.).
MachinaOs is inspired by n8n’s node-based approach but focuses on:
  • Deep AI integration (OpenAI, Claude, Gemini with memory)
  • WhatsApp automation
  • Android device control
  • Real-time WebSocket communication
MachinaOs is built with React and Python, while n8n uses Node.js.
Yes, MachinaOs is released under an open-source license. Check the repository for specific license terms.

​
Installation

Minimum:
  • 2GB RAM
  • 2 CPU cores
  • 10GB disk space
Recommended:
  • 4GB+ RAM
  • 4+ CPU cores
  • SSD storage
Yes, using Docker Desktop for Windows or WSL2. Native development is also supported with Node.js and Python installed.
cd MachinaOs
git pull
docker-compose down
docker-compose up --build -d
Change the port in your .env file:
VITE_CLIENT_PORT=3001
Then restart the services.

​
Workflows

  • Save: Persists your workflow to the database. The workflow is not running.
  • Deploy: Activates triggers and starts listening for events. Required for cron schedules, webhooks, and message triggers.
  1. Make sure the workflow is deployed (not just saved)
  2. Check if filters are too restrictive
  3. Verify external services are connected (WhatsApp, Android)
  4. Check backend logs for errors
Use template variables:
{{nodeName.fieldName}}
Example: {{webhookTrigger.body.message}}
Yes, each deployed workflow runs independently. Multiple workflows can have triggers active at the same time.
  1. Use the Run button on individual nodes to test them
  2. Check the output panel for node results
  3. Add Python Executor nodes with print() statements
  4. Check backend logs: docker-compose logs -f backend

​
AI Integration

Click the key icon in the toolbar to open the Credentials panel. Add keys for:
  • OpenAI
  • Anthropic (Claude)
  • Google AI (Gemini)
  • Google Maps
  • Android Remote
Yes, API keys are:
  • Encrypted before storage
  • Stored locally in SQLite
  • Never sent to MachinaOs servers
  • Only transmitted to the respective AI providers
The Simple Memory node stores messages in SQLite by session ID. Connect it to an AI Agent’s memory handle (diamond shape) to enable multi-turn conversations.
Use CaseRecommended
General chatGPT-4o, Claude 3.5 Sonnet
Complex reasoningClaude 3 Opus, GPT-4 Turbo
Fast responsesGPT-3.5 Turbo, Claude Haiku
Long contextGemini 1.5 Pro
Cost-effectiveGPT-3.5 Turbo

​
WhatsApp

  1. Click the WhatsApp/Android icon in the toolbar
  2. A QR code appears
  3. Open WhatsApp on your phone
  4. Go to Settings > Linked Devices > Link a Device
  5. Scan the QR code
  • Ensure your phone has stable internet
  • Don’t use WhatsApp Web simultaneously
  • Keep the MachinaOs server running continuously
  • Check if you’re logged out on your phone
Yes, WhatsApp Business accounts work the same way as regular accounts.
Use the group’s JID (ends with @g.us) as the recipient. The WhatsApp Receive node provides group_info.group_jid for incoming group messages.

​
Android

Local (USB):
  1. Enable Developer Options and USB Debugging on your phone
  2. Connect via USB
  3. Run adb devices to verify
  4. Select device in Android Device Setup node
Remote:
  1. Configure relay URL in .env
  2. Add API key in Credentials
  3. Install companion app on device
  4. Scan QR code to pair
# Check connection
adb devices

# Restart ADB
adb kill-server
adb start-server

# Try different USB cable/port
Also ensure USB debugging is enabled in Developer Options.
Some Android automation features require root or special permissions:
  • Airplane mode toggle
  • Some system settings
  • Protected app access
Use automation apps like Tasker for restricted features.

​
Webhooks

Local: http://localhost:3010/webhook/{path} Production: https://your-domain.com/webhook/{path}Replace {path} with the path you set in the Webhook Trigger node.
  • Verify the workflow is deployed
  • Check the path matches exactly (case-sensitive)
  • Ensure backend is running on the correct port
Use authentication in the Webhook Trigger node:
  • Basic auth (username/password)
  • Bearer token
  • API key header

​
Deployment

Yes, but it’s more complex:
  1. Install Node.js 18+ and Python 3.12+
  2. Install dependencies: npm install and pip install -r requirements.txt
  3. Build frontend: npm run build
  4. Run backend: uvicorn main:app
  5. Serve frontend with nginx
Docker is recommended for easier deployment.
MachinaOs can run on a small VPS:
  • DigitalOcean: ~$6/month (1GB RAM)
  • AWS EC2: ~$10/month (t3.micro)
  • Self-hosted: Hardware cost only
Plus costs for AI API calls and domain/SSL.
# Backup SQLite database
docker cp machinaos-backend-1:/app/data ./backup/

# Backup WhatsApp session
docker cp machinaos-whatsapp-1:/app/data ./backup/whatsapp/

​
Troubleshooting

  • Check browser console for errors
  • Verify frontend container is running
  • Clear browser cache
  • Check if ports are blocked by firewall
  • Verify backend is running
  • Check nginx WebSocket proxy configuration
  • Ensure no firewall blocks WebSocket (port 3010)
  • Check CORS settings in .env
  • Restart containers: docker-compose restart
  • Check for runaway workflows
  • Limit conversation memory window size
  • Increase server RAM if needed
SQLite doesn’t handle concurrent writes well. If you see “database is locked”:
  • Restart backend container
  • Consider migrating to PostgreSQL for production

​
Getting Help

GitHub Issues

Report bugs and request features

Documentation

Browse the full documentation