---
slug: selfhost-start
title: "자체 설치판: 설치한 뒤 처음 할 일"
description: "AiAkiv 무료 자체 설치판(사용자 5명까지)을 설치한 뒤 읽는 안내입니다. 기억을 저장하고 찾는 법, AI 에게 말로 관리를 부탁하는 법, 사용자와 팀과 키를 더하는 법, 다른 컴퓨터의 팀원을 연결하는 법, 내보내기와 가져오기, 백업과 새 버전, 엔진이 밖으로 보내는 것, 막혔을 때 볼 것을 한곳에 모았습니다."
lang: ko
---


# 31. 자체 설치판: 설치한 뒤 처음 할 일

> **한 줄 요약.** 설치가 끝났으면 AI 프로그램을 다시 시작하고 "ak save" 로 저장해 보세요.
> 사용자 추가, 내보내기 같은 관리는 관리 스킬을 설치한 AI 에게 말로 부탁하면 됩니다.
> 직접 하고 싶으면 설치 폴더에서 `aiakiv-admin` 명령을 씁니다.

이 문서는 AiAkiv 무료 자체 설치판(직접 설치하는 무료판, 활성 사용자 5명까지)을 설치 프롬프트로
설치한 다음에 읽는 안내입니다. 아직 설치하지 않았다면 https://app.aiakiv.com/selfhost 에서
로그인한 뒤 설치 프롬프트를 받으세요.

## 설치가 끝나면 생기는 것

- **엔진**: Docker 컨테이너 두 개(엔진과 데이터베이스)가 이 컴퓨터에서 돕니다. 주소는
  `http://127.0.0.1:7777/mcp` 이고(설치 때 다른 포트를 골랐으면 그 번호), 이 컴퓨터 안에서만
  열립니다. 컴퓨터를 다시 켜도 Docker 가 켜지면 엔진도 다시 뜹니다.
- **설치 폴더**: 보통 `~/.aiakiv/engine`(Windows 는 `$HOME\.aiakiv\engine`)입니다. 안에 이런 것이
  있습니다.
  - `aiakiv-compose.yml` 과 `.env`: 엔진 설정입니다. `.env` 에는 데이터베이스 비밀번호가 들어
    있으니 남에게 보내지 마세요.
  - `secrets/`: 설치 때 만든 키 파일입니다. 사람마다 자기 키를 전한 뒤 지우세요.
  - `bundle-<버전>/`: 안내 문서(`README.md`, `PREPARE.md`, `aiakiv-admin.md`), 백업과 새 버전용
    프롬프트(`prompts/`), 스킬(`skills/`)이 있습니다.
- **AI 프로그램 연결**: 설치 때 고른 프로그램에 `AiAkiv-Local` 이라는 MCP 서버와 스킬이
  들어가 있습니다. 새 서버와 스킬은 그 프로그램을 다시 시작해야 보입니다.
- **기억은 이 컴퓨터에만 있습니다.** AiAkiv 클라우드와 이어져 있지 않습니다. 그래서 백업이
  중요합니다(아래 "백업과 새 버전").

AiAkiv 클라우드에 있는 웹 콘솔, 로그인, 카드, 팀 간 링크, 공개 기억, 앱은 무료 자체 설치판에
없습니다. 관리는 모두 명령으로 합니다.

## 기억 저장하고 찾기

쓰는 방법은 클라우드와 같습니다.

- **저장**: 대화 중에 "ak save" 라고 하면 AI 가 지금까지의 내용을 정리해 저장합니다. "이것
  기억해 줘" 만으로는 저장하지 않습니다.
- **찾기**: 평소처럼 물으면 AI 가 필요할 때 기억을 찾아 씁니다. 꼭 찾게 하려면 "AiAkiv-Local
  에서 ○○ 를 찾아 줘" 라고 하세요.
- **연결 확인**: 처음에는 "AiAkiv-Local 에서 install check 를 검색해 줘" 라고 해 보세요. 설치 때
  남긴 시험 기억이 나오면 연결된 것입니다.
- **어느 기억에 저장되나**: 키가 정합니다. 키는 사람 한 명과 기억 하나(개인 기억 또는 공유 팀)에
  묶여 있습니다. 팀이 여럿이면 팀마다 키가 다르고, 폴더마다 다른 팀을 쓰려면 그 폴더에 설정 파일을
  둡니다(설치 프롬프트 9단계에서 "한 폴더만" 을 고른 경우). 폴더 설정 파일에는 키가 들어 있으니
  git 에 올리지 마세요.

저장과 검색을 잘 쓰는 요령은 [저장하기](saving)와 [찾기](searching)에 있습니다. 클라우드 기준
문서지만 요령은 같습니다.

## 가장 쉬운 방법: AI 에게 말로 부탁하기

