Self-hosted edition: your first steps after installing

Read this after installing the free self-hosted AiAkiv engine (up to 5 users). It covers saving and finding memories, asking your AI to manage the engine in plain words, adding users, teams and keys, connecting teammates on other computers, export and import, backups and new versions, what the engine sends out, and what to check when something does not work.

In short. When the install is done, restart your AI program and try "ak save". For admin work such as adding a user or exporting, ask an AI that has the admin skill, in plain words. If you prefer to do it yourself, use the aiakiv-admin command in the install folder.

This page is for after you have installed the free self-hosted AiAkiv engine (the free edition you install yourself, up to 5 active users) with the install prompt. If you have not installed it yet, sign in at https://app.aiakiv.com/selfhost and get the install prompt there.

What you have after the install

The engine: two Docker containers (the engine and its database) run on this computer. The address is http://127.0.0.1:7777/mcp (or the port you picked during the install), and it is open only inside this computer. When you restart the computer, the engine starts again once Docker is running.
The install folder: usually ~/.aiakiv/engine (Windows: $HOME\.aiakiv\engine). It holds:
- aiakiv-compose.yml and .env: the engine settings. .env holds the database password, so do not send it to anyone.
- secrets/: the key files made during the install. Give each person their own key, then delete the file.
- bundle-<version>/: guides (README.md, PREPARE.md, aiakiv-admin.md), prompts for backups and new versions (prompts/), and skills (skills/).
Your AI programs: the programs you chose during the install have an MCP server called AiAkiv-Local and the skills. You see them only after you restart that program.
Your memories live only on this computer. They are not connected to the AiAkiv cloud service. That is why backups matter (see "Backups and new versions" below).

The web console, sign-in, cards, links between teams, public memory and apps of the AiAkiv cloud service are not part of the free self-hosted edition. You manage everything with commands.

Saving and finding memories

It works the same way as the cloud service.

Save: say "ak save" in a conversation and the AI sums up the conversation and saves it. "Remember this" alone does not save.
Find: ask as usual and the AI looks up memories when it needs them. To make sure it does, say "search AiAkiv-Local for ...".
Check the connection: first, try "search AiAkiv-Local for install check". If the test memory from the install comes back, you are connected.
Where a save goes: the key decides. A key belongs to one person and one memory (their personal memory or one shared team). With several teams, each team has its own key. To use a different team in a different folder, put a settings file in that folder (the "one folder only" choice in step 9 of the install prompt). Folder settings files contain the key, so do not commit them to git.

Tips for saving and searching well are in Saving and Searching. They are written for the cloud service, but the tips are the same.

The easy way: ask your AI

If you installed the admin skill aiakiv-local-admin, ask the AI on the computer where the engine runs. It picks the right command, and before it deletes or changes anything it shows you the plan and asks.

You want to	Say
See the status	"Show me the AiAkiv engine status"
Add a person	"Add Alex as an AiAkiv user and put them in the dev team"
Make a team	"Create a planning team in AiAkiv. I am the owner"
Replace a key	"Alex lost their key. Issue a new one"
Export	"Export the AiAkiv dev team's memories to a file"
Import	"Import this file into the AiAkiv dev team"
Check for updates	"Is there a new AiAkiv version?"

If you did not install the admin skill, copy the folder bundle-<version>/skills/aiakiv-local-admin/ from the install folder into your AI program's skills folder (Claude Code: ~/.claude/skills/, Codex and Gemini CLI: ~/.agents/skills/) and restart the program.

Using the admin command yourself

The command runs inside the engine container. From the install folder, run:

docker compose -f aiakiv-compose.yml exec engine aiakiv-admin status

Below, the first part is left out and commands are written as aiakiv-admin <command>. Always put docker compose -f aiakiv-compose.yml exec engine in front of them. The command is the same in Windows PowerShell.

aiakiv-admin status: active users and the limit, teams, number of memories, database size, and whether a new version is out.
aiakiv-admin dashboard: a one-screen summary.
Commands that delete or change something only show a plan when you run them without --yes. Check the plan, then run the same command again with --yes.
Add --help to see the options. Every command is described in bundle-<version>/aiakiv-admin.md in the install folder.
A key is shown only once, when it is issued. Save the output of commands that make a key (user add, team create, team add, key issue, key reissue) to a file instead of the screen. For example: ... aiakiv-admin user add alex --json > secrets/alex-personal.json. In PowerShell, use | Out-File -Encoding utf8 <file> instead of > <file>.

Adding users

Up to 5 users can be active. A sixth one is refused.

You can also ask your AI: "Add Alex as an AiAkiv user and put them in the dev team". The AI keeps the key off the screen and saves it to a file in secrets/. To do it yourself, follow these steps.

Make the user: aiakiv-admin user add <name>. This makes the user, their personal memory, and a key for it. Names can be in any language, up to 64 characters.
Add them to a team: aiakiv-admin team add <team> <name>. This gives them a new key for that team. In the free self-hosted edition, every member can read and write all of the team's memories.
Hand over the key: give each person their own key, preferably not by plain email. Then delete that person's file in secrets/.
Connect their AI program: add an MCP server named AiAkiv-Local with the address http://<engine computer address>:7777/mcp and the header Authorization: Bearer <key>. In Claude Code:
```
claude mcp add --transport http --scope user AiAkiv-Local http://127.0.0.1:7777/mcp --header "Authorization: Bearer <key>"
```
The settings for Codex, Cursor and Gemini CLI are in step 9 of the install prompt. Copy the skills aiakiv-local-save-and-recall and aiakiv-local-graph-query for them too, so their AI saves and searches better.

Remove a person: aiakiv-admin user remove <name> --yes. All their keys stop working and you can add one more user. The memories they saved stay.
Remove them from one team only: aiakiv-admin team remove <team> <name> --yes (the owner cannot be removed).

