Get started

Your first run

The first time you open Ovillo you create a private vault with a passphrase, then a short setup card walks you through four optional steps. This page covers both, in the order the app shows them.

Create a private vault

The first screen is Create a private vault. The passphrase comes before any documents, because everything is encrypted with it before it is saved.

1. Type a passphrase in Passphrase. It must be at least 12 characters.
2. Type it again in Confirm passphrase. If the two differ you see The two passphrases do not match.
3. Read the warning: There is no password recovery. If you lose this passphrase, the vault cannot be opened.
4. Tick I understand that losing the passphrase means losing access. The button stays unavailable until you do.
5. Choose Create encrypted vault.

Twelve characters is the only rule the app checks. A longer phrase is safer: a short or common one can still be guessed by someone who copies your vault file. A few unrelated words work well and are easy to remember.

On the same screen, Restore existing backup brings a record across from another Mac (see moving to a new Mac), and each person you keep a record for has their own vault and passphrase (see People). Ovillo is also available in Spanish; use the language switch at the top of the screen.

The setup card

When the vault opens you land on the Overview with a card headed Setup · step 1 of 4, a row of four progress dots and a Skip setup button. Every step has its own Not now button, so you can do the steps in one sitting, leave some out, or skip all of it with Skip setup. Nothing is lost by skipping; every step is also available later from the normal screens. The card also appears when you open a vault that is still empty.

Step 1: Bring in your documents

The card says Drop a whole folder anywhere on this page, or choose it below: letters, lab reports and scans. You will see a plan before anything is stored.

1. Drag a folder onto the window, or choose Choose a folder on the card. (To pick single files, use Choose files in the band lower on the Overview.)
2. Ovillo reads the list of files and shows a Folder plan inside the card. Nothing has been stored yet.
3. Check the plan, then choose Bring these in, or Cancel to start again.

The plan screen

The plan lists, in plain sentences:

• Add N other documents for the assistant to review. These are the files Ovillo will keep. Open Documents for the inbox to see their names.
• Leave out N files. Open Left out to see each file with its reason, such as over 100 MB, file type not supported, duplicate of a file already included or system or hidden file.
• Only if the folder holds one: a line about importing an existing history file, and a line about attaching originals that it names.

Below the list: Every file is encrypted with your vault key before it is stored. Nothing is sent anywhere. Ovillo keeps encrypted copies; your original files are not moved or changed. The full list of what is accepted is on Documents.

After you confirm, the files are encrypted one by one (Encrypted 3 of 12 files…), reading starts on this computer and the card moves on. You can keep working while documents are read.

Step 2: Whose record is this?

Ovillo checks every document against one person's name, so a letter about someone else does not end up in this record. Once reading finds a name, the card asks These documents are for Lucía M. Is this Lucía M.'s record? (an invented name, as an example).

• Choose Yes, Lucía M. to take that name. If the documents give more than one name, you see up to three buttons, one per name.
• Choose Someone else to type the full name yourself, as it appears on the documents, and choose Save name.
• While reading is still going, the card says Reading your documents to find the name. You can type it now instead.

Once the name is saved, each new document is checked against it before anything from it is filed or sent. A document that names someone else waits for you on the Documents page. If the name is already set, this step is skipped automatically. The optional date of birth, used only to check that a document is about this person, is in Settings, not on the card.

Step 3: Connect the assistant (optional)

The card explains that the assistant reads your record and documents, answers questions with sources and suggests updates, and that Everything else works without it. You have three buttons:

• Sign in with ChatGPT: uses your own ChatGPT plan. It takes you to Settings, Assistant connection.
• Your own API key: for an OpenAI-compatible service you pay for yourself. Same place in Settings.
• Skip and use without an assistant: carries on to the last step. The default is no assistant.

There is also one optional line, In a sentence, what is happening now? (optional). Whatever you type is kept as a note in the encrypted vault so the assistant knows the situation from its first question. Once an assistant is connected, the card reads The assistant is connected and offers Continue.

Step 4: Save a backup

The card says Now that your documents are in, save a backup. Your passphrase cannot be recovered and your documents live only on this Mac, so a backup file kept somewhere else is the only way back if the Mac fails. It stays encrypted and needs the same passphrase.

• Download encrypted backup saves health-picture-encrypted-backup.json and ends setup.
• Not now ends setup without a backup. The Overview will remind you later (see the next-step card).

After setup

• Run setup again. Open Settings and choose Run setup again. It restarts the card at step 1.
• Auto-lock. A new vault locks itself after 5 minutes without activity. You can change it in Settings under Auto-lock (5, 15, 30 or 60 minutes, or never). Locking clears the open record from memory.
• Lock now. Use Lock vault in the header whenever you step away.

The main screens are Overview, Documents, Record, Review and Settings, plus the Assistant panel. Start with the Overview and Documents.

Something unclear or out of date? Tell us on GitHub.