> ## 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.

# Installation

> Set up MachinaOs on your local machine or server

# 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](https://docs.astral.sh/uv/) (Python package manager)
* Git

## Quick Install

<Tabs>
  <Tab title="Install the CLI">
    Install MachinaOs globally and start it:

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

    <Tip>
      You can also run it without installing by using `npx machina start`.
    </Tip>
  </Tab>

  <Tab title="From source">
    ```bash theme={null}
    # Clone the repository
    git clone https://github.com/zeenie-ai/MachinaOS.git
    cd MachinaOS

    # Build (installs client + server dependencies via uv)
    npm run build

    # Start all services (production mode)
    npm run start

    # Or start with hot-reload for development
    npm run dev
    ```

    Under the hood the npm scripts call the `machina` CLI (`python -m cli start` / `dev` / `build`). The backend is managed by [uv](https://docs.astral.sh/uv/) (`uv sync` against `server/uv.lock`), not pip.
  </Tab>
</Tabs>

## CLI Commands

The `machina` CLI (also available as `npx machina`) drives every lifecycle action:

| Command          | Description                                         |
| ---------------- | --------------------------------------------------- |
| `machina start`  | Start all services (production mode, clean output)  |
| `machina dev`    | Start with hot-reload for development               |
| `machina build`  | Install dependencies and build for production       |
| `machina serve`  | Serve API + WebSocket + SPA on a single public port |
| `machina stop`   | Stop all running services                           |
| `machina clean`  | Clean build artifacts                               |
| `machina deploy` | Provision a cloud VM running MachinaOs              |

Useful flags: `--verbose` / `-v` (full service logs), `--skip-whatsapp` (skip the WhatsApp service).

## Environment Configuration

Copy the environment template:

```bash theme={null}
cp .env.template .env
```

### Key Settings

<ParamField path="VITE_CLIENT_PORT" type="number" default="3000">
  Frontend development server port
</ParamField>

<ParamField path="PYTHON_BACKEND_PORT" type="number" default="3010">
  Backend API server port
</ParamField>

<ParamField path="AUTH_MODE" type="string" default="single">
  Authentication mode: `single` (first user is owner) or `multi` (open registration)
</ParamField>

<ParamField path="REDIS_ENABLED" type="boolean" default="false">
  Enable Redis cache. Set to `true` for production.
</ParamField>

<ParamField path="VITE_ANDROID_RELAY_URL" type="string">
  WebSocket URL for remote Android device connections
</ParamField>

### Full Environment Example

```bash theme={null}
# 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`

<Check>
  If you see the workflow canvas with the component palette, installation is complete!
</Check>

## 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:

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

<Info>
  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.
</Info>

## Troubleshooting

<Accordion title="Port already in use">
  Change the port in `.env`:

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

<Accordion title="Python dependencies fail">
  The backend is managed by [uv](https://docs.astral.sh/uv/). Sync the environment from the lock file:

  ```bash theme={null}
  cd server
  uv sync
  ```

  This creates `server/.venv` against `server/uv.lock`. Make sure `uv` is installed and on your PATH first.
</Accordion>

<Accordion title="Services won't start">
  Stop everything cleanly, then start again with full logs:

  ```bash theme={null}
  machina stop
  machina start -v
  ```

  If a build looks stale, run `machina clean` before `machina build`.
</Accordion>

## Next Steps

<Card title="Quick Start" icon="rocket" href="/quickstart">
  Build your first workflow in 5 minutes
</Card>