설치 때 관리 스킬 `aiakiv-local-admin` 을 설치했다면, 엔진을 설치한 컴퓨터의 AI 에게 말로
부탁하면 됩니다. AI 가 알맞은 명령을 고르고, 지우거나 바꾸는 일은 먼저 계획을 보여 주고 묻습니다.

| 하고 싶은 일 | 이렇게 말하세요 |
|---|---|
| 상태 보기 | "AiAkiv 엔진 상태 알려 줘" |
| 사람 더하기 | "AiAkiv 에 민수를 사용자로 추가하고 개발팀에 넣어 줘" |
| 팀 만들기 | "AiAkiv 에 기획팀을 만들어 줘. 소유자는 나야" |
| 키 다시 받기 | "민수가 키를 잃어버렸어. 다시 발급해 줘" |
| 내보내기 | "AiAkiv 개발팀 기억을 파일로 내보내 줘" |
| 가져오기 | "이 파일을 AiAkiv 개발팀으로 가져와 줘" |
| 새 버전 확인 | "AiAkiv 새 버전 나왔어?" |

관리 스킬을 설치하지 않았다면 설치 폴더의 `bundle-<버전>/skills/aiakiv-local-admin/` 폴더를 AI
프로그램의 스킬 폴더(Claude Code 는 `~/.claude/skills/`, Codex 와 Gemini CLI 는
`~/.agents/skills/`)에 복사하고 프로그램을 다시 시작하세요.

## 관리 명령 직접 쓰기

명령은 엔진 컨테이너 안에서 돕니다. 설치 폴더에서 이렇게 부릅니다.

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

아래에서는 앞부분을 줄여 `aiakiv-admin <명령>` 으로 적습니다. 실제로는 늘 앞에
`docker compose -f aiakiv-compose.yml exec engine` 을 붙입니다. Windows 의 PowerShell 에서도 같은
명령입니다.

- `aiakiv-admin status`: 사용자 수와 한도, 팀, 기억 수, 데이터베이스 크기, 새 버전 정보를 봅니다.
- `aiakiv-admin dashboard`: 한 화면 요약입니다.
- 지우거나 바꾸는 명령은 `--yes` 없이 돌리면 계획만 보여 주고 아무것도 바꾸지 않습니다. 계획을
  확인한 뒤 같은 명령에 `--yes` 를 붙여 다시 돌리세요.
- 인자가 궁금하면 `--help` 를 붙이세요. 명령 하나하나의 설명은 설치 폴더의
  `bundle-<버전>/aiakiv-admin.md` 에 있습니다.
- **키는 발급할 때 딱 한 번 나옵니다.** 키를 만드는 명령(`user add`, `team create`, `team add`,
  `key issue`, `key reissue`)의 결과는 화면 대신 파일에 받아 두세요. 예:
  `... aiakiv-admin user add 민수 --json > secrets/민수-personal.json`. PowerShell 은
  `> 파일` 대신 `| Out-File -Encoding utf8 파일` 을 씁니다.

## 사용자 더하기

활성 사용자는 5명까지입니다. 여섯째 사용자는 거절됩니다.

사람을 더하는 일도 AI 에게 "AiAkiv 에 민수를 사용자로 추가하고 개발팀에 넣어 줘" 라고 시키면
됩니다. AI 가 키를 화면에 내지 않고 `secrets/` 폴더의 파일로 받아 둡니다. 직접 하려면 아래 순서대로
합니다.

1. **사용자 만들기**: `aiakiv-admin user add <이름>`. 사용자와 그 사람의 개인 기억, 개인 기억의
   키가 생깁니다. 이름은 어느 언어든 되고 64자까지입니다.
2. **팀에 넣기**: `aiakiv-admin team add <팀> <이름>`. 그 팀의 키가 새로 나옵니다. 무료
   자체 설치판에서는 팀원 모두가 팀의 기억을 모두 읽고 씁니다.
3. **키 전하기**: 키는 사람마다 따로, 가능하면 평문 메일이 아닌 방법으로 전하세요. 전한 뒤
   `secrets/` 의 그 사람 파일은 지우세요.
4. **그 사람의 AI 프로그램 연결**: 서버 이름 `AiAkiv-Local`, 주소 `http://<엔진 컴퓨터 주소>:7777/mcp`,
   머리글 `Authorization: Bearer <키>` 로 MCP 서버를 더합니다. Claude Code 라면:

   ```bash
   claude mcp add --transport http --scope user AiAkiv-Local http://127.0.0.1:7777/mcp --header "Authorization: Bearer <키>"
   ```

   Codex, Cursor, Gemini CLI 의 설정 모양은 설치 프롬프트 9단계에 있습니다. 스킬
   `aiakiv-local-save-and-recall` 과 `aiakiv-local-graph-query` 도 같이 복사해 주면 그 사람의 AI 가
   저장과 검색을 더 잘합니다.

