| name | agentic-vault-setup-guide |
| description | Comprehensive installation guide for Agentic Vault with AWS KMS on non-AWS VMs. Covers the full setup scope: AWS KMS key creation, private CA + client certificates, IAM Roles Anywhere configuration, VM tooling (AWS CLI, signing helper), OpenClaw plugin installation, plugin configuration, policy setup, and systemd service integration. Use this skill whenever a user mentions installing Agentic Vault, setting up a vault, deploying to a VM, configuring AWS KMS signing, or connecting Agentic Vault to OpenClaw. Also trigger when users ask about certificate setup, IAM Roles Anywhere, or vault credential issues on non-AWS machines.
|
Agentic Vault Setup Guide
Guide users through deploying Agentic Vault on a non-AWS VM using IAM Roles Anywhere for zero long-lived credentials.
Architecture Overview
Dev Machine (has AWS access) VM (production, no AWS credentials)
───────────────────────────── ────────────────────────────────────
1. Create KMS key (secp256k1) 6. Install AWS CLI + signing helper
2. Create CA + client cert 7. Deploy client cert
3. Store CA key securely 8. Write AWS config profile
4. Create Trust Anchor + Role 9. Install OpenClaw plugin
5. Transfer cert to VM 10. Configure plugin + policy
11. (Optional) systemd gateway env
Auth flow (zero long-lived credentials):
VM → aws_signing_helper → IAM Roles Anywhere → STS → temp credentials (1h) → KMS:Sign
Decision Tree
Before starting, determine which phases the user needs:
Has AWS KMS key?
├─ No → Start at Phase 1 (read references/aws-dev-setup.md)
└─ Yes
Has client certificate?
├─ No → Start at Phase 1, Step 2
└─ Yes
Has IAM Roles Anywhere configured?
├─ No → Start at Phase 1, Step 4
└─ Yes
VM tools installed?
├─ No → Start at Phase 2 (read references/vm-setup.md)
└─ Yes
OpenClaw plugin configured?
├─ No → Start at Phase 3 (read references/openclaw-config.md)
└─ Yes → Verify setup (see Verification below)
Phases
Phase 1: AWS Setup (Dev Machine)
Read references/aws-dev-setup.md for complete instructions.
| Step | What | Verification |
|---|
| 1 | Create KMS key (ECC_SECG_P256K1) | aws kms describe-key --key-id KEY_ID returns Enabled |
| 2 | Create self-signed CA + client cert | openssl verify -CAfile ca.pem client.crt succeeds |
| 3 | Store CA key securely (1Password / USB) | ca.key removed from disk |
| 4 | Create Trust Anchor, IAM Role, Profile | All three enabled + correct ARNs |
| 5 | Transfer client cert+key to VM via scp | Files exist in /tmp/ on VM |
Common gotchas in this phase:
- CA cert must have
basicConstraints=critical,CA:TRUE or Trust Anchor creation fails
- Client cert must have
keyUsage: digitalSignature + extendedKeyUsage: clientAuth
- Never transfer
ca.key to the VM
Phase 2: VM Setup
Read references/vm-setup.md for complete instructions.
Alternatively, if the user prefers an automated approach, the project provides a one-command setup script:
export TRUST_ANCHOR_ARN="arn:aws:rolesanywhere:REGION:ACCOUNT:trust-anchor/ID"
export PROFILE_ARN="arn:aws:rolesanywhere:REGION:ACCOUNT:profile/ID"
export ROLE_ARN="arn:aws:iam::ACCOUNT:role/ROLE_NAME"
export AWS_REGION="ap-northeast-1"
bash scripts/vm-setup.sh
Manual steps overview:
| Step | What | Verification |
|---|
| 6 | Install AWS CLI v2 | aws --version |
| 7 | Install aws_signing_helper | aws_signing_helper --version |
| 8 | Deploy client cert to /etc/pki/rolesanywhere/ | ls -la /etc/pki/rolesanywhere/ |
| 9 | Write ~/.aws/config profile | cat ~/.aws/config shows profile |
| 10 | Verify credentials | AWS_PROFILE=rolesanywhere-kms aws sts get-caller-identity |
Key points:
- Signing helper URL is case-sensitive (
Aarch64 not AARCH64)
credential_process must be a single line in ~/.aws/config- Client key needs
chmod 440 + chown root:<app-group>
Phase 3: OpenClaw Plugin + Policy
Read references/openclaw-config.md for complete instructions.
| Step | What | Verification |
|---|
| 11 | Install plugin | openclaw plugins list shows agentic-vault-openclaw |
| 12 | Configure plugin in OpenClaw config | Plugin loads without errors |
| 13 | Create policy.json | vault_get_address returns address |
| 14 | (Optional) systemd gateway env | systemctl --user show openclaw-gateway -p Environment has AWS vars |
Full Verification Checklist
After completing all phases, verify end-to-end:
AWS_PROFILE=rolesanywhere-kms aws sts get-caller-identity
AWS_PROFILE=rolesanywhere-kms aws kms get-public-key \
--key-id alias/agentic-vault-signer --region REGION
openclaw plugins list
Troubleshooting
Read references/troubleshooting.md for a complete troubleshooting guide covering:
- Certificate issues (missing extensions, permissions, expiry)
- Roles Anywhere errors (disabled anchor/profile, access denied)
- Signing helper problems (wrong arch, XML download, config parsing)
- OpenClaw gateway systemd env var issues
- Common chain ID mismatches
Quick Reference: Collected ARNs
Users need these ARNs across multiple steps. Suggest they record them early:
| ARN | Where Created | Where Used |
|---|
| KMS Key ARN | Step 1 | IAM policy (Step 4c), plugin config (Step 12) |
| Trust Anchor ARN | Step 4a | IAM trust policy (Step 4b), AWS config (Step 9) |
| Profile ARN | Step 4d | AWS config (Step 9) |
| Role ARN | Step 4b | Roles Anywhere Profile (Step 4d), AWS config (Step 9) |
Annual Maintenance
Client certificates expire after 1 year. Read references/aws-dev-setup.md "Cert Renewal" section for the renewal procedure. Key points:
- Retrieve CA key from secure storage
- Sign new client cert with same extensions
- Transfer to VM, replace old cert, restart services
- Re-secure CA key
