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

# remote-commands

> Control any Botify instance remotely via MongoDB command queue.

The Remote Command system lets you send commands to any registered Botify PC via the `botify_commands` MongoDB collection — no direct network connection to the target PC required.

***

## How It Works

<Steps>
  <Step title="Insert Command">
    A command document is inserted into the `botify_commands` MongoDB collection, targeting a specific PC by `target_pc` name.
  </Step>

  <Step title="Node Polls">
    The target Botify instance polls `botify_commands` every few seconds and finds the pending command.
  </Step>

  <Step title="Auth Verification">
    The node verifies the `auth_token` matches its `command_token`. If it doesn't match, the command is **silently rejected**.
  </Step>

  <Step title="Execution">
    The command is executed on the target PC.
  </Step>

  <Step title="Audit Log">
    Result is written to `botify_command_history`. The command document is removed from the queue.
  </Step>
</Steps>

<Warning>
  All commands require a valid `auth_token` matching the target node's `command_token`. Invalid tokens are silently rejected and logged.
</Warning>

***

## Command Reference

### Engine Control

| Command        | Action                                     | Parameters             |
| -------------- | ------------------------------------------ | ---------------------- |
| `start_247`    | Start 24/7 Alting mode                     | —                      |
| `start_normal` | Launch N alts (Normal Launch)              | `count` (default: `5`) |
| `stop`         | Stop the current engine and close all bots | —                      |
| `restart`      | Restart the Botify EXE entirely            | —                      |

### Account Management

| Command        | Action                                  | Parameters            |
| -------------- | --------------------------------------- | --------------------- |
| `kill_account` | Kill a specific running Roblox instance | `username` (required) |

### Diagnostics

| Command        | Action                                            | Response                     |
| -------------- | ------------------------------------------------- | ---------------------------- |
| `screenshot`   | Capture screen and upload to `botify_screenshots` | Base64 PNG stored in MongoDB |
| `system_stats` | Return CPU, RAM, disk, and instance stats         | JSON stats object            |

### UI Control

| Command     | Action                                                       | Parameters                          |
| ----------- | ------------------------------------------------------------ | ----------------------------------- |
| `lock`      | Disable the Botify UI on the target PC (freeze all controls) | —                                   |
| `unlock`    | Re-enable the UI after a `lock` command                      | —                                   |
| `broadcast` | Display a notification banner in the Botify app              | `message` (string), `from` (string) |

***

## Command Document Format

```json theme={null}
{
  "target_pc": "MainPC",
  "owner_id": "123456789012345678",
  "auth_token": "<32-byte-hex-token>",
  "command": "start_normal",
  "params": {
    "count": 10
  },
  "timestamp": "2026-05-20T12:00:00Z"
}
```

***

## Example Commands

<CodeGroup>
  ```json Start 24/7 Alting theme={null}
  {
    "target_pc": "MainPC",
    "owner_id": "123456789012345678",
    "auth_token": "<your_auth_token>",
    "command": "start_247"
  }
  ```

  ```json Launch 10 Normal Alts theme={null}
  {
    "target_pc": "MainPC",
    "owner_id": "123456789012345678",
    "auth_token": "<your_auth_token>",
    "command": "start_normal",
    "params": { "count": 10 }
  }
  ```

  ```json Send Broadcast Message theme={null}
  {
    "target_pc": "MainPC",
    "owner_id": "123456789012345678",
    "auth_token": "<your_auth_token>",
    "command": "broadcast",
    "params": {
      "message": "Server event starting in 5 minutes!",
      "from": "Admin"
    }
  }
  ```

  ```json Kill Specific Account theme={null}
  {
    "target_pc": "MainPC",
    "owner_id": "123456789012345678",
    "auth_token": "<your_auth_token>",
    "command": "kill_account",
    "params": { "username": "CoolAlt123" }
  }
  ```
</CodeGroup>

***

## system\_stats Response

```json theme={null}
{
  "cpu_percent": 45.2,
  "ram_total_gb": 16.0,
  "ram_used_gb": 8.3,
  "ram_percent": 51.9,
  "disk_free_gb": 120.4,
  "roblox_instances": 12,
  "roblox_total_ram_mb": 960
}
```

***

## Audit History

After execution, every command is logged in `botify_command_history`:

```json theme={null}
{
  "pc_name": "MainPC",
  "owner_id": "123456789012345678",
  "command": "start_normal",
  "params": { "count": 10 },
  "result": "success",
  "executed_at": "2026-05-20T12:00:05Z"
}
```

***

## Security

* `auth_token` is a **32-byte random hex string** generated on first run, stored in `botify_nodes`
* Commands without a matching token are **silently rejected** — no error is returned to prevent enumeration
* The `lock` command disables all UI controls on the target PC — useful for preventing interference during automated runs
* `owner_id` verification is optional but recommended for an additional layer of access control