AgentKit Vault: cất API key cho đàng hoàng, đừng để agent đọc `.env` nữa

Bài 6/20 trong bộ onboarding AgentKit v3. Đọc khoảng 10 phút.

Thú thật đi: máy bạn đang có bao nhiêu file .env chứa API key thật? Tui từng đếm máy tui, ra con số làm tui hơi... ngại 😅

Vấn đề không chỉ là "lỡ commit lên GitHub". Giờ agent đọc file trong project như cơm bữa. Chỉ cần một prompt injection trong README của một thư viện nào đó là key của bạn có thể bị đọc ra. Vault của AgentKit sinh ra để xử lý chuyện này.

Bài này chia 2 phần rõ ràng: vault cục bộ (đã ship, xài ngay) và đồng bộ đa thiết bị (preview, đọc kỹ cảnh báo).

Phần A: vault cục bộ ak secrets ✅

1/ Nó cất secret ở đâu?

• Mặc định: keychain của hệ điều hành (macOS Keychain, Windows Credential Manager, Secret Service trên Linux).

• Máy không có keychain dùng được (server, container): file vault mã hoá bằng age, --backend=file, có recovery key.

• File ~/.agentkit/secrets/index.json chỉ chứa metadata (tên, người tạo, thời gian, gợi ý ngắn), không bao giờ chứa giá trị.

2/ Chuyển .env vào vault

ak secrets import-env .env

Hoặc thêm từng cái:

ak secrets set OPENAI_API_KEY        # nhập giá trị qua prompt, không lưu vào lịch sử shell
ak secrets list
ak secrets get OPENAI_API_KEY        # mặc định đã redact
ak secrets search stripe --environment production

Import xong, nhớ xoá hoặc dọn file .env gốc. Không thì coi như chưa làm gì 😁

3/ Dùng secret mà không lộ giá trị

Chạy một chương trình với secret trong môi trường:

ak secrets run --env STRIPE_API_KEY=STRIPE_API_KEY --purpose deploy -- npm run deploy

--env BIEN=TEN_SECRET gắn secret vào đúng một biến cho đúng một chương trình, và lần chạy đó được ghi vào sổ audit.

Tham chiếu trong config của agent: hook secrets-inject thay ${secret:TEN_SECRET} bằng giá trị thật lúc chạy. Agent chỉ thấy tham chiếu, không thấy key.

Một tên biến, nhiều secret: ví dụ DATABASE_URL trỏ tới bản staging hay production tuỳ ngữ cảnh:

ak secrets alias --help

So sánh mà không in ra:

ak secrets compare OPENAI_API_KEY --value-file ./key-can-kiem-tra.txt

Kết quả chỉ là "khớp" hay "khác", không in giá trị nào cả.

4/ Agent xin quyền, bạn duyệt

Đây là phần tui thích nhất. Agent không tự lấy secret được. Nó phải xin, bạn duyệt, và mọi lần đọc đều có sổ ghi:

ak secrets approve     # trả lời các yêu cầu agent đang chờ
ak secrets grants      # xem agent nào được đọc secret nào
ak secrets revoke ...  # rút quyền
ak secrets audit       # sổ ghi truy cập
ak secrets trust       # xem hoặc ghim lại binary của coding agent

Quyền được cấp cho binary agent đã lấy dấu vân tay (fingerprint). Binary đổi (update, bị thay) thì phải ghim lại.

5/ Để agent tự làm đúng

Trong Claude Code hay Codex, dùng skill ak-vault:

/ak-vault import .env của project này vào vault rồi sửa config dùng ${secret:...}

Skill này được viết để không bao giờ in giá trị secret, và tôn trọng lựa chọn của bạn nếu bạn đã quyết định dùng .env hay một secret manager khác. Nó hỏi tối đa một lần.

Phần B: đồng bộ đa thiết bị (AK Vault) 🧪

Ý tưởng

Bạn có laptop, desktop, máy công ty. Muốn secret đi theo mà server không bao giờ đọc được. AK Vault làm đúng vậy: mã hoá đầu cuối (E2E), local-first, opt-in.

• Server (Cloudflare Worker, mỗi vault một Durable Object SQLite) chỉ lưu ciphertext và một ít metadata đã được tài liệu hoá.

• Khoá vault được bọc bởi: khoá thiết bị, khoá dẫn xuất từ mật khẩu bằng Argon2id, và một recovery key 32 byte ngẫu nhiên.

• Thêm máy mới: máy mới hiện mã SAS 6 chữ số, bạn so và duyệt trên một máy đã tin cậy. Giống ghép Bluetooth, nhưng nghiêm túc hơn.

• Danh sách thành viên có chữ ký, có cơ chế thu hồi thiết bị.

• Repo mã nguồn mở, giấy phép MIT: bestagentkits/ak-vault.

Lệnh (có trong binary 3.0.0, đang ẩn khỏi --help tổng)

ak login --email ban@example.com
ak secrets sync enable
ak secrets sync now
ak secrets sync status
ak secrets devices add       # trên máy mới
ak secrets devices approve   # trên máy đã tin cậy, so mã SAS
ak secrets devices list

Ngoài ra còn sync recover, sync rotate-recovery, sync disable, devices remove, devices rotate.

⚠️ Cảnh báo phải đọc

Nói thẳng, vì đây là secret của bạn:

1. Đồng bộ chưa GA. Lệnh ak secrets sync đang bị ẩn khỏi danh sách lệnh trong --help. README của ak-vault ghi rõ: chưa sẵn sàng chung, đừng lưu credential production.

2. Dashboard trên trình duyệt và remote MCP của vault.agentkit.best đã được bật trên production theo quyết định của chủ sản phẩm ngày 01/11/2026, trước khi qua cổng release. Trang vault tự ghi đây là pre-release.

3. Remote MCP khác với đồng bộ E2E: khi dùng remote MCP, plaintext đi qua bộ nhớ của server. Nếu bạn cần "server không bao giờ thấy plaintext", đừng dùng remote MCP.

4. Giao thức v1 hiện mới được chủ sản phẩm review, chưa có review độc lập bên ngoài.

Vậy tui khuyên gì?

• Xài vault cục bộ ngay hôm nay. Nó đã ship và giải quyết 80% vấn đề.

• Muốn thử đồng bộ thì thử với key dev/test. Key production đợi bản GA.

• Cất recovery key ở chỗ an toàn ngoài máy. Mất cả thiết bị lẫn recovery key là mất vault, server cũng không cứu được (đó là ý nghĩa của zero-knowledge).

Tóm tắt nhanh

Bài tiếp: Hooks và quyền riêng tư →

Nguồn

• ak secrets --help, ak secrets sync --help (ak 3.0.0, chạy trong HOME tạm)

• Repo ak-vault (MIT): https://github.com/bestagentkits/ak-vault, README, ADR 0001, docs/security/threat-model.md

• Trang https://vault.agentkit.best (kiểm tra 02/11/2026): ghi chú pre-release, dashboard và remote MCP bật trên production từ 01/11/2026

• Hướng dẫn secrets: agentkit/docs/guides/secrets.md (tag v3.0.0), mã nguồn apps/cli/internal/commands/secretscmd/sync_cmd.go (sync Hidden: true)