Part 5: Team Git Sync, Scoped Auth & GPU KV Warming
Setting up a team without writing Rust? Follow Share a vault with a team. This part covers the same steps with the Rust API.
In this tutorial, you harden an Obsidian vault for multi-agent teams. You start ControlPlaneServer::bind_with_auth, issue per-agent ScopedApiKey credentials, synchronize a shared Git repository with VaultEngine::git_sync, connect obsidian-aether-plugin, and warm vLLM or SGLang KV caches.
Before you begin. Complete Part 4: Obsidian Vault Compiler & MCP Server. Initialize your vault directory as a Git repository with a remote named origin if you want to run git_sync end to end.
Step 1: Start the authenticated team gateway
Generate a 64-hex bootstrap admin key (aek_<64-hex>) and start aether-mcp with --require-auth:
export AETHER_BOOTSTRAP_ADMIN_KEY="aek_$(openssl rand -hex 32)"
cargo run -p muninn-aether-vault --bin aether-mcp -- \
--vault /path/to/team-vault \
--http-addr 0.0.0.0:4771 \
--require-auth \
--bootstrap-admin-key "$AETHER_BOOTSTRAP_ADMIN_KEY" \
--kv-endpoint http://127.0.0.1:8000 \
--kv-model llama-3.1-8b
Passing --require-auth allows non-loopback binds on ControlPlaneServer::bind_with_auth and enforces Authorization: Bearer aek_<hex> on every HTTP route. ensure_bootstrap_admin_key stores only the domain-separated SHA-256 digest of the secret in agent_api_keys under AgentId "bootstrap-admin".
Step 2: Issue and inspect scoped API keys
AgentRole defines three ordered roles (Reader, Contributor, Admin). Issue a Contributor key restricted to the engineering scope using the admin token:
curl -sS -X POST http://127.0.0.1:4771/v1/auth/keys \
-H "Authorization: Bearer $AETHER_BOOTSTRAP_ADMIN_KEY" \
-H 'Content-Type: application/json' \
-d '{
"agent_id": "coding-agent",
"role": "contributor",
"scopes": ["engineering"]
}'
The JSON response returns key (key_id formatted as key_<16-hex>, agent_id, role, scopes, created_at) and a one-time plaintext secret (aek_<64-hex>). Store secret in AETHER_API_KEY.
To bind a stdio MCP client to that scoped agent, pass --api-key "$AETHER_API_KEY":
cargo run -p muninn-aether-vault --bin aether-mcp -- \
--vault /path/to/team-vault \
--api-key "$AETHER_API_KEY"
Under a scoped session:
aether_recallintersects the requestedscopewith the key'sscopesbefore top-K truncation. Keys with*may read all non-private scopes, andglobalnotes are readable by any valid key.aether_stage_memoryrequiresContributororAdmin, defaultsscopetoagent.default_write_scope(), and stampsproposed_bywithagent.agent_id.aether_inspect_sourcedenies cross-scope notes and cross-scope entries insideAether/Compiled/Approved.md.
List or revoke keys anytime with GET /v1/auth/keys and POST /v1/auth/keys/revoke (Admin only).
Step 3: Synchronize a team Git vault (git_sync)
Run POST /v1/git/sync as an Admin (or call VaultEngine::git_sync(GitSyncOptions::new()) in Rust):
curl -sS -X POST http://127.0.0.1:4771/v1/git/sync \
-H "Authorization: Bearer $AETHER_BOOTSTRAP_ADMIN_KEY" \
-H 'Content-Type: application/json' \
-d '{"remote":"origin","branch":"main","push":true}'
During git_sync, VaultEngine executes five steps:
- Ensures
.gitignoreignores.aether/and.obsidian/plugins/aether-memory/data.jsonso local SQLite files and plugin API keys never enter Git history. - Runs
git fetchand merges into the local branch, redacting anyuserinfo@credentials from reported remotes viaredact_url_userinfo. - Resolves merge conflicts in
Aether/Inbox.mdandAether/Compiled/Approved.mdautomatically using a monotonic join-semilattice keyed onCandidateIdwhereApprovedoverridesRejected, andRejectedoverridesPending. - Skips human Markdown notes containing unresolved
<<<<<<<,=======, and>>>>>>>conflict markers outside fenced code blocks while keeping prior SQLite AMUs active until a human resolves the conflict. - Re-syncs the vault, commits resolved state, and optionally pushes.
Step 4: Connect obsidian-aether-plugin over HTTPS + bearer auth
When targeting a remote authenticated server (--require-auth), configure Settings -> AMC inside Obsidian:
- Set Aether control-plane URL to your HTTPS gateway (for example
https://vault.internal:4771). - Paste your scoped token (
aek_<64-hex>) into API key. The plugin stores that token locally in.obsidian/plugins/aether-memory/data.json, whichgit_synckeeps out of Git. - Click Test connection to confirm connectivity and token permissions.
- Configure Live vault sync, Sync debounce (ms) (
500to10000), optional Auto-pull interval (seconds) to refreshAether/Inbox.mdandAether/Compiled/Approved.md, and Default KV model (for examplellama-3.1-8b). Turn on Run Dream consolidation on push only when using anAdminkey.
Calling Sync vault with Aether (aether-sync-vault) or editing notes with Live vault sync enabled pulls GET /v1/vault/pull, pushes delta public notes (POST /v1/vault/push) without ever transmitting aether_tier: private note bodies, and materializes updated Aether/Inbox.md and Aether/Compiled/Approved.md files back into Obsidian.
For headless or embedded integrations, instantiate AetherCompanionPlugin directly in TypeScript:
import { AetherCompanionPlugin, type ObsidianHostAdapter } from './src/main.ts';
const plugin = new AetherCompanionPlugin(hostAdapter, 'https://vault.internal:4771', {
apiKey: process.env.AETHER_API_KEY,
defaultKvModel: 'llama-3.1-8b',
});
await plugin.onload();
Step 5: Pre-warm GPU KV caches (warm_kv_cache)
With --kv-endpoint and --kv-model configured (or using VllmLmCacheHttpAdapter or InMemoryKvCacheAdapter in Rust), warm PagedAttention prefix blocks and CacheBlend AMU chunks over HTTP (Contributor or Admin):
curl -sS -X POST http://127.0.0.1:4771/v1/kv/warm \
-H "Authorization: Bearer $AETHER_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model_id": "llama-3.1-8b",
"scope": "engineering",
"target_tier": "gpu_hbm",
"include_hot_prefix": true,
"include_cache_blend": true
}'
You receive a KvWarmReport with blocks_warmed, blocks_reused, tokens_warmed, estimated_baseline_ttft_ms, estimated_warmed_ttft_ms, estimated_ttft_saved_ms, ttft_reduction_pct, fallback_used, and block_hashes.
If the vLLM or LMCache server is unreachable and offline_fallback is true (the default on VllmLmCacheConfig::new), the adapter falls back to its local tiered InMemoryKvCacheAdapter (GpuHbm to HostDram to NvmeSsd) and sets fallback_used: true. Subsequent aether_recall calls passing kv_model: "llama-3.1-8b" attach kv_hint (prefix_block_hashes, cache_blend_hashes, cache_hit_tokens, total_tokens, estimated_ttft_saved_ms). Check live tier usage anytime via GET /v1/kv/stats?model_id=llama-3.1-8b.
Where to go next
- Read Concepts Overview: Model-Free & Pieces-First to learn how
RecordStoreconsistency,PersonalizedPageRank, and KV block eviction work internally. - Bookmark Crates, Traits & API Reference, the aether-mcp CLI and MCP tools, and the HTTP API for daily development lookup.