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

# Execute

> Execute a shell command or script inside the VM

Executes a shell command or script inside the VM. Use this for programmatic control of the desktop environment.

<Note>
  Replace `VM_API_IP:PORT` with the actual IP and port of the VM's Desktop Environment API server.
</Note>

## Request Body

<ParamField body="command" type="array" required>
  Command and arguments as an array. For example: `["ls", "-la", "/home/user"]`
</ParamField>

<ParamField body="shell" type="boolean" default="false">
  Whether to run the command in shell mode
</ParamField>

## Response

<ResponseField name="stdout" type="string">
  Standard output from the command
</ResponseField>

<ResponseField name="stderr" type="string">
  Standard error output from the command
</ResponseField>

<ResponseField name="exit_code" type="number">
  Exit code of the command (0 = success)
</ResponseField>

<RequestExample>
  ```bash List Files (Linux/Ubuntu) theme={null}
  curl -X POST "http://VM_API_IP:PORT/execute" \
    -H "Content-Type: application/json" \
    -d '{"command": ["ls", "-la", "/home/user"], "shell": false}'
  ```

  ```bash List Files (Windows) theme={null}
  curl -X POST "http://VM_API_IP:PORT/execute" \
    -H "Content-Type: application/json" \
    -d '{"command": ["dir", "C:\\Users"], "shell": true}'
  ```

  ```bash Open Application (macOS) theme={null}
  curl -X POST "http://VM_API_IP:PORT/execute" \
    -H "Content-Type: application/json" \
    -d '{"command": ["open", "-a", "Safari"], "shell": false}'
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "stdout": "total 48\ndrwxr-xr-x 12 user user 4096 Nov 20 10:00 .\ndrwxr-xr-x  3 root root 4096 Nov 15 08:00 ..\n-rw-r--r--  1 user user  220 Nov 15 08:00 .bash_logout\n",
    "stderr": "",
    "exit_code": 0
  }
  ```

  ```json Error Response theme={null}
  {
    "stdout": "",
    "stderr": "ls: cannot access '/nonexistent': No such file or directory",
    "exit_code": 2
  }
  ```
</ResponseExample>