- **사람 빼기**: `aiakiv-admin user remove <이름> --yes`. 그 사람의 키가 모두 막히고 사용자를 한 명
  더 넣을 수 있게 됩니다. 그 사람이 저장한 기억은 남습니다.
- **팀에서만 빼기**: `aiakiv-admin team remove <팀> <이름> --yes`(소유자는 뺄 수 없습니다).

### 다른 컴퓨터의 팀원이 쓰려면

엔진은 처음에 이 컴퓨터 안(`127.0.0.1`)에서만 열립니다. 팀원이 자기 컴퓨터에서 쓰려면 설치한
사람이 엔진을 사내망에 열어야 합니다.

1. 엔진 컴퓨터의 사내망 주소(예: `192.168.0.10`)를 확인합니다.
2. 설치 폴더의 `.env` 에서 `AIAKIV_BIND=127.0.0.1` 을 그 주소로 바꾸고,
   `docker compose -f aiakiv-compose.yml up -d` 로 다시 띄웁니다.
3. 방화벽에서 그 포트(기본 7777) 하나를 사내망에만 허용합니다.
4. 팀원은 주소를 `http://192.168.0.10:7777/mcp` 처럼 바꿔 연결합니다.

이 연결은 암호화되지 않습니다. **믿을 수 있는 사내망이나 VPN 안에서만** 여세요. 공인 인터넷
주소에는 열지 마세요.

## 팀과 키

- **공유 팀 만들기**: `aiakiv-admin team create <팀> --owner <이름>`. 팀과 소유자의 키가 생깁니다.
- **목록**: `aiakiv-admin team list`, `aiakiv-admin user list`, `aiakiv-admin key list`(키 값은 나오지
  않고 키 id 만 나옵니다).
- **키를 잃었을 때**: `aiakiv-admin key reissue <키 id> --yes`. 옛 키는 막히고 새 키가 나옵니다. 그
  키를 쓰던 AI 프로그램 설정을 새 키로 바꾸고 프로그램을 다시 시작하세요.
- **컴퓨터를 하나 더 쓸 때**: `aiakiv-admin key issue <이름> --team <팀>` 으로 키를 하나 더 받습니다.
- **키 막기**: `aiakiv-admin key revoke <키 id> --yes`.
- **팀 지우기**: `aiakiv-admin team delete <팀> --yes` 는 팀과 기억을 바로 지웁니다. 되돌릴 수
  없으니 먼저 내보내기를 해 두세요.
- 개인 기억은 명령에서 `personal:<이름>` 으로 부릅니다(예: `personal:민수`).

## 내보내기와 가져오기

내보내기 파일(`.mweft.tar.gz`)은 AiAkiv 클라우드, 무료 자체 설치판, 유료 기업판이 같은 형식을
씁니다. 파일에는 작성자와 권한이 들어가지 않습니다. 받는 쪽에서는 가져오는 사람의 기억으로
들어갑니다.

**AI 에게 시키는 것이 가장 쉽습니다.** 관리 스킬을 설치한 AI 에게 "AiAkiv 개발팀 기억을 파일로
내보내 줘", "다운로드 폴더의 이 파일을 AiAkiv 개발팀으로 가져와 줘" 라고 하면 파일을 컨테이너에
넣고 꺼내는 일, 가져올 계획 확인, 실제로 넣기까지 AI 가 차례로 합니다. 넣기 전에 몇 건이 들어가는지
보여 주고 묻습니다. 직접 하려면 아래 명령을 씁니다.

명령은 컨테이너 안의 경로를 쓰므로, 파일을 컨테이너 밖으로 꺼내거나 안으로 넣는 일이 한 번 더
있습니다. 아래 `DC` 는 `docker compose -f aiakiv-compose.yml` 입니다.

**내보내기**

```bash
DC exec engine aiakiv-admin export 개발팀 --to /data/exports/dev.mweft.tar.gz
DC cp engine:/data/exports/dev.mweft.tar.gz ./dev.mweft.tar.gz
```

**가져오기**

```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 개발팀 --dry-run
DC exec engine aiakiv-admin import /data/imports/dev.mweft.tar.gz --team 개발팀 --yes
```

- `--dry-run` 은 몇 건이 들어가는지 계획만 보여 줍니다. 확인한 뒤 `--yes` 로 실제로 넣습니다.
- 같은 파일을 같은 팀에 두 번 넣어도 두 번째는 모두 건너뜁니다. 같은 파일을 다른 팀에 넣을 수는
  없습니다.
- 중간에 끊기면 같은 명령에 `--resume` 을 붙여 이어서 합니다.

**AiAkiv 클라우드의 기억을 가져올 때**

