Step-by-step setup

Get OpenClone Running

Name: OpenClone
Author: OpenClone

Choose your deployment path, configure your AI, and connect the apps. Full guide for every level.

Choose your path

Run on your own machine or home server. Mac Mini, Raspberry Pi, or any device you already own. Full control, zero cost.

Clone the repo

git clone https://github.com/PixxzR/openclone
cd openclone

Configure your environment

cp backend/.env.example backend/.env
# Edit .env:
#   API_KEY=your-secure-random-key
#   AI_PROVIDER=openai
#   AI_API_KEY=your-openai-key

Start the backend

cd backend
docker compose up -d

Verify it's running

curl http://localhost:8000/api/status
# → {"status":"ok","version":"1.0.0"}

Connect the app

# In the iOS or macOS app:
# Backend URL: http://your-local-ip:8000
# API Key: (same as API_KEY in .env)

→ Install plugins

We provision a VPS in your cloud account (Hetzner, OVH). Your data, your server. We just automate the setup.

Create a VPS

# Hetzner CX22 recommended (~€5/mo)
# Ubuntu 22.04, 2 vCPU, 4 GB RAM

SSH into your server

ssh root@your-vps-ip
apt update && apt install -y docker.io docker-compose-v2 git

Clone & configure

git clone https://github.com/PixxzR/openclone
cd openclone/backend
cp .env.example .env && nano .env

Start the backend

docker compose up -d
curl localhost:8000/api/status

Expose via nginx (optional)

# Point api.yourdomain.com → localhost:8000
# Certbot for TLS: certbot --nginx -d api.yourdomain.com

→ Join Auto-VPS waitlist

We host everything for you. Test all features, then migrate your data to your own server whenever you're ready.

Join the waitlist

# Go to /waitlist and select Trial (€7)
# You'll receive credentials by email within 24h

Connect the app

# In the iOS or macOS app:
# Backend URL: https://your-id.opencloneai.com
# API Key: (provided in welcome email)

Install plugins

# macOS plugins:
# → openclone-mac-audio (system audio transcription)
# → openclone-mac-screen (screen OCR every 30s)

Migrate when ready

# Export your vault from the app settings
# Or we provision a VPS in your cloud account
# Your data is fully portable (.md files)

→ Join Trial waitlist — €7

Install the apps

Connect the macOS desktop app or iOS mobile app to your backend. Both are signed and ready to use.

✓

Signed & notarized with an Apple Developer certificate — no Gatekeeper warning, opens like any Mac app.

Download the .dmg from GitHub Releases

# https://github.com/PixxzR/openclone/releases
# → OpenClone-x.x.x.dmg

Install the app

# Open the .dmg
# Drag OpenClone.app → /Applications
# Eject the .dmg

Connect to your backend

# Launch OpenClone
# Go to Settings
# Backend URL:  http://your-server-ip:8000
# API Key:      (same as API_KEY in your .env)
# → tap Connect

Install macOS plugins (optional)

# Switch to the "macOS Plugins" tab above
# to enable audio capture and screen OCR

Homebrew (coming soon): brew install --cask openclone

✓

Distributed via TestFlight during beta. Your backend must be reachable from your phone — use Tailscale for home server access on the go.

Make your backend reachable from your phone

# Option A — Home server via Tailscale (free, recommended)
# Install Tailscale on your server + phone → done

# Option B — Public URL
# Expose port 8000 via nginx + TLS
# Point a domain like api.yourdomain.com → your server

Join the TestFlight beta

# Open this link on your iPhone:
# https://testflight.apple.com/join/openclone
# → Install OpenClone from TestFlight
# Requires iOS 16+

Connect to your backend

# Launch OpenClone
# Go to Settings
# Backend URL:  https://your-server-or-tailscale-ip:8000
# API Key:      (same as API_KEY in your .env)
# → tap Connect

Enable capture sources

# In the app → Plugins
# Enable: System Audio, Microphone, Journal
# Grant microphone permission when prompted

App Store: Coming after the beta period. TestFlight users will get early access.

