OneCloud: Personal Cloud Server and API

OneCloud is a personal cloud backend that gives you real-time insights and control over your devices.

It acts as the central hub for your personal cloud, enabling system monitoring, AI-assisted queries, and remote operations — securely accessible from anywhere.

The backend leverages Flask APIs and Cloudflare Tunnel for secure access, even behind NAT or firewalls.

With OneCloud, you can:

• Monitor multiple devices in real time
• View detailed system metrics
• Capture screenshots remotely
• Perform control actions like shutdown/reboot
• Chat with an AI assistant about your system
• Keep your devices safe with token-based authentication

---

Frontend ( separate repo )

The OneCloud Backend works together with the OneCloud Frontend to give you a full dashboard experience. The frontend is a separate project and can be found here: Frontend Repo → github.com/Rhishavhere/mydesk.app

---

Architecture

OneCloud consists of:

1. Backend API (This Project) Runs on each monitored device, collecting metrics and handling control actions.

2. Frontend Dashboard A separate React/TypeScript project that consumes this API and displays a beautiful dashboard (see link above).

---

Cloudflare Tunnel Integration

Cloudflare Tunnel securely connects your devices to the internet without opening ports.

When a request is made to your domain (e.g., https://your-domain.com), Cloudflare routes it through a secure outbound-only tunnel to your API.

Benefits:

• 🔒 No open ports — safer by design
• ⚡ Simpler setup — no complex networking configs
• 📜 TLS by default — automatic HTTPS
• 🛡 DDoS Protection — Cloudflare shields your API

---

Platform-Specific Note

OneCloud supports both Windows and Linux (Fedora) environments with separate API scripts:

• Windows → api_win.py → exposes /desktop/* endpoints
• Linux (Fedora) → api_linux.py → exposes /laptop/* endpoints

Update the exposed endpoints to match your device preferences.

Simply run the script for your OS and tunnel it using Cloudflare Tunnel to your chosen public hostname. Example:

• Desktop: https://your-domain.com/desktop/system/overview
• Laptop: https://your-domain.com/laptop/system/overview

---

API Endpoints

🖥 System Information

Endpoint	Method	Description
		Quick overview: OS, hostname, uptime
		Full CPU, memory, disk, network, battery, temp
		Detailed CPU stats
		Memory + swap usage
		Disk partitions & I/O
		Interfaces, I/O, connections
		Running processes info
		Battery status
		Temperature readings
		Logged-in users
		Windows services
		Historical CPU/mem/network usage

---

🛠 System Control

Endpoint	Method	Description
		Capture current screen
		Schedule shutdown
		Schedule reboot
		Cancel shutdown/reboot
		Capture image from webcam and return as PNG

---

🎮 Remote Desktop & Input

Endpoint	Method	Description
		MJPEG video stream of the desktop
		Control mouse/keyboard actions

---

🤖 AI Integration

Endpoint	Method	Description
		Chat with your devices using Google Gemini AI

---

❤️ Health Check

Endpoint	Method	Description
		API health status

---

Endpoint Parameters

/system/processes (GET)

• limit (int) — number of processes to return (default: 20)
• sort (string) — sort by memory, cpu, name, or pid (default: memory)

Example:

GET /desktop/system/processes?limit=10&sort=cpu

---

/system/screenshot (GET)

• width (int) — resize image width before returning
• height (int) — resize image height before returning
• quality (int) — image quality (default: 95)

Example:

GET /desktop/system/screenshot?width=800&height=600&quality=80

---

/ai/chat (POST)

• query (string) — natural language question or command
• include_screenshot (bool) — if true, attaches a screenshot for AI context Body: { "query": "Describe the system status", "include_screenshot": true }

---

### `/desktop/livestream` (GET)
- `fps` *(int)* — frames per second (default: 15, max: 30)
- `quality` *(int)* — JPEG quality 1-100 (default: 70)
- `scale` *(float)* — resolution scale 0.1-1.0 (default: 0.5)
- `cursor` *(string)* — `crosshair`, `simple`, or `none`

**Example:**
```bash
https://your-domain.com/desktop/livestream?fps=20&quality=80&scale=0.75

---

/desktop/mapping (POST)

Control the mouse remotely. Requires Authorization header.

Body (Move):

{
  "action": "move",
  "x": 0.5,     // 0.0 to 1.0 (normalized)
  "y": 0.5,
  "normalized": true
}

Body (Click/Tap):

{
  "action": "tap", // or 'doubletap', 'rightclick'
  "x": 0.5,
  "y": 0.5
}

Body (Scroll):

{
  "action": "scroll",
  "delta": 200 // positive = up, negative = down
}

Setup

Prerequisites

• Python 3.8+
• Cloudflare account + cloudflared tunnel
• Cloudflare account + cloudflared tunnel
• Google Gemini API key
• (mss is recommended for faster screen capture, installed via requirements)

Install & Run

# Create venv & install deps
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Create .env
echo "GEMINI_API_KEY=your_gemini_key" >> .env
echo "CONTROL_TOKEN=your_secure_token" >> .env

# Start API
python api_win.py   # for Windows
# or
python api_linux.py # for Linux (Fedora)

---

Expose API via Cloudflare Tunnel

1. Install Cloudflare Tunnel CLI (cloudflared): Installation Guide → Cloudflare Docs

2. Authenticate with Cloudflare:

cloudflared login

3. Create a tunnel (replace <YOUR_TUNNEL_NAME> with a name you choose):

cloudflared tunnel create <YOUR_TUNNEL_NAME>

4. Configure the tunnel by creating ~/.cloudflared/config.yml:

tunnel: <YOUR_TUNNEL_UUID>
credentials-file: /home/user/.cloudflared/<YOUR_TUNNEL_UUID>.json

# Change hostname to your Cloudflare domain/subdomain
hostname: your-domain.com
service: http://localhost:5000

5. Run the tunnel:

cloudflared tunnel run <YOUR_TUNNEL_NAME>

---

Once the tunnel is running, your API will be available at:

• Desktop: https://your-domain.com/desktop/*
• Laptop: https://your-domain.com/laptop/*

---

Security Tips

• Use strong, unique tokens in .env
• Always access via HTTPS (Cloudflare provides this)
• Keep dependencies updated

---