Set up Skippy
Skippy runs in Docker. There are three Compose files to choose from. Each one works on its own, so you only need the one that matches what you want.
| Setup | File | What runs | .env file |
|---|---|---|---|
| Basic | docker-compose.yml |
Skippy | Not needed |
| Voice and image text | docker-compose.simple.yml |
Skippy, Whisper, Tesseract | Not needed |
| Full | docker-compose.all.yml |
Skippy, Whisper, Tesseract, Garage | Required |
- Whisper turns voice notes into text.
- Tesseract reads the text in images, so you can search for it.
- Garage stores attachments in S3-compatible storage instead of in the Skippy volume.
Once Skippy is running, open http://localhost:8787 and create an account. From another device, use port 8787 on your server's address.
Basic
Create a folder, download the file into it, and start Skippy:
mkdir skippy && cd skippy
curl -fsSLO https://raw.githubusercontent.com/LucasGenoud/skippy/main/docker-compose.yml
docker compose -f docker-compose.yml up -d server
Notes and attachments are saved in the app_data volume. They are kept when
the container restarts or updates.
Voice and image text
This setup adds Whisper and Tesseract. Both are already connected to Skippy, so there is nothing to configure.
mkdir skippy && cd skippy
curl -fsSLO https://raw.githubusercontent.com/LucasGenoud/skippy/main/docker-compose.simple.yml
docker compose -f docker-compose.simple.yml up -d server whisper tesseract
On the first start, Skippy waits for Whisper to be ready. This can take a minute or two.
Tesseract reads English by default. To read other languages, create a .env
file next to the Compose file, for example:
OCR_LANGUAGES=fra+eng
Full
This setup adds Garage to store attachments. Notes stay in Skippy's database
in app_data; only attachments go to Garage.
-
Download the file:
mkdir skippy && cd skippy curl -fsSLO https://raw.githubusercontent.com/LucasGenoud/skippy/main/docker-compose.all.yml -
Create the Garage keys. Skippy and Garage must share the same access key and secret key, so the script writes each one twice. Run it once:
access_key="GK$(openssl rand -hex 12)" secret_key="$(openssl rand -hex 32)" cat >> .env <<EOF GARAGE_RPC_SECRET=$(openssl rand -hex 32) GARAGE_DEFAULT_ACCESS_KEY=$access_key GARAGE_DEFAULT_SECRET_KEY=$secret_key S3_ACCESS_KEY=$access_key S3_SECRET_KEY=$secret_key EOFKeep
.envprivate. It holds the keys to your attachments. -
Start the stack:
docker compose -f docker-compose.all.yml up -d server whisper tesseract garage
Garage sets itself up on the first start, including the bucket Skippy stores attachments in.
Everyday commands
Replace <file> with the Compose file you use.
| Task | Command |
|---|---|
| Update | docker compose -f <file> pull, then run your start command again |
| Stop | docker compose -f <file> down (your data is kept) |
| See the logs | docker compose -f <file> logs -f server |
Apply a change to .env |
Run your start command again |
Switch to another setup
Keep every setup in the same folder. All three files use the same app_data
volume, so your notes and account come with you.
- Stop the current setup with
docker compose -f <file> down. - Download the new file and start it as shown in its section.
Attachments do not move to or from Garage
Basic and Voice and image text store attachments in app_data. Full
stores them in Garage. Skippy does not copy files from one to the other,
so after a switch, files uploaded before it no longer open. Pick Full
before you upload files if you want Garage.
Optional settings
All three files read these settings from the .env file in the same folder.
Leave a setting out to keep its feature off, or to let each user set it up in
the app. After a change, run your start command again.
| Setting | What it does |
|---|---|
PUBLIC_URL |
The address people use to reach Skippy, such as https://notes.example.com. Set it when Skippy runs behind a reverse proxy. Password reset emails link to it. |
EMBED_URL |
Address of an OpenAI-compatible embeddings API. Turns on semantic search. None of the setups includes one. |
EMBED_MODEL |
Embedding model name. Default: bge-m3. |
EMBED_API_KEY |
Key for the embeddings API, if it needs one. |
LLM_BASE_URL, LLM_API_KEY, LLM_MODEL |
One AI provider for every user. Users cannot change it and never see the key. |
LLM_LABELING, LLM_CHAT, LLM_WRITING |
true or false. Turns automatic labeling, notes chat, or AI writing on or off in every workspace. When unset, each workspace owner decides. |
SMTP_HOST, SMTP_PORT, SMTP_SECURITY, SMTP_USERNAME, SMTP_PASSWORD, SMTP_FROM |
One mail server for every user, for email reminders and password resets. Users then only enter their own address. |
ALLOW_PRIVATE_USER_ENDPOINTS |
Lets users point their own AI, ntfy, or mail settings at hosts on your private network. Off by default. |
OCR_LANGUAGES |
Languages Tesseract reads, such as eng or fra+eng. Default: eng. Voice and image text and Full only. |
DOCS_PORT |
Port for the local copy of these docs. Default: 8123. |
Install on a device
These commands install Skippy directly from a development machine. They do not publish it to an app store. On iPhone or iPad, you can also get Skippy from the App Store.
Android
Enable USB debugging, connect the device, then run:
cd app
flutter devices
flutter run --release -d <android-device-id>
iPhone or iPad
Use macOS with Xcode, enable Developer Mode on the device, and select your
Apple signing team in app/ios/Runner.xcworkspace. Then connect the device:
cd app
flutter devices
flutter run --release -d <ios-device-id>
An app installed with a free Apple developer account needs refreshing every seven days.
AI in a workspace
Automatic labeling, notes chat, and AI note editing run on the AI provider of the workspace's owner, for everyone in the workspace. Members do not need a provider of their own, and never see the owner's key.
- Open Settings, then AI & search, and set up AI provider. Any OpenAI-compatible API works, including Ollama.
- Every workspace you own now has AI. To turn it off, or to turn off one feature, open the workspace's settings and use the switches under AI.
Only the owner can change these switches. A server can also pin a feature on
or off for every workspace with LLM_LABELING, LLM_CHAT, or
LLM_WRITING.
Connect an AI assistant
Skippy includes a Model Context Protocol (MCP) server, so an assistant such as Claude can search and read your notes and, if you allow it, create notes and add to them. It cannot delete, move, or share anything.
- In Skippy, open Settings, then Sharing & access, and choose New token under Assistant access (MCP).
- Name the token and choose Read only or Read and add.
- Copy the token. It is shown once.
For Claude Code, the dialog shows a ready command:
claude mcp add --transport http skippy https://notes.example.com/api/mcp --header "Authorization: Bearer skp_..."
Any other MCP client connects to https://<your server>/api/mcp over
Streamable HTTP with the header Authorization: Bearer <token>. Revoke a
token in the same Settings section; resetting your password revokes all of
them.
A token reaches every workspace you belong to, except one whose owner turned off Assistant access (MCP) in its settings.
Documentation site
Every Compose file can also run a local copy of these docs. Start the docs
service with the same file, for example:
docker compose -f docker-compose.simple.yml up -d docs
Then open http://localhost:8123. To use another port, set DOCS_PORT in
.env.
Advanced settings
These are not read from .env. To change one, edit the environment: section
of the service in your Compose file.
| Setting | What it does | Default |
|---|---|---|
STORAGE |
Where attachments go: disk or s3. |
disk; Full uses s3 |
S3_URL |
S3 endpoint. Required with s3. |
Full uses http://garage:3900 |
S3_REGION |
S3 region. | garage |
S3_BUCKET_PREFIX |
Attachments go in the bucket <prefix>attachments. In Full, change GARAGE_DEFAULT_BUCKET on the garage service to match. |
sticky-notes- |
WHISPER_URL |
Whisper address. Unset turns transcription off. | Unset; Voice and image text and Full use http://whisper:9000 |
OCR_URL |
Tesseract address. Unset turns image text off. | Unset; Voice and image text and Full use http://tesseract:8884 |
UNFURL_ALLOW_PRIVATE |
Allows link previews of hosts on your private network. | Off |
TELEGRAM_API |
Telegram Bot API address. | https://api.telegram.org |
ADDR |
Address the server listens on inside the container. | 0.0.0.0:8787 |
DB |
Database file. | /data/sticky_notes.db |
UPLOADS |
Attachment folder when STORAGE is disk. |
/data/uploads |
WEB |
Web app folder. | /app/web |
The whisper service uses the base speech model, set by ASR_MODEL. A
larger model such as small is more accurate but slower and uses more memory.