Wiki · Zikaron

AI Agents and remote operation

An AI Agent can call the command line in a terminal, or connect straight through MCP, and carry out your everyday Zikaron work; with the app on another machine, it can do so remotely too. Each of the command line’s three ways has its own setup.

Connecting through MCP

An AI Agent that speaks MCP (the Model Context Protocol) can call the command line without a terminal.

Copy the config. In the “Terminal” group of Settings › Command line and AI control, press “Copy config” on the “Connect an AI app” row. The config names this computer’s command line by its full path, so “Enable the zikaron command” can stay as it is.
Paste it into the AI Agent. Paste the config into the AI Agent’s MCP server settings.
Set the switches as usual. For each write, with “With a credential” on it writes with the credential, and otherwise the desktop writes it (open and unlocked), so the two sections below apply as they stand; putting on chain follows “Putting on chain from the command line”, and “Send automatically” spends this identity’s gas.

Tools that write take the data folder’s full path. Through MCP an AI Agent can record, grant, revoke, add notes, delete records, export and verify record kits, put entries on chain and run the read-only checks; making keys, handing a ledger over and resending with higher fees stay on the desktop or in a terminal.

Through the desktop app

The AI Agent’s commands are carried out by your running desktop. The private keys and the passcode stay in the desktop, the AI Agent only hands over requests, and everything it does shows in the window at once.

Put it in the terminal. Turn on “Enable the zikaron command” in Settings › Command line and AI control. “Through the desktop app” under “Automation level” on the same page is on by default.
Open and unlock the desktop. Pick the identity and role at the top of the sidebar. Keep the desktop open and unlocked while the AI Agent works.
Find the data folder. Under “Details” in Settings › Local data, the “Data folder” row gives its path; give it to the AI Agent.
Choose a mode. Under “Putting on chain from the command line” in “Anchoring”, Settings › Command line and AI control: with “Send automatically” the AI Agent can see a job through from start to finish, the fee paid straight from the address; with “Queue only” the AI Agent does the writing and you confirm each payment to put entries on chain on the desktop.
Turn off auto-lock. The desktop counts idle time from your keyboard and mouse, and the AI Agent’s requests leave that count running; once it reaches the “Idle time”, the desktop locks and the channel closes. To let the AI Agent keep working, turn off “Auto-lock” in Settings › Identity key, or set a longer idle time. When the AI Agent is done, press “Lock” in the sidebar.

Hand the AI Agent this text, with your data folder path filled in:

You can operate my Zikaron with the ZIKARON command line, zikaron.
Run zikaron contract first: it lists every subcommand, its flags and the exit codes.
For anything that writes to my ledger, every command carries --home "<data folder>" and is carried out by the running desktop.
Each command prints one JSON value on standard output; the exit code gives the outcome:
  0 done; 1 refused or failed; 2 the command is wrong; 3 a partial result, or queued for me to send from the desktop; 4 no answer, such as no answer from the desktop or nodes unreachable.

The AI Agent can finish several pieces of work first and put them on chain once at the end, so they travel in one transaction for the price of one.

With a credential

With a credential for a set time that you grant on the desktop, the AI Agent writes the ledger the desktop keeps and sends its queue directly, with the desktop closed or locked, signing with the key in the desktop’s key store.

Put it in the terminal. Turn on “Enable the zikaron command” in Settings › Command line and AI control.
Grant the credential. Under “Automation level” on the same page, turn on “With a credential”, enter the passcode, set how long it lasts to the time the AI Agent will work, and press “Turn on”.
Choose a mode. “Putting on chain from the command line” in “Anchoring” on the same page, its two modes as above.
Find the ledger folder. Under “Details” in Settings › Local data, the “Data folder” row is this role’s data folder for this identity; give the AI Agent the path of the ledger folder inside it.

Hand the AI Agent this text, with that path filled in:

You can operate my Zikaron with the ZIKARON command line, zikaron.
Run zikaron contract first: it lists every subcommand, its flags and the exit codes.
Every command that writes to the ledger carries --ledger "<ledger folder>", with no --home, --key or --key-file.
Put on chain: zikaron anchor --ledger "<ledger folder>" sends this ledger's queue.
Each command prints one JSON value on standard output; the exit code gives the outcome:
  0 done; 1 refused or failed, such as an expired credential E_CREDENTIAL_EXPIRED or the desktop writing E_HOME_HELD (try again shortly); 2 the command is wrong; 3 a partial result, or queued for me to send from the desktop; 4 no answer, such as nodes unreachable or the transaction still outside a block.