Teammates on other computers

At first the engine is open only inside this computer (127.0.0.1). For teammates to use it from their own computers, the person who installed it opens it to the office network.

Find the engine computer's address on the office network (for example 192.168.0.10).
In the install folder's .env, change AIAKIV_BIND=127.0.0.1 to that address, then restart with docker compose -f aiakiv-compose.yml up -d.
In the firewall, allow that one port (7777 by default) for the office network only.
Teammates connect to an address like http://192.168.0.10:7777/mcp.

This connection is not encrypted. Open it only inside a network or VPN you trust. Never open it on a public internet address.

Teams and keys

Make a shared team: aiakiv-admin team create <team> --owner <name>. This makes the team and the owner's key.
Lists: aiakiv-admin team list, aiakiv-admin user list, aiakiv-admin key list (shows key ids, never the key itself).
A lost key: aiakiv-admin key reissue <key id> --yes. The old key stops working and you get a new one. Put the new key in the AI program that used the old one, then restart the program.
One more computer: aiakiv-admin key issue <name> --team <team> gives the person another key.
Stop a key: aiakiv-admin key revoke <key id> --yes.
Delete a team: aiakiv-admin team delete <team> --yes deletes the team and its memories at once. You cannot undo it, so export first.
A personal memory is called personal:<name> in commands (for example personal:alex).

Export and import

The export file (.mweft.tar.gz) has the same format in the AiAkiv cloud service, the free self-hosted edition and the paid enterprise edition. The file does not carry authors or permissions. On the receiving side, the memories belong to the person who imports them.

Asking your AI is the easiest way. Tell an AI that has the admin skill "Export the AiAkiv dev team's memories to a file" or "Import this file from my Downloads folder into the AiAkiv dev team". The AI copies the file into or out of the container, checks the import plan, and imports, step by step. Before it imports, it shows you how many memories will go in and asks. To do it yourself, use the commands below.

The commands use paths inside the container, so there is one extra step to copy the file out of the container or into it. Below, DC means docker compose -f aiakiv-compose.yml.

Export

DC exec engine aiakiv-admin export dev --to /data/exports/dev.mweft.tar.gz
DC cp engine:/data/exports/dev.mweft.tar.gz ./dev.mweft.tar.gz

Import

DC exec engine mkdir -p /data/imports
DC cp ./dev.mweft.tar.gz engine:/data/imports/dev.mweft.tar.gz
DC exec engine aiakiv-admin import /data/imports/dev.mweft.tar.gz --team dev --dry-run
DC exec engine aiakiv-admin import /data/imports/dev.mweft.tar.gz --team dev --yes

--dry-run only shows the plan (how many memories go in). After checking it, run with --yes.
Importing the same file into the same team twice skips everything the second time. You cannot import the same file into a different team.
If it stops partway, run the same command with --resume to continue.

Bringing memories from the AiAkiv cloud service

In the web console at https://app.aiakiv.com, open Export / Import, export the team and download the file. Only the team owner can do this.
Import it as shown above.

Files exported from the cloud service have no search vectors, so the engine calculates them again while importing. This takes time. On our test PC (12-core CPU), 1,000 memories took about 8.5 minutes, and the engine used up to 3.7 GB of memory meanwhile. The team's part structure, authors and hidden memories do not come along, and the import plan tells you so.

To move memories the other way, from the self-hosted edition to the cloud service, export them as shown above and import the file in the web console's Export / Import screen.

Backups and new versions

Your memories exist only on this computer. If the disk fails, you lose them all, so set up a backup first. Backups and new versions are done by pasting a prompt from the install folder into your AI.

Backup, daily backup, restore, moving to another computer: bundle-<version>/prompts/backup-restore.en.md
Installing a new version: bundle-<version>/prompts/upgrade.en.md. It backs up first and goes back to the old version if something fails. Download new versions at https://app.aiakiv.com/selfhost after signing in.

Open the file and paste everything below its "Copy from here" line into your AI chat. To see whether a new version is out, look at the new version information in aiakiv-admin status, or ask "Is there a new AiAkiv version?".

What the engine sends out

Once a day the engine sends two requests to the AiAkiv server (https://app.aiakiv.com). This is everything it sends.

Update check: one request that reads https://app.aiakiv.com/selfhost/latest.json. It carries no values.
Usage report: these five values, sent to https://app.aiakiv.com/selfhost/api/usage.

Value	What it is	Example
`install_id`	A number made at random once, the first time this install reports	a random UUID
`version`	The engine version	`0.1.0`
`edition`	The product type	`free`
`arch`	The CPU type	`amd64` or `arm64`
`active_users`	The number of active users	`3`

You can see the exact values it sends in the usage_report field of aiakiv-admin status.

To turn both off, add the line AIAKIV_UPDATE_CHECK=off to .env and restart with docker compose -f aiakiv-compose.yml up -d. The engine then sends nothing at all. Do this on a computer without internet. The engine works the same either way.

When something does not work

The AI cannot find AiAkiv-Local: check that you restarted the AI program. In Claude Code, claude mcp list should show AiAkiv-Local as connected.
The engine does not answer: check that Docker (Docker Desktop) is running, and open http://127.0.0.1:7777/health in a browser. You should see "status":"ok". If not, run docker compose -f aiakiv-compose.yml up -d in the install folder.
The key is refused (401): the key was stopped or entered wrongly. Check it with aiakiv-admin key list and, if needed, get a new one with key reissue.
A sixth user is refused: 5 users are already active. Remove someone who no longer uses it with user remove to make room.
If it still does not work, show the AI the output of docker compose -f aiakiv-compose.yml logs --tail 100 engine and ask what is wrong.