Keeper Agent¶

Thinklio Built-in Agent Specification Version 0.1 | March 2026

1. Purpose and Problem Statement¶

Keeper is the secrets management agent. It provides secure storage for credentials — API keys, passwords, OAuth tokens, service accounts, and any other sensitive values — and controls how those secrets are shared and consumed.

Its scope is broader than a conventional password manager in one important respect: Keeper is the credential substrate for the entire Thinklio agent ecosystem. When a custom agent needs to call an external API (a CRM, a payment gateway, a bespoke internal service), it does not receive the key directly. Instead, it requests an authenticated call through Keeper, which executes the call on the agent's behalf. The raw credential value never leaves Keeper.

This proxy execution model has several consequences: - A revoked or rotated credential takes effect immediately across all agents that depend on it - An agent can be granted access to a service without any user or developer ever seeing the credential in agent code or configuration - Access can be revoked per-agent without touching the underlying credential

Keeper is also a conventional secrets manager for human users: storing and retrieving passwords for personal use, sharing a credential with a team member in use-only mode, or providing a secure note for sensitive non-credential information.

2. UI Structure¶

[ Chat ]  [ Vault ]  [ Shared ]  [ Agents ]  [ Audit ]

Chat Tab¶

Natural language access for common operations: - "Add a new API key for DocRaptor" - "Who has access to the Postmark credentials?" - "Generate a new password for the Hetzner account" - "Revoke the Tavily key from the newsletter coordinator agent" - "What agents are currently using the Supabase service account?"

Vault Tab¶

The user's personal credential store. A list of all secrets owned by this user, grouped by category (API Keys, Passwords, Service Accounts, Secure Notes, OAuth Tokens). Each row shows: name, category, service/URL, last accessed date, sharing status.

Clicking a secret opens its detail panel: metadata, access history, sharing configuration. The raw value is never shown by default — it must be explicitly revealed with a confirmation step (and this action is logged).

Shared Tab¶

Secrets shared with this user by others, and secrets this user has shared with others. Shows: secret name, owner, permission level, and access history. Secrets shared in use-only mode show no value — only the name and the "use" action.

Agents Tab¶

A view of all agent access grants — which agents have been granted access to which secrets, when the grant was made, when it was last used, and revoke controls. Filterable by agent and by secret.

Audit Tab¶

A searchable, filterable log of all Keeper activity: secret creation, access, sharing, revocation, agent use, and value reveals. Immutable. Accessible to the secret owner; org-level audit accessible to admins.

3. Data Model¶

Secret¶

Secret
├── secret_id           UUID
├── name                string (human label, e.g. "Tavily API Key — Production")
├── category            enum (api_key | password | oauth_token | service_account | secure_note | other)
├── service             string | null (e.g. "Tavily", "DocRaptor", "Hetzner")
├── url                 string | null
├── value               encrypted_string (never returned in API responses; accessed only via proxy)
├── username            string | null (for password-type secrets)
├── notes               string | null
├── tags                string[]
├── owner_id            UUID
├── created_at          timestamp
├── updated_at          timestamp
├── last_accessed_at    timestamp | null
├── expires_at          timestamp | null
└── rotation_reminder   duration | null

Access Grant¶

AccessGrant
├── grant_id            UUID
├── secret_id           UUID
├── grantee_type        enum (user | agent | team)
├── grantee_id          UUID
├── permission          enum (use_only | reveal)
├── granted_by          UUID
├── granted_at          timestamp
├── revoked_at          timestamp | null
└── last_used_at        timestamp | null

use_only — the grantee can trigger authenticated calls via Keeper's proxy but cannot retrieve the raw value. reveal — the grantee can see the raw value (only applicable for human users, never for agents).

4. Proxy Execution Model¶

When an agent needs to use a credential to call an external service:

The agent sends an authenticated call request to Keeper, specifying:
The secret_id it wants to use
The HTTP request to execute (method, URL, headers template, body template)
Keeper validates that the agent holds a current use_only grant for that secret
Keeper retrieves the raw credential value internally
Keeper injects the credential into the request (as a header, query parameter, or body field, depending on how the secret is configured)
Keeper executes the HTTP request and returns the response to the agent
The raw credential is never exposed to the agent at any point