When the credential has expired, tell me.

While the desktop is open, the entries the AI Agent writes show up in the window at once. When the AI Agent is done, turn off “With a credential” in Settings › Command line and AI control, and the credential is deleted.

With the command line on its own

The AI Agent writes a ledger of its own with a dedicated key, with no desktop involved. It keeps working after the machine restarts, so the whole lifecycle runs without you; add a little ETH when the address runs short. Important identities stay with the desktop; this uses a dedicated key alone.

In your own terminal, run zikaron keygen and save the private key in a file only this user can read.
Send a little ETH to the address, enough for gas.
Create the ledger folder (zikaron init) and tell the AI Agent four things: the ledger folder, the path of the key file, a node address, and the registry contract address (on Ethereum mainnet, 0x36Ea8A857a5FE813429d4D9947000C644A88809A).

Hand the AI Agent this text, with those filled in:

You can operate a dedicated Zikaron ledger with the ZIKARON command line, zikaron.
Run zikaron contract first: it lists every subcommand, its flags and the exit codes.
Every command that writes to the ledger carries --ledger "<ledger folder>" --key-file "<key file>".
Put on chain: zikaron anchor --key-file "<key file>" --endpoint 1=<node address> --form registry --registry <registry contract address> --hash <entry ID>
  --hash can repeat, so one transaction anchors several; note the entry IDs printed on writing and send a few together.
Each command prints one JSON value on standard output; the exit code gives the outcome: 0 done; 1 refused or failed; 2 the command is wrong; 3 a partial result; 4 no answer, such as nodes unreachable.
When putting on chain is refused, tell me why; if the balance is short, ask me to top it up.

The AI Agent uses this key, and what is at stake is this dedicated ledger and the ETH at its address. The ledger can join the desktop later through “Import key” and “Adopt existing ledger folder”; to write it by turns on the remote machine and on your own computer, see Handing a ledger over. How to keep the key file is under Plain files.

Remote operation

Put the app on a small computer at home or on a cloud server, and an AI Agent can work for you remotely. The command line deals with the same user on the same machine alone, so the AI Agent runs its commands on that machine: it logs in as that user over SSH, or is installed on the machine itself. Files to work on go to that machine first.

Through the desktop app: The machine needs a graphical interface: a display attached, or remote desktop. The app’s window needs OpenGL on Windows and Linux and Metal on macOS; a Windows or Linux machine without a graphics card relies on a virtual display with software rendering, so check once that the window opens. Over remote desktop you open the app, enter the passcode and turn off auto-lock, and the everyday work goes to the AI Agent. After the machine restarts or the app quits, you open it again over remote desktop and enter the passcode once more; with “Queue only”, you confirm putting entries on chain over remote desktop too.
With a credential: The graphical interface is used once, to grant the credential: over remote desktop you open the app, enter the passcode and turn on “With a credential”. After that the app can be closed; the AI Agent runs commands over SSH and keeps working across restarts until the credential expires, when you open the app over remote desktop once more.
The command line on its own: The machine needs no graphical interface, which spares unlocking and entering the passcode again after a restart; a Linux machine with no screen is enough. The AI Agent runs commands over SSH, and the key file lives on the machine.

Which machine. Through the desktop app, the master key is in memory while the desktop is unlocked; with a credential, the master key is sealed in the credential file on the machine’s disk; with the command line on its own, the private key sits in a file on the machine. A cloud provider can read a virtual machine’s memory and disk from the host underneath, so a cloud server means trusting the provider; a machine of your own at home is the safer place.

Safety

Anyone or any program that can log in to the machine as this user can have the desktop act for you, use the credential, or read the dedicated key. Allow SSH logins by key alone, and turn on full-disk encryption on the machine.
Through the desktop app with auto-lock off, remember to press “Lock” when the AI Agent is done or you step away. To confirm every payment to put entries on chain yourself, use “Queue only”.
The credential opens every identity’s data folder on this computer, and can write entries, send transactions to put them on chain and hand a ledger over to another key. Set its time to what you need and turn it off when done; a passcode change leaves it working, so take it back by turning the switch off. Whole-machine backups carry no credential.
Keep important identities with the desktop. The key the AI Agent uses on the command line on its own stands apart, with only a little ETH at its address.
Write a given ledger in one place at a time: while the remote machine writes it, use your own computer to read; to move the writing, use Handing a ledger over.
Keep whole-machine backups and copies of the key file off the machine.

PreviousCommand line NextSettings and alerts