---
slug: selfhost-start
title: "Self-hosted edition: your first steps after installing"
description: "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."
lang: en
---


# 31. Self-hosted edition: your first steps after installing

> **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](saving) and [Searching](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:

```bash
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.

1. **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.
2. **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.
3. **Hand over the key**: give each person their own key, preferably not by plain email. Then delete
   that person's file in `secrets/`.
4. **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:

   ```bash
   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.

1. Find the engine computer's address on the office network (for example `192.168.0.10`).
2. 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`.
3. In the firewall, allow that one port (7777 by default) for the office network only.
4. 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**

```bash
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**

```bash
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**

1. 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.
2. 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.

1. **Update check**: one request that reads `https://app.aiakiv.com/selfhost/latest.json`. It carries no
   values.
2. **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.