diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..07654e3
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,26 @@
+# Folyo Server
+
+Folyo is a small server that lets AI agents control devices or VMs over WebSockets.
+Devices connect to the server, identify themselves with a device ID, and stay online as execution targets. An AI client can then call the server and ask it to list connected devices or execute shell commands on a specific device. The server acts as the bridge between agent-facing APIs and device-side WebSocket sessions.
+
+## Building
+
+Build the binary:
+
+```bash
+cargo build --release
+```
+
+Build the image:
+
+```bash
+docker build -t folyo-server .
+```
+
+## Endpoints
+
+- `GET /connect` for device WebSocket connections
+  - requires `Authorization: Bearer <token>`
+  - requires `X-Device-ID: <device-id>`
+- `POST /mcp` for MCP/JSON-RPC requests
+  - typically uses `Authorization: Bearer <token>`