Use
ZikaronDesk
Evidence infrastructure
Give it to an AI Agent with a cloud computer; it sets itself up.
Give it to the AI Agent on your computer; it walks you through the app, which you open once.
Needs a Mac with Apple silicon and macOS 11 or later.
Needs Windows 10 or 11 on x86_64.
Needs x86_64 Linux with glibc 2.31 or later (Ubuntu 20.04, Debian 11 and up). On other architectures, build from source.
Getting started
- Copy the promptThe button above copies all of it.
- Give it to an AI AgentOne on a cloud computer or on your own; there is a prompt for each. It follows it and gets ready to work.
- Talk with itSend a little ETH for gas to the address it gives you, then ask in plain words.
Record this contract.
purchase-contract-v3.pdfPDF · 238 KBDone: entry 12, content fingerprint 0x3fa9…c2e1. It goes on chain with your next batch.
Put today’s records on chain together.
Entries 12 to 14 went out in one transaction and are in block 26,214,903. Transaction 0x8c1e…77a0, fee 0.00041 ETH.
Grant this illustration to 0x7d2e…19b4 for commercial use, for a year.
little-tree.pngThe grant is signed and in the ledger. Pass this grant code on.
Grant codezikaron-grant:eyJhdXRob3IiOiIweDNiZTYiLCJib2R5Ijp7Imdy…Q2Rk4xR2VrM3dVc19sQ0Who holds grants for this illustration now?
Two: a commercial grant to 0x7d2e…19b4, valid until 2027-10-21; a display grant to 0x51ac…e0f3, which expired on 30 September.
The prompt in full
ZIKARON quick start (for an AI agent)
1. Fetch and install: download the latest package from the Releases of https://github.com/kaptonia/zikaron, check it against SHA256SUMS.txt, then install. On Linux: sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -o Dpkg::Options::=--force-confold ./zikaron-desk_*_amd64.deb
2. Read: README.md (networks and contract addresses) and CLI-SCHEMA.md (how to use each command). Once installed, run zikaron contract and go by the subcommands, flags and exit codes it lists.
3. Get to work:
- If the user already runs ZIKARON Desk on their own computer, prefer --home or "With a credential", so the private key stays on the user's computer.
- Otherwise: generate a key with zikaron keygen, save it in a file with mode 600 and keep it out of sight; ask the user whether they want a copy of the key file to keep; if so, hand it over as a file, never pasted into the chat, and remind them to store it offline; then create a ledger with zikaron init; ask the user to send a little ETH to the address for gas.
4. Every day: record with history --file → put on chain with anchor → check with scan, then audit; to share, export a record kit with kit-export, which the other side checks with kit-verify; to show a kit to the recipient alone, add --to-key <public key> (or --to <address> with --endpoint) to kit-export; add --originals-to <folder> to kit-verify to take out the originals. Gather several records and put them on chain together, paying gas for one transaction.
5. Upgrading: check Releases regularly. For a new version, first read the release notes and the upgrading part of CHANGELOG, check the package against SHA256SUMS.txt, then install it over the old one as in step 1. Command-line ledger folders keep working across versions. If the release notes call for a migration by hand, tell the user first and go ahead once they agree. After upgrading, run zikaron contract to see whether any command changed. At every upgrade, remind the user to download a ledger backup (pack the ledger folder into one file and hand it over), and agree with them on regular backups from then on.
6. When the user wants the safer desktop app, walk them through it step by step:
- Open the download page https://kaptonia.github.io/en/use.html, download for the user's system, check the SHA-256, then install. On a Mac, the quarantine mark comes off before the first launch; the download page has the command to copy.
- First launch: set a passcode and write the recovery words on paper, kept somewhere offline. The recovery words stay with the user alone; ask them to keep the words to themselves.
- Bring the ledger into the desktop, one of two ways:
· Hand the private key to the user, who imports it with "Import key" in the desktop app and takes the ledger in with "Adopt existing ledger folder". After adoption, the desktop writes the original folder's ledger.
· Write the ledger into a handoff file with hand-over and give it to the user, who takes it on the desktop side with take-over; from then on the ledger is written by turns in the two places.
- Then ask the user to turn on "Through the desktop app" or "With a credential" in Settings › Command line and AI control; switch to --home or the credential, and delete the private key file in the cloud afterwards.
7. Rules: the private key and the recovery words stay out of chats and logs; one place writes a ledger at a time, and to move the writing use hand-over / take-over.ZIKARON quick start (for an AI agent on the user's computer)
1. Install the app: ask whether ZIKARON Desk is on the user's computer. If not, walk them through downloading it from https://kaptonia.github.io/en/use.html#desktop, checking the SHA-256, then installing.
2. At the first launch, walk the user through these steps; after them the app can be closed and stay closed:
- Set a passcode and write the recovery words on paper, kept somewhere offline. The recovery words and the passcode stay with the user alone; ask them to keep both to themselves.
- Turn on "Enable the zikaron command" in Settings › Command line and AI control.
- Under "Automation level" on the same page, turn on "With a credential": enter the passcode, let the user choose how long it lasts ("Does not expire" is one of the choices), and press "Turn on".
- Tell you the path in the "Data folder" row under "Details" in Settings › Local data.
- Close the app.
3. Get to work: run zikaron contract and go by the subcommands, flags and exit codes it lists; the details are in the repository's CLI-SCHEMA.md. Every command that writes to the ledger carries --ledger "<the ledger folder in the data folder>", with no --key, --key-file or --home; put on chain with zikaron anchor --ledger "<the same folder>". The private key stays in the app's key store the whole time; you neither generate nor hold it.
4. Every day: record with history --file → put on chain with anchor --ledger → check with audit; to share, export a record kit with kit-export, which the other side checks with kit-verify; to show a kit to the recipient alone, add --to <address> or --to-key <public key> to kit-export; add --originals-to <folder> to kit-verify to take out the originals. Gather several records and put them on chain together, paying gas for one transaction. When the address runs short of ETH for gas, ask the user to top it up.
5. When the app needs opening again:
- E_CREDENTIAL_EXPIRED or E_CREDENTIAL_MISSING: the credential ran out or was turned off; ask the user to open the app and turn "With a credential" on again.
- A new version: remind the user to install it and upgrade by the release notes; if they call for a migration by hand, explain it first and go ahead once the user agrees.
- Whenever the app is opened for either reason, remind the user to make a whole-machine backup.
6. Rules: the private key, the passcode and the recovery words stay out of chats and logs; on E_HOME_HELD, the app is writing, so try again shortly; one place writes a ledger at a time, and to move the writing use hand-over / take-over.Keys and upgrades
- On a cloud computer, the AI Agent writes the ledger with a dedicated key; keep only enough ETH for gas at its address.
- On your own computer, the private key stays in the app’s key store and the AI Agent works with the “With a credential” credential. You choose how long it lasts; any program running as your system account can use it, so turn it off in Settings › Command line and AI control once you are done with it.
- To keep the private key on your own computer, install the and let the AI Agent work for you through “With a credential” or --home. Step 6 of the prompt has it walk you through the switch.
- When a new version comes out, the AI Agent checks and upgrades by step 5 of the prompt.
All files
Release list: SHA256SUMS.txt · Third-party licences: THIRD-PARTY-LICENSES-macos.txt
Release list: SHA256SUMS.txt · Third-party licences: THIRD-PARTY-LICENSES-windows.txt
Release list: SHA256SUMS.txt · Third-party licences: THIRD-PARTY-LICENSES-linux.txt
Install
- Check the SHA-256; it should match the value listed under Check below:
shasum -a 256 ~/Downloads/ZIKARON-0.1.5-macos-arm64.dmg - In Terminal, remove the quarantine flag macOS adds to downloads:
xattr -d com.apple.quarantine ~/Downloads/ZIKARON-0.1.5-macos-arm64.dmgDo this before you open the dmg.
- Open the dmg, drag ZIKARON.app to Applications, then open it.
If you dragged the app in first, run this instead:
xattr -dr com.apple.quarantine /Applications/ZIKARON.appThe zikaron command line is inside the app bundle: ZIKARON.app/Contents/MacOS/zikaron. To type zikaron in any terminal, turn on “Enable the zikaron command” in the app’s Settings › Command line and AI control: it places a link in /usr/local/bin, and macOS asks for an administrator password when needed.
- Check the SHA-256; it should match the value listed under Check below:
shasum -a 256 ~/Downloads/ZIKARON-0.1.5-macos-arm64.pkg - In Terminal, remove the quarantine flag macOS adds to downloads:
xattr -d com.apple.quarantine ~/Downloads/ZIKARON-0.1.5-macos-arm64.pkgDo this before you double-click it.
- Double-click the pkg to install.
The installer puts the app in /Applications and the command line at /usr/local/bin/zikaron, so zikaron works in a terminal right after installing.
Change the paths to wherever you downloaded the files.
Why this step: the app is signed with Kaptonia’s self-signed certificate and is outside Apple’s notarization. Files downloaded in a browser carry macOS’s quarantine flag, and macOS refuses to open them; on recent macOS, Open Anyway in System Settings › Privacy & Security works only some of the time. Checking the file and then removing the flag tells the system you trust the file you have checked.
To upgrade, install the new version over the old one; the machine folder and data folders of 0.1.4 and 0.1.3 carry on as they are. Upgrading from 0.1.2 or earlier, a ledger from an earlier version comes across in these steps: in the old version, “Export ledger mirror” to a folder outside the machine folder, then quit; move the old machine folder ~/.zikaron-desk.d/ aside together with the pointer file ~/.zikaron-desk; start this version, set a passcode and import the identity with the same recovery words; when the wizard reaches “Create the ledger”, press “Adopt existing ledger folder”, choose the author folder inside the mirror and press “Adopt in place”; last, run a ledger check on the Ledger page and see that it reads “OK”.
- In PowerShell, check the SHA-256; it should match the value listed under Check below:
Get-FileHash ~\Downloads\ZIKARON-0.1.5-windows-x86_64.zip -Algorithm SHA256PowerShell prints the value in capitals; compare it without regard to case.
- Unzip it to any folder and double-click zikaron-desk.exe.
There is nothing to install, and the runtime comes with the program. The command line is zikaron.exe in the same folder and runs in a terminal: hold Shift, right-click an empty spot in the folder, choose “Open in Terminal” (“Open PowerShell window here” on Windows 10), then type .\zikaron.exe with a verb and its flags. Double-clicked in Explorer, it only flashes a window.
- If the first launch shows “Windows protected your PC”, click More info, then Run anyway.
Change the paths to wherever you downloaded the files.
Why this step: the program is unsigned. On Windows 11 with Smart App Control on, unsigned programs are blocked outright, with no Run anyway and no way to allow this one program; to use it, first turn Smart App Control off under Windows Security › App & browser control › Smart App Control settings.
Local data lives in %LOCALAPPDATA%\ZIKARON\, apart from the unzipped folder. Start menu entries and desktop shortcuts are up to you; to type zikaron in any terminal, turn on “Enable the zikaron command” in the app’s Settings › Command line and AI control, which adds the command line’s folder to this user’s PATH. To upgrade, replace the old folder with the new one; the machine folder and data folders of 0.1.4 and 0.1.3 carry on as they are. Upgrading from 0.1.2 or earlier, a ledger from an earlier version comes across in these steps: in the old version, “Export ledger mirror” to a folder outside the machine folder, then quit; move the old machine folder %LOCALAPPDATA%\ZIKARON\.zikaron-desk.d\ aside together with the pointer file %LOCALAPPDATA%\ZIKARON\.zikaron-desk; start this version, set a passcode and import the identity with the same recovery words; when the wizard reaches “Create the ledger”, press “Adopt existing ledger folder”, choose the author folder inside the mirror and press “Adopt in place”; last, run a ledger check on the Ledger page and see that it reads “OK”.
- Check the SHA-256; it should match the value listed under Check below:
sha256sum ~/Downloads/zikaron-desk_0.1.5_amd64.deb - Install it:
sudo apt install ~/Downloads/zikaron-desk_0.1.5_amd64.debFor Debian, Ubuntu and their derivatives. The window program is zikaron-desk, also in the applications menu; the command line is zikaron; both go in /usr/bin, so zikaron works in a terminal right after installing.
- Check the SHA-256; it should match the value listed under Check below:
sha256sum ~/Downloads/ZIKARON-0.1.5-x86_64.AppImage - Make it executable, then run it:
chmod +x ~/Downloads/ZIKARON-0.1.5-x86_64.AppImage ~/Downloads/ZIKARON-0.1.5-x86_64.AppImageThere is nothing to install; it opens the window program. If the system lacks FUSE, add --appimage-extract-and-run to the command. The command line inside cannot be called directly; for the command line, install the .deb.
Change the paths to wherever you downloaded the files.
Neither package is signed; check them by their SHA-256. The system file dialog goes through the desktop portal, so install xdg-desktop-portal and a backend such as xdg-desktop-portal-gtk; without a portal, drag files straight into the window. Dropping files needs X11: with an X display (XWayland on a Wayland desktop included) it works as usual, and a pure Wayland session with no X display receives no dropped files.
To upgrade, install the new version; the machine folder and data folders of 0.1.4 and 0.1.3 carry on as they are. Upgrading from 0.1.2 or earlier, a ledger from an earlier version comes across in these steps: in the old version, “Export ledger mirror” to a folder outside the machine folder, then quit; move the old machine folder ~/.zikaron-desk.d/ aside together with the pointer file ~/.zikaron-desk; start this version, set a passcode and import the identity with the same recovery words; when the wizard reaches “Create the ledger”, press “Adopt existing ledger folder”, choose the author folder inside the mirror and press “Adopt in place”; last, run a ledger check on the Ledger page and see that it reads “OK”.
Other architectures or distributions: build from source; see Developer guide · Building from source.
Check
Both the app and the dmg are signed with this certificate. Once installed, check in Terminal; the Authority in the output should read Kaptonia:
codesign -dvv /Applications/ZIKARON.appCheck the pkg by its SHA-256.For more checks in the terminal, see Developer guide · Checksums.
The program is unsigned; check it by its SHA-256. The unzipped folder holds zikaron-desk.exe, zikaron.exe, LICENSE.txt and THIRD-PARTY-LICENSES.txt.For more checks in the terminal, see Developer guide · Checksums.
Neither package is signed; check them by their SHA-256. With the release list and the downloads in one folder, check them all at once:
sha256sum -c --ignore-missing SHA256SUMS.txtFor more checks in the terminal, see Developer guide · Checksums.