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 (11 LLM providers with memory, tools, and skills)
  • WhatsApp, Telegram, and Twitter/X 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. MachinaOs runs natively on Windows with Node.js 22+ and Python 3.12+ installed. macOS, Linux, WSL2, and Git Bash are also supported. All launch scripts are cross-platform.
cd MachinaOs
git pull
npx machina clean
npx machina start
machina start auto-installs any new dependencies before launching.
Change the port in your .env file:
VITE_CLIENT_PORT=3001
Then restart the services. Default ports: client 3000, backend 3010, Node.js executor 3020, WhatsApp 9400, Temporal gRPC 7233 + UI 8080, Redis 6379.

​
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. Use the Console tab in the bottom panel to view node execution logs
  4. Add Python Executor nodes with print() statements
  5. Check the backend Terminal tab or the server logs for errors

​
AI Integration

Click the key icon in the toolbar to open the Credentials panel. MachinaOs supports 11 LLM providers plus service credentials, including:
  • OpenAI
  • Anthropic (Claude)
  • Google AI (Gemini)
  • OpenRouter, Groq, Cerebras, DeepSeek, Kimi (Moonshot), Mistral
  • Ollama and LM Studio (local servers — enter the server URL, no cloud key needed)
  • Google Workspace, Google Maps, Twitter/X, Telegram, WhatsApp, and other services
Ollama and LM Studio point at a local server URL (for example http://localhost:11434/v1) instead of a cloud API key.
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 conversation history as editable markdown, keyed by session ID. Connect it to an AI Agent’s memory handle to enable multi-turn conversations. It keeps a rolling window of recent exchanges and can optionally archive older messages to a vector store for long-term semantic retrieval.
Use CaseRecommended
General chatGPT-5.2, Claude Sonnet 4.6, Gemini 3.5 Flash
Complex reasoningClaude Opus 4.8, GPT-5.5, o3
Fast responsesClaude Haiku 4.5, Gemini 3.5 Flash, Groq (Llama 3.3-70b)
Long contextClaude Opus 4.8 (1M), GPT-5.5 (1M+), Gemini 3.5 Flash (1M)
Cost-effectiveGemini 3.5 Flash, DeepSeek V4 Flash, Groq / Cerebras
Local / privateOllama or LM Studio (whatever model you have loaded)
Model availability changes over time — the model dropdown on each AI Model node always reflects the current supported list.

​
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. The requirements are Node.js 22+ and Python 3.12+. The backend uses uv for Python dependencies (not pip). For local development, the simplest path is:
npx machina start   # or: npx machina dev
machina start frees ports, auto-installs dependencies (uv sync for Python, npm for the frontend and Node executor), and launches everything. Environment variables bootstrap from .env.template.
MachinaOs can run on a small VM:
  • GCP e2-micro / e2-small: low single-digit dollars per month
  • AWS EC2 t3.micro / small: ~$10/month
  • Self-hosted: hardware cost only
Plus costs for AI API calls and domain/SSL.
MachinaOs keeps its state under the data directory (~/.machina/ by default): the SQLite databases (workflow.db, credentials.db, temporal.db), per-workflow workspaces, and the WhatsApp session. To back up, copy that directory while the server is stopped. API keys and OAuth tokens live encrypted in credentials.db.

​
Troubleshooting

  • Check browser console for errors
  • Verify the frontend and backend are running
  • Clear browser cache
  • Check if ports are blocked by firewall
  • Verify the backend is running (port 3010)
  • If behind a reverse proxy, check the WebSocket proxy configuration
  • Ensure no firewall blocks WebSocket traffic
  • Check CORS settings in .env
  • Restart the services: npx machina stop then npx machina start
  • Check for runaway workflows
  • Limit the conversation memory window size
  • Increase server RAM if needed
SQLite doesn’t handle concurrent writes well. If you see “database is locked”:
  • Restart the backend (npx machina stop then npx machina start)
  • On production, enable Redis (REDIS_ENABLED=true) so execution state uses Redis instead of SQLite

​
Getting Help

GitHub Issues

Report bugs and request features

Documentation

Browse the full documentation