> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opencompany.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Frequently asked questions about MachinaOs

# Frequently Asked Questions

Common questions and troubleshooting for MachinaOs.

## General

<AccordionGroup>
  <Accordion title="What is MachinaOs?">
    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.
  </Accordion>

  <Accordion title="Is MachinaOs free to use?">
    Yes, MachinaOs is open-source and free to self-host. You only pay for external services you use (AI API calls, cloud hosting, etc.).
  </Accordion>

  <Accordion title="What's the difference between MachinaOs and n8n?">
    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.
  </Accordion>

  <Accordion title="Can I use MachinaOs commercially?">
    Yes, MachinaOs is released under an open-source license. Check the repository for specific license terms.
  </Accordion>
</AccordionGroup>

## Installation

<AccordionGroup>
  <Accordion title="What are the system requirements?">
    **Minimum:**

    * 2GB RAM
    * 2 CPU cores
    * 10GB disk space

    **Recommended:**

    * 4GB+ RAM
    * 4+ CPU cores
    * SSD storage
  </Accordion>

  <Accordion title="Can I run MachinaOs on Windows?">
    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.
  </Accordion>

  <Accordion title="How do I update MachinaOs?">
    ```bash theme={null}
    cd MachinaOs
    git pull
    npx machina clean
    npx machina start
    ```

    `machina start` auto-installs any new dependencies before launching.
  </Accordion>

  <Accordion title="Port 3000 is already in use">
    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.
  </Accordion>
</AccordionGroup>

## Workflows

<AccordionGroup>
  <Accordion title="What's the difference between Save and Deploy?">
    * **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.
  </Accordion>

  <Accordion title="Why isn't my trigger node firing?">
    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
  </Accordion>

  <Accordion title="How do I pass data between nodes?">
    Use template variables:

    ```
    {{nodeName.fieldName}}
    ```

    Example: `{{webhookTrigger.body.message}}`
  </Accordion>

  <Accordion title="Can I run multiple workflows simultaneously?">
    Yes, each deployed workflow runs independently. Multiple workflows can have triggers active at the same time.
  </Accordion>

  <Accordion title="How do I debug a workflow?">
    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
  </Accordion>
</AccordionGroup>

## AI Integration

<AccordionGroup>
  <Accordion title="Where do I add my API keys?">
    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.
  </Accordion>

  <Accordion title="Are my API keys secure?">
    Yes, API keys are:

    * Encrypted before storage
    * Stored locally in SQLite
    * Never sent to MachinaOs servers
    * Only transmitted to the respective AI providers
  </Accordion>

  <Accordion title="How does conversation memory work?">
    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.
  </Accordion>

  <Accordion title="Which AI model should I use?">
    | Use Case          | Recommended                                                |
    | ----------------- | ---------------------------------------------------------- |
    | General chat      | GPT-5.2, Claude Sonnet 4.6, Gemini 3.5 Flash               |
    | Complex reasoning | Claude Opus 4.8, GPT-5.5, o3                               |
    | Fast responses    | Claude Haiku 4.5, Gemini 3.5 Flash, Groq (Llama 3.3-70b)   |
    | Long context      | Claude Opus 4.8 (1M), GPT-5.5 (1M+), Gemini 3.5 Flash (1M) |
    | Cost-effective    | Gemini 3.5 Flash, DeepSeek V4 Flash, Groq / Cerebras       |
    | Local / private   | Ollama 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.
  </Accordion>
</AccordionGroup>

## WhatsApp

<AccordionGroup>
  <Accordion title="How do I connect 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
  </Accordion>

  <Accordion title="WhatsApp disconnects frequently">
    * 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
  </Accordion>

  <Accordion title="Can I use WhatsApp Business?">
    Yes, WhatsApp Business accounts work the same way as regular accounts.
  </Accordion>

  <Accordion title="How do I send to groups?">
    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.
  </Accordion>
</AccordionGroup>

## Android

<AccordionGroup>
  <Accordion title="How do I connect an Android device?">
    **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
  </Accordion>

  <Accordion title="ADB device not detected">
    ```bash theme={null}
    # 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.
  </Accordion>

  <Accordion title="Some actions require root access">
    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.
  </Accordion>
</AccordionGroup>

## Webhooks

<AccordionGroup>
  <Accordion title="What's my webhook URL?">
    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.
  </Accordion>

  <Accordion title="Webhook returns 404">
    * Verify the workflow is **deployed**
    * Check the path matches exactly (case-sensitive)
    * Ensure backend is running on the correct port
  </Accordion>

  <Accordion title="How do I secure my webhooks?">
    Use authentication in the Webhook Trigger node:

    * Basic auth (username/password)
    * Bearer token
    * API key header
  </Accordion>
</AccordionGroup>

## Deployment

<AccordionGroup>
  <Accordion title="What's the recommended way to deploy to the cloud?">
    The current path is the built-in `machina deploy` CLI, which provisions a login-gated VM and installs MachinaOs automatically:

    ```bash theme={null}
    npx machina deploy up --provider gcp --owner-email you@example.com
    npx machina deploy status
    npx machina deploy destroy
    ```

    This uses your cloud CLI plus Terraform to stand up a single-port server running `machina serve` under systemd, with authentication enabled and an owner credential generated at deploy time. See [Production Deployment](/deployment/production) for details. Docker Compose remains available as a legacy option (see [Docker Deployment](/deployment/docker)).
  </Accordion>

  <Accordion title="Can I run it manually without the CLI?">
    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:

    ```bash theme={null}
    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`.
  </Accordion>

  <Accordion title="How much does hosting cost?">
    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.
  </Accordion>

  <Accordion title="Where is my data stored?">
    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`.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Frontend shows blank page">
    * Check browser console for errors
    * Verify the frontend and backend are running
    * Clear browser cache
    * Check if ports are blocked by firewall
  </Accordion>

  <Accordion title="WebSocket connection fails">
    * 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`
  </Accordion>

  <Accordion title="High memory usage">
    * 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
  </Accordion>

  <Accordion title="Database locked error">
    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
  </Accordion>
</AccordionGroup>

## Getting Help

<CardGroup cols={2}>
  <Card title="GitHub Issues" icon="github" href="https://github.com/trohitg/MachinaOs/issues">
    Report bugs and request features
  </Card>

  <Card title="Documentation" icon="book" href="/introduction">
    Browse the full documentation
  </Card>
</CardGroup>