Dùng secrets vault

ak secrets giữ các giá trị nhỏ có tên, như API key, token và certificate, trong keychain của hệ điều hành hoặc một file vault mã hoá bằng age. Coding agent dùng giá trị qua tham chiếu ${secret:NAME} thay vì một file .env không được quản lý hay một lệnh export trong shell. Hướng dẫn này giải thích các lệnh phối hợp với nhau thế nào; trang của từng lệnh có đầy đủ flag, giá trị mặc định và exit code. Ứng dụng Desktop có trang Secrets riêng.

Các lệnh

Giá trị được đọc từ --value=- (stdin), --value-file hoặc một prompt không hiện ký tự, không bao giờ từ một giá trị flag dạng literal vốn sẽ nằm lại trong lịch sử shell. ak secrets get in [redacted] trừ khi bạn truyền --reveal trong terminal.

Chọn backend

Backend được chọn từ --backend, rồi AGENTKIT_SECRETS_BACKEND, rồi backend trong phần secrets của $AGENTKIT_HOME/config.yaml, và nếu không có thì là keychain. Vì vậy một config máy chọn file backend sẽ khiến mọi lần resolve của agent thất bại, dù không flag nào nói vậy. Hãy dùng keychain trên máy nào mà agent cần secret; file backend hợp với vault chỉ mình bạn đọc từ terminal.

Keychain hệ điều hành có thể hỏi bạn cho phép truy cập ở lần đầu ak đọc một mục, hoặc sau khi nâng cấp làm binary thay đổi. Prompt đó là cơ chế kiểm soát truy cập của chính keychain.

Thiết lập file backend

ak secrets recovery init --label <label>                 # create the vault and one recovery key
ak secrets recovery add <age-public-key> --label <label>  # enroll another recovery key
ak secrets recovery list

recovery init hiển thị recovery private key một lần và không lưu ở đâu cả. Hãy cất nó ở nơi máy không chạm tới được: nếu bạn mất passphrase và mọi recovery key, không ai mở được vault. Nếu quên passphrase, hãy chạy một lệnh đọc vault với --unlock-with-recovery trong terminal, dán recovery key và chọn passphrase mới.

Máy ghi nhớ phiên bản vault mới nhất mà nó từng thấy. Nếu vault trên đĩa cũ hơn (khôi phục từ bản sao lưu hoặc bị một bản sao cũ sync đè), các lệnh mở vault sẽ thất bại. Hãy tìm nguyên nhân trước; nếu vẫn muốn giữ vault cũ hơn, chạy ak secrets recovery accept-rollback. Các lần ghi sau bản sao cũ đó sẽ mất.

Cho agent dùng một secret

Agent viết một tham chiếu vào tool call:

curl -H "Authorization: Bearer ${secret:NAME}" <url>

Hook PreToolUse secrets-inject của Kit core thay giá trị vào trong bộ nhớ ngay trước khi tool chạy. Trong Claude Code, nó chỉ quét lệnh của Bash và PowerShell cùng URL của WebFetch. Với mỗi tham chiếu, nó chạy ak secrets resolve, lệnh này xác định agent gọi bằng cách duyệt cây tiến trình và băm binary của agent; bên gọi không bao giờ được lấy từ flag. Mọi lỗi đều chặn tool call thay vì chuyển tiếp tham chiếu nguyên văn.

Khi ak run khởi động một agent Codex hoặc Grok, các tham chiếu ${secret:NAME} trong môi trường truyền cho agent đó được resolve theo cùng cách, và lần chạy dừng lại nếu một giá trị không thể được release.

Một lần resolve chỉ thành công khi có grant khớp bốn trường: secret, project, fingerprint binary của agent và mục đích. Mục đích rỗng là một giá trị literal, không phải wildcard, và block luôn thắng mọi allow trên cùng scope. Lấy fingerprint của agent từ ak secrets trust <adapter> --json hoặc từ một yêu cầu đang chờ.

ak secrets grant --allow-host <host> giới hạn một allow vào các URL WebFetch nhắm tới những host được liệt kê. Một grant bị giới hạn sẽ từ chối mọi lần release mà Hook không kiểm tra được đích đến, bao gồm mọi tham chiếu trong Bash hoặc PowerShell. Giới hạn này chỉ áp dụng cho đường thay giá trị của chính Hook; xem ak secrets grant để biết quy tắc so khớp chính xác.

Trả lời yêu cầu duyệt

Khi không grant nào bao phủ một lần resolve, nó không hỏi. Nó thất bại an toàn (exit 8) và để lại một yêu cầu cho bạn. Trả lời bằng ak secrets approve trong terminal của chính bạn, hoặc trong hộp duyệt trên trang Secrets của Desktop:

Một agent cứ xin mà không có grant sẽ bị giới hạn tốc độ theo fingerprint rồi bị giữ trong thời gian chờ (exit 9). Một job chạy dưới grant thường trực không bao giờ chạm tới giới hạn này.

grant và approve từ chối chạy (exit 6) khi có agent nằm phía trên chúng trong cây tiến trình, và Desktop từ chối câu trả lời khi một agent đã khởi động ứng dụng. Điều này ngăn agent tự duyệt yêu cầu của chính nó theo cách hiển nhiên; đây là gờ giảm tốc, không phải ranh giới.

Revoke

ak secrets revoke <ref> --agent sha256:<hash>   # one scope, allow or block
ak secrets revoke --agent sha256:<hash> --all   # every grant that binary holds

Revoke chặn các lần đọc sau này. Nó không thu hồi giá trị agent đã đọc, nên hãy rotate secret sau một lần revoke khẩn cấp.

Sau một lần release