1. https://app.aiakiv.com 웹 콘솔의 Export / Import 화면에서 팀을 내보내고 파일을 내려받습니다.
   팀 소유자만 할 수 있습니다.
2. 위 "가져오기" 대로 넣습니다.

클라우드에서 내보낸 파일에는 검색에 쓰는 벡터가 없어서, 엔진이 가져오면서 벡터를 다시 계산합니다.
시간이 걸립니다. 저희 시험 PC(12코어 CPU)에서 기억 1,000건에 약 8분 반이 걸렸고, 그동안 엔진의
메모리가 3.7GB 까지 올라갔습니다. 팀의 파트 구조, 작성자, 숨긴 기억은 들어오지 않으며 가져오기
계획이 그 사실을 알려 줍니다.

거꾸로 자체 설치판의 기억을 클라우드로 옮길 때는 위 "내보내기" 로 만든 파일을 웹 콘솔의 Export /
Import 화면에서 가져옵니다.

## 백업과 새 버전

기억은 이 컴퓨터에만 있습니다. 디스크가 고장 나면 모두 잃으니, 설치가 끝나면 먼저 백업을
준비하세요. 백업과 새 버전 설치는 설치 폴더의 프롬프트를 AI 에게 붙여 넣어 합니다.

- **백업, 매일 백업, 되살리기, 다른 컴퓨터로 옮기기**:
  `bundle-<버전>/prompts/backup-restore.ko.md`
- **새 버전 설치**: `bundle-<버전>/prompts/upgrade.ko.md`. 먼저 백업하고, 실패하면 이전 버전으로
  돌아갑니다. 새 버전 파일은 https://app.aiakiv.com/selfhost 에서 로그인한 뒤 받습니다.

파일을 열어 "여기부터 복사" 줄 아래를 AI 대화창에 붙여 넣으세요. 새 버전이 나왔는지는
`aiakiv-admin status` 의 새 버전 정보나 "AiAkiv 새 버전 나왔어?" 로 알 수 있습니다.

## 엔진이 밖으로 보내는 것

엔진은 하루 한 번 AiAkiv 서버(`https://app.aiakiv.com`)에 요청 두 개를 보냅니다. 보내는 것은 아래가
전부입니다.

1. **새 버전 확인**: `https://app.aiakiv.com/selfhost/latest.json` 을 읽는 요청 하나입니다. 요청에
   담아 보내는 값은 없습니다.
2. **사용 보고**: `https://app.aiakiv.com/selfhost/api/usage` 로 아래 다섯 값을 보냅니다.

| 값 | 내용 | 예 |
|---|---|---|
| `install_id` | 이 설치에서 처음 한 번 무작위로 만든 번호 | 무작위 UUID |
| `version` | 엔진 버전 | `0.1.0` |
| `edition` | 제품 종류 | `free` |
| `arch` | CPU 종류 | `amd64` 또는 `arm64` |
| `active_users` | 활성 사용자 수 | `3` |

실제로 보내는 값은 `aiakiv-admin status` 결과의 `usage_report` 칸에서 그대로 볼 수 있습니다.

둘 다 끄려면 `.env` 에 `AIAKIV_UPDATE_CHECK=off` 줄을 더하고
`docker compose -f aiakiv-compose.yml up -d` 로 다시 띄우세요. 끄면 엔진은 밖으로 아무 요청도 보내지
않습니다. 인터넷이 없는 컴퓨터라면 이렇게 둡니다. 꺼도 엔진은 똑같이 동작합니다.

## 막혔을 때

- **AI 가 AiAkiv-Local 을 못 찾음**: AI 프로그램을 다시 시작했는지 보세요. Claude Code 는
  `claude mcp list` 에서 `AiAkiv-Local` 이 연결됨으로 나와야 합니다.
- **엔진이 답하지 않음**: Docker(Docker Desktop)가 켜져 있는지 보고, 브라우저로
  `http://127.0.0.1:7777/health` 를 열어 `"status":"ok"` 가 나오는지 보세요. 안 나오면 설치 폴더에서
  `docker compose -f aiakiv-compose.yml up -d` 로 다시 띄웁니다.
- **키가 거절됨(401)**: 키가 막혔거나 잘못 들어갔습니다. `aiakiv-admin key list` 로 키 상태를 보고,
  필요하면 `key reissue` 로 다시 받으세요.
- **여섯째 사용자가 거절됨**: 활성 사용자 5명이 다 찼습니다. 쓰지 않는 사람을 `user remove` 로
  빼면 새 사용자를 넣을 수 있습니다.
- 그래도 안 되면 `docker compose -f aiakiv-compose.yml logs --tail 100 engine` 의 내용을 AI 에게
  보여 주고 원인을 물어보세요.