Skip to main content
Run Moorcheh Edge on the Arduino UNO Q Debian side. Docker pulls the ARM64 image automatically. Install the CLI and Python SDK in a virtual environment to avoid Debian PEP 668 warnings and keep python3 imports working.
Embeddings: Moorcheh Edge is vector-only. Generate embeddings in your app or an upstream service first. Vectors must be exactly 1024 dimensions - see Vector requirements.

​
What you need

RequirementNotes
Arduino UNO QLinux (MPU) partition with Docker
NetworkLocal network or Wi‑Fi during board onboarding
Arduino App Lab / onboardingTo connect to the board shell (no fixed IP in this guide)
The published image moorcheh/moorcheh-edge:latest includes linux/arm64 and linux/amd64. On UNO Q, moorcheh-edge up pulls the correct architecture for you.

​
Step 1 - Connect to the board

During onboarding, connect the UNO Q to your local network, Wi‑Fi, or internet as prompted. Then in Arduino App Lab:
  1. Connect your Arduino UNO Q (USB icon in the bottom status bar).
  2. Select moorcheh-edge for that board if it is not already active.
  3. Click the terminal icon (>_) in the status bar to open the board shell.
Arduino App Lab with moorcheh-edge on Arduino UNO Q
You should land in a shell as user arduino on the board.

​
Step 2 - Create a virtual environment and install

Debian on UNO Q is externally managed (PEP 668). Use a venv so both the CLI and Python SDK live in one place: 
sudo apt-get update && sudo apt-get install -y python3-venv
python3 -m venv ~/moorcheh-venv
source ~/moorcheh-venv/bin/activate
pip install moorcheh-edge
After activate, your prompt may show (moorcheh-venv). The moorcheh-edge CLI and moorcheh_edge Python package are available in this shell.
Each time you open a new board shell, activate the venv again before running commands:
source ~/moorcheh-venv/bin/activate
When you are finished in that shell session, deactivate the venv:
deactivate
Your prompt returns to normal (no (moorcheh-venv) prefix). Deactivating does not stop the Moorcheh Edge server - the Docker container keeps running until you run moorcheh-edge down.

​
Step 3 - Start the server

moorcheh-edge up
The CLI pulls moorcheh/moorcheh-edge:latest (if needed), starts the Docker container, and creates ~/.moorcheh-edge/data. Verify the API: 
moorcheh-edge status
Expect "status": "ok" and "vector_dimension": 1024 (see Vector requirements).

​
Step 4 - Run a smoke test

Create ~/moorcheh-edge-test.py: 
nano ~/moorcheh-edge-test.py
Paste: 
#!/usr/bin/env python3
"""Smoke test for Moorcheh Edge: health → upload → search → delete."""

import random
import uuid

from moorcheh_edge.api import MoorchehEdgeApiClient

client = MoorchehEdgeApiClient(base_url="http://127.0.0.1:8080")


def rand_vec(dimension: int) -> list[float]:
    return [random.random() for _ in range(dimension)]


print("1) Health:", client.health())

health = client.health()
dimension = int(health["vector_dimension"])

suffix = uuid.uuid4().hex[:8]
ids = [f"item-{suffix}-1", f"item-{suffix}-2", f"item-{suffix}-3"]

print("2) Upload:", client.upload_vectors({
    "vectors": [{"id": item_id, "vector": rand_vec(dimension)} for item_id in ids],
}))

print("3) Search:", client.search({
    "query": rand_vec(dimension),
    "top_k": 3,
}))

print("4) Delete:", client.delete_items({"ids": [ids[1]]}))

print("5) Health:", client.health())
print("\nDone.")
The same file lives in the repo at moorcheh-edge-client/examples/moorcheh-edge-test.py. Run it (with the venv activated): 
python3 ~/moorcheh-edge-test.py
The script reads vector_dimension from /health so it stays aligned with Limits when the supported size changes.

​
External embeddings

Moorcheh Edge does not generate embeddings. Produce vectors upstream, then upload or search via the CLI or SDK.
TopicWhere to read
1024-dimensional vectors (upload and search)Vector requirements
Upload APIPOST /upload
Search APIPOST /search
Python SDKPython client

​
Troubleshooting

​
Upload fails: failed writing temp file ... moorcheh_edge_store.tmp

The container runs as a non-root user. Ensure the data directory is writable: 
moorcheh-edge down
chmod 777 ~/.moorcheh-edge/data
moorcheh-edge up

​
ModuleNotFoundError: No module named 'moorcheh_edge'

Activate the venv first: 
source ~/moorcheh-venv/bin/activate
python3 ~/moorcheh-edge-test.py

​
moorcheh-edge: command not found

Activate the venv: 
source ~/moorcheh-venv/bin/activate

​
exec format error in container logs

Pull the latest multi-arch image (see Changelog), then: 
moorcheh-edge down
moorcheh-edge up

​
Next steps