This model requires Keeper to function as an authenticated HTTP proxy for agent calls to external services. The performance implication (an extra hop) is accepted in exchange for credential isolation.

For services that require OAuth flows rather than static keys, Keeper manages the token lifecycle: storing the refresh token, handling token refresh before expiry, and presenting a valid access token to the proxy at request time.

5. Configuration¶

5.1 Admin Configuration¶

Setting	Description
Reveal permission scope	Whether `reveal` grants can be made at all; some orgs may prohibit this entirely
Agent access scope	Whether agents may be granted access to secrets (and if so, which agent types)
Rotation policy	Default rotation reminder intervals per secret category
Audit retention	How long audit log entries are retained
External vault integration	Whether Keeper can sync with an external secrets manager (e.g. HashiCorp Vault, AWS Secrets Manager)

5.2 User Configuration¶

Setting	Description
Default reveal confirmation	Whether revealing a secret value requires password re-entry or MFA
Expiry notifications	How far in advance to be notified of expiring secrets
Auto-categorisation	Whether Keeper attempts to auto-categorise new secrets based on name and service

6. Agent Capabilities¶

Capability	Description
List secrets	Return the names and metadata of secrets the requesting agent has access to (never values)
Proxy call	Execute an authenticated HTTP request on behalf of an agent using a specified secret
Check access	Verify whether the agent has a current grant for a given secret (without revealing the secret)

These are the only capabilities exposed to other agents. Keeper does not expose create, update, delete, or grant operations to agents — those are human-only operations.

A user may share a secret with another user at either use_only or reveal permission level (subject to org policy). The recipient sees the secret name and service in their Shared tab. If use_only, they can trigger proxy calls using the secret but cannot see its value. If reveal, they can see the value after a confirmation step.

A user grants an agent access to a secret at use_only level only. The agent is identified by its agent ID within the Thinklio platform. The user can see all active agent grants in the Agents tab and revoke any at any time.

Agents cannot be granted reveal permission. This is a hard platform rule with no admin override.

Team Secrets¶

An org admin can create team-level secrets accessible to all members of a team, managed through the workspace admin interface. Team secrets follow the same access grant model.

8. Use Cases¶

UC-1: API key for a custom agent¶

A user builds a custom Newsletter Creator agent that uses Tavily for research. They add their Tavily API key to Keeper, then grant the newsletter coordinator agent use_only access. The agent calls Tavily through Keeper's proxy. The user later rotates their Tavily key — they update it in Keeper and all agent calls automatically use the new value.

UC-2: Shared service account¶

An admin adds a shared Postmark account credential to Keeper as a team secret. All agents in the workspace that handle email delivery are granted use_only access. No individual user ever sees the Postmark API key.

UC-3: Personal password storage¶

A user stores their Hetzner Cloud login in Keeper. They use the Vault tab to retrieve it when needed, confirming with their password before the value is revealed. The access is logged.

UC-4: Agent access audit¶

A security-conscious admin reviews the Agents tab to confirm which agents have access to the production database service account. They revoke access from a deprecated custom agent that is no longer in use.

UC-5: Expiry notification¶

A user's DocRaptor API key is set to expire in 14 days. Keeper sends a notification and creates a Taskmaster task: "Renew DocRaptor API key — expires [date]".

9. Open Questions¶

The proxy execution model requires Keeper to be able to make outbound HTTP calls on behalf of agents. This is significant infrastructure. Should the initial release use a simpler model (agent receives a short-lived token it uses directly) with the full proxy model deferred to a later phase?
OAuth token lifecycle management (refresh, expiry, re-authorisation) is complex. Should this be in scope for the initial release, or should OAuth secrets be stored as static tokens only initially?
External vault integration (HashiCorp Vault, AWS Secrets Manager) is high value for enterprise deployments. Phase two?
How does Keeper handle the case where a proxy call fails due to an invalid credential (e.g. a rotated key that hasn't been updated in Keeper)? The error must be surfaced to the agent without leaking the credential value or details.

Previous: Rolodex Agent | Next: Mail Agent