Giá trị đã release tới được tiến trình và tham số của tool, và runtime có thể ghi lại call đã chạy, kèm giá trị, vào transcript session của nó. AgentKit chỉ giữ hash và độ dài của mỗi giá trị đã release, trong các release manifest dưới $AGENTKIT_HOME/diagnostics/manifests/. Hai lệnh dùng chúng để gỡ các giá trị đã release về sau:

• ak diagnostics export gỡ chúng khỏi gói hỗ trợ khi đọc được các manifest.
• ak sessions redact tìm chúng trong các session file Claude Code đã đăng ký. Lệnh chạy thử (dry run) trừ khi bạn truyền --apply --yes, và sao lưu trước khi ghi lại.

Rotate

Mỗi secret có một cửa sổ rotation: mặc định 90 ngày, hoặc giá trị bạn truyền với ak secrets set <ref> --rotate-ttl <days>d. ak secrets list đánh dấu các secret đã quá cửa sổ. Thay giá trị bằng ak secrets rotate <ref>; lệnh thất bại nếu ref không tồn tại, nên gõ nhầm sẽ không tạo ra secret mới.

Audit các lần release

Mọi lần resolve có bên gọi xác định được đều ghi một dòng vào ledger secrets_audit, cho cả release lẫn từ chối, trước khi bất kỳ giá trị nào được trả về. Một dòng ghi ref, project, fingerprint, label, mục đích, quyết định, nguồn, session, mã lỗi và ngữ cảnh, không bao giờ có giá trị. Với tham chiếu WebFetch, host đích được thêm vào ngữ cảnh. Một lần reveal trên Desktop cần lý do, được ghi theo cùng cách.

Đọc ledger bằng ak secrets audit hoặc trên trang Audit log của Desktop. Ledger được giữ cho tới khi bạn đổi retention của nó bằng ak data retention --class secrets_audit.

Khi Desktop đang mở, mỗi lần release còn hiển thị một thông báo trong ứng dụng có nút Revoke this agent's grants, và tạo một thông báo hệ điều hành với tiêu đề Secret released khi không ai đang nhìn cửa sổ. Không thông báo nào chứa giá trị; xem trang Secrets.

Export

ak secrets export --json                               # inventory on stdout, no values
ak secrets export --out ./inventory.json               # the same, as a file only you can read
ak secrets export --include-values --out ./values.age  # confirms, then writes an age-encrypted file

Bản export mặc định không có giá trị. --include-values cần terminal tương tác và một đường dẫn --out kết thúc bằng .age; giá trị không bao giờ ra stdout. Lệnh hỏi bạn xác nhận và chọn passphrase, và không gì trên máy giữ passphrase đó, nên mất passphrase là mất bản export. Giải mã bằng CLI age gốc, ví dụ age --decrypt values.age | jq ., và đối xử với mọi file đã giải mã như chính các secret bên trong.

Chuyển từ .env

ak secrets import-env <path>           # skips keys that already exist
ak secrets import-env <path> --force   # overwrites them instead

Lệnh chỉ báo số lượng, không bao giờ báo giá trị, và đọc tối đa 1 MiB. Sau đó hãy grant cho các agent cần từng key, đổi lệnh sang dùng ${secret:NAME}, và xoá file .env.

Đồng bộ đám mây

Vault nằm trên một máy. Tính năng đồng bộ mã hoá đầu-cuối, tự chọn bật, giữa các thiết bị, đồng đội và CI đang được phát triển với tên ak-vault. Tính năng này chưa dùng được: dịch vụ đồng bộ vẫn tắt cho tới khi giao thức vượt qua một đợt đánh giá bảo mật độc lập.

Thiết kế giữ vault cục bộ làm nguồn sự thật:

• Mỗi thiết bị mã hoá giá trị trước khi tải lên, nên máy chủ đồng bộ chỉ lưu và chuyển tiếp bản mã, không đọc được secret nào.
• Thay đổi thành viên được chủ vault ký và nối chuỗi băm, nên máy chủ không thể tự thêm người đọc hay giấu một lần gỡ bỏ.
• Các chỉnh sửa đồng thời được giữ lại thành xung đột để bạn xử lý, không bao giờ bị ghi đè âm thầm, và một thiết bị cũ không thể làm sống lại secret đã xoá.
• Mỗi thiết bị giữ grant của riêng nó: policy được đồng bộ chỉ có thể thu hẹp những gì agent được đọc, không bao giờ mở rộng.

Giao thức và mô hình mối đe doạ được công khai.

Giới hạn

Đây là các ranh giới có chủ đích của phiên bản này:

• Grant nghĩa là tin model của agent với bản rõ. Một agent bị prompt injection có thể gửi giá trị đã grant tới bất kỳ host nào mà --allow-host không loại trừ. Grant không giới hạn dựa vào permission prompt của runtime, và AGENTKIT_SECRETS_INJECT_AUTO_ALLOW=1 bỏ prompt đó.
• Không có tường chắn sau khi inject. Khi giá trị đã vào một tiến trình con, môi trường của nó hoặc một transcript, AgentKit không thể giữ nó lại. Redact và rotate là cách khắc phục.
• Từ chối tự duyệt chỉ là gờ giảm tốc. Một agent chạy dưới user của bạn có thể tách khỏi cây tiến trình hoặc sửa trực tiếp file grant.
• Kiểm soát truy cập keychain thuộc về hệ điều hành. Bất kỳ tiến trình nào chạy dưới user của bạn mà keychain cho vào đều đọc được một mục.
• Kẻ tấn công bộ nhớ. Ai đọc được bộ nhớ của ak, của Hook hoặc của tiến trình tool đều đọc được giá trị khi nó đang được dùng.
• Cửa sổ cố định. Cửa sổ grant và rotation là các khoảng thời gian cố định.