From 062fdca59d6f3925b8c54bb87b267083fe6566d2 Mon Sep 17 00:00:00 2001
From: Valentin Haudiquet <valentin.haudiquet@canonical.com>
Date: Thu, 29 Oct 2026 21:47:14 +0100
Subject: [PATCH] docs: add a README

How to install and run the snap, and how to embed the library: one
RunOptions example covers a basic machine. The logo lives under
.github/img.
---
 .github/img/logo.svg | 46 +++++++++++++++++++++++++++++++++++++++++++
 README.md            | 47 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 93 insertions(+)
 create mode 100644 .github/img/logo.svg
 create mode 100644 README.md

diff --git a/.github/img/logo.svg b/.github/img/logo.svg
new file mode 100644
index 0000000..743e12a
--- /dev/null
+++ b/.github/img/logo.svg
@@ -0,0 +1,46 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="256" height="256" role="img">
+  <title>écrou</title>
+  <desc>A steel hex nut: rounded hexagonal body, chamfered top face, threaded hole at the center.</desc>
+  <defs>
+    <linearGradient id="side" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#5a6675"/>
+      <stop offset="1" stop-color="#2b323c"/>
+    </linearGradient>
+    <linearGradient id="top" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#9aa8b8"/>
+      <stop offset="1" stop-color="#616f7e"/>
+    </linearGradient>
+  </defs>
+
+  <!-- hex body, hole cut through -->
+  <path fill="url(#side)" fill-rule="evenodd" d="
+    M121.07 36
+    A14 14 0 0 1 134.93 36
+    L204.21 76
+    A14 14 0 0 1 204.21 88
+    L204.21 168
+    A14 14 0 0 1 204.21 180
+    L134.93 220
+    A14 14 0 0 1 121.07 220
+    L51.79 180
+    A14 14 0 0 1 51.79 168
+    L51.79 88
+    A14 14 0 0 1 51.79 76
+    Z
+    M168 128 A40 40 0 1 0 88 128 A40 40 0 1 0 168 128
+    Z"/>
+
+  <!-- chamfered top face, same hole -->
+  <path fill="url(#top)" fill-rule="evenodd" d="
+    M50 128 A78 78 0 1 0 206 128 A78 78 0 1 0 50 128
+    Z
+    M168 128 A40 40 0 1 0 88 128 A40 40 0 1 0 168 128
+    Z"/>
+
+  <!-- shadow ring where the hole meets the face -->
+  <circle cx="128" cy="128" r="43.5" fill="none" stroke="#20272f" stroke-width="5" opacity="0.45"/>
+
+  <!-- light catch along the top chamfer -->
+  <path d="M78.5 78.5 A70 70 0 0 1 177.5 78.5" fill="none"
+        stroke="#ffffff" stroke-width="7" stroke-linecap="round" opacity="0.28"/>
+</svg>
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..135249b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,47 @@
+<p align="center">
+  <img src=".github/img/logo.svg" width="150" alt="écrou logo">
+</p>
+<h1 align="center">ecrou</h1>
+<p align="center">a small microVM runtime based on <a href="https://github.com/libkrun/libkrun">libkrun</a></p>
+
+## Try ecrou in the terminal
+
+### Installation
+
+ecrou is available as a strictly confined snap:
+```
+sudo snap install ecrou
+sudo snap connect ecrou:kvm
+```
+
+### Usage
+
+```
+$ ecrou run -it ubuntu
+root@ecrou-vm-m2glhl:/# 
+```
+
+## Embed ecrou into your project
+
+ecrou is both a library and a tiny CLI frontend around it. The library is embeddable into any project, allowing to use microVMs easily.
+
+### Rust
+
+ecrou is a Rust library, which can just be called:
+```rust
+use ecrou::vm::RunOptions;
+use ecrou::NoProgress;
+
+fn main() -> ecrou::Result<std::process::ExitCode> {
+    let code = ecrou::vm::run(
+        &RunOptions {
+            image: "ubuntu:resolute".into(),
+            command: vec!["uname".into(), "-a".into()],
+            ..RunOptions::default()
+        },
+        &NoProgress,
+    )?;
+    Ok(std::process::ExitCode::from(code.clamp(0, 255) as u8))
+}
+```
+