macOS plugins run as LaunchAgents — they start automatically at login and send data to your backend via POST /api/v1/ingest.

Mac System Audio + Microphone

audio_system · audio_mic

Captures all system audio (apps, meetings, media) and ambient mic via ScreenCaptureKit + AVFoundation. Transcribed locally with Whisper.

cd openclone/plugins/mac-audio
./install.sh

# Prompts for:
#   Backend URL (e.g. http://localhost:8000)
#   API Key
# Installs the LaunchAgent → auto-starts at login

Mac Screen OCR

screen_ocr

Screenshots the active window every 30s. Text extracted locally via Apple Vision framework. Nothing leaves your machine unprocessed.

cd openclone/plugins/mac-screen
./install.sh

# Same prompts as mac-audio
# Requires Screen Recording permission in System Settings

To uninstall: launchctl unload ~/Library/LaunchAgents/com.opencloneai.mac-audio.plist

AI Skills

Drop a skill file into your AI tool and it knows how to search your vault, read its format, and call the API.

Claude Code

Claude Code Skill

Gives Claude Code full context about your vault structure, file format, and API. Drop it once, use it everywhere.

openclone.claude.md

# OpenClone Memory Vault

## Vault Structure
Audio/YYYY-MM-DD.md  # meetings, system audio
Screen/YYYY-MM-DD.md # screen OCR every 30s
Web/YYYY-MM-DD.md    # browsing history

## Query Examples
Grep "meeting" in Audio/
Read vault/Screen/today.md

Install path:

~/.claude/skills/openclone.claude.md

Download

Cursor

Cursor Rules

Teaches Cursor about the vault layout, file format, source types, and backend API endpoints for your project.

openclone.cursorrules

# OpenClone Memory Vault — Cursor Rules

vault/Audio/YYYY-MM-DD.md # audio transcriptions
vault/Screen/YYYY-MM-DD.md # screen OCR
vault/Web/YYYY-MM-DD.md   # web browsing

## API
POST /api/v1/ingest  # write memories
GET  /api/search?q=  # search vault
POST /api/ask/stream # AI query (SSE)

Install path:

.cursorrules (project root)

Download

Any AI

Universal Context

A ready-to-paste context block that explains your memory vault to any AI: ChatGPT, Gemini, Claude web, etc.

openclone-context.md

# My Personal Memory — OpenClone Context

My vault captures:
• Audio — meetings, conversations
• Screen — OCR of active windows
• Web — sites visited, articles read
• Journal — voice notes

Format: Source/YYYY-MM-DD.md
with ### HH:MM timestamped entries

Install path:

Paste into any AI chat

Download

Claude Code →

cp openclone.claude.md
~/.claude/skills/

Cursor →

cp openclone.cursorrules
/your/project/.cursorrules

ChatGPT / Gemini →

Paste the content of
openclone-context.md

See the apps

iOS companion app and macOS desktop app. Connect them to your backend in seconds.

Dashboard

Ask

Sources

Journal

Passive

Braindump

Watch it in action

Short demos of each key workflow — setup, capture, and querying your memory.

Video coming soon

→ videos/setup-5min.mp4

Setup ~2 min

Docker setup in 5 minutes

Clone, configure .env, docker compose up, verify running.

Video coming soon

→ videos/demo-ask-cli.mp4

CLI ~1 min

Querying memory with Claude Code CLI

Ask a question in the terminal, watch Claude search the vault and stream an answer.

Video coming soon

→ videos/demo-ios.mp4

iOS ~1.5 min

iOS companion app walkthrough

Dashboard, ask screen with live streaming, memory archive and settings.

Video coming soon

→ videos/demo-macos.mp4

macOS ~2 min

macOS desktop app overview

Dashboard with live plugins, ask screen with streaming, plugin management.

Videos to record (replace placeholders) click to expand

Record these short clips and place them in www/public/videos/. Recommended: MP4 (H.264), max 1080p, 30fps, keep clips under 2 minutes for fast loading.

setup-5min.mp4 ~90s