# How Genie Works

Genie is designed to feel simple, while running a full cloud environment that combines infrastructure, real-time interaction, and AI in one place.

![Welcome to Genie](https://253630326-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fy3wRNrxvvjTFreyXSBOV%2Fuploads%2Fgit-blob-5b650353359a7574da71c86edc2177fedace5d6a%2Fhow-genie-works.png?alt=media)

You do not manage setup or systems. You open Genie and everything is already connected and ready to use.

## The Simple Version

You → Browser → Genie Server (in the cloud) → Your Files/Apps

When you type a command in the browser, it is executed on your cloud server. The result is streamed back instantly to your screen. Your files are stored on that server and persist over time, so your work is always available.

In practice, it feels like using a local machine, but everything is running remotely with continuous synchronization.

***

## What This Means

There is no need to set up SSH, configure environments, or manage local dependencies. Your environment is always available, your work is saved automatically, and you can access everything from any device with a browser.

***

## The Technical Version

### Architecture

```
┌─────────────────┐
│  Your Browser   │  (Terminal, Files, Chat)
└────────┬────────┘
         │ WebSocket (secure)
         ▼
┌─────────────────┐
│  Genie Gateway  │  (Auth, Routing)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Your Server    │  (Ubuntu 22.04)
│  - Terminal
│  - Filesystem
│  - AI Agent
└─────────────────┘
```

Genie maintains a real-time connection between your browser and your server using secure WebSockets. The gateway handles authentication and routes every action to your dedicated machine. The server runs a full Linux environment where your commands, files, and AI interactions are executed.

***

## Core Components

### Terminal

Genie provides a full terminal directly in your browser using xterm.js. It supports standard shells like bash and zsh, behaves like a normal SSH session, and allows you to run any command as you would on a local machine. In advanced usage, you can open multiple terminal sessions and work across them in parallel.

### File System

Your server includes a persistent Linux filesystem. Your main workspace is located at `/home/ubuntu/workspace`, and everything you create or modify is stored there. You can install tools using familiar commands such as `apt`, `npm`, or `pip`, and your data remains intact even if the server restarts.

### AI Layer

Genie integrates AI directly into your environment. The AI understands your context, including your files, commands, and workflows. It can assist with tasks, explain issues, and execute actions on your server when permitted. This turns AI from a passive assistant into an active part of your system.

***

## Messaging Integration

Genie extends beyond the browser through Telegram and Discord. This allows you to interact with your environment without opening the application.

Once connected through settings, your messages are securely routed through the gateway to your server. The AI processes your request using your environment context and responds instantly.

Through messaging, you can check logs, ask questions, run commands, and receive alerts. This creates a continuous connection to your system, making Genie accessible from anywhere, not just within a browser session.

***

## Why This Matters

Genie brings together infrastructure, interface, and intelligence into a single system. Instead of switching between tools or managing layers separately, everything works together in real time within one environment.