Skip to content

Connect an AI Agent to a Safe

UnoLock was built to protect you. Now it can protect both you and your agent.

This setup path is for the current alpha of Agentic Safe Access. It is suitable for evaluation and early testing, but not for broad production rollout yet.

Overview

This guide explains how to connect an AI agent to an existing UnoLock Safe using an Agent Key and the UnoLock MCP.

This workflow is for customers who want an AI assistant or automation host to work with Safe content without giving it unrestricted Safe access.

In practice, that often means using UnoLock as:

  • a secure secret store for the agent
  • a durable memory store for notes, checklists, and other working data
  • a controlled shared space where the agent can only see and modify what the user explicitly grants

This workflow is best suited to user-adjacent agent hosts running in a normal logged-in user session. It is harder to use securely in fully headless or remote sandboxed agents where TPM, Secure Enclave, keychain access, or other non-exportable key storage may be unreliable.

macOS support is still alpha. On a Mac, the UnoLock Agent MCP now prefers Secure Enclave and falls back to a non-exportable Keychain-backed key when Secure Enclave is unreliable in the current launch context.

Before You Start

Make sure you have:

  • an existing UnoLock Safe
  • either:
  • a Free or Inheritance Safe using its single included space
  • or a Sovereign or HighRisk Safe if you want broader Space segmentation
  • admin access to that Safe
  • a host environment where you can run the UnoLock MCP
  • the UnoLock Agent MCP installed from the official GitHub Releases page when a binary is available, or from the official GitHub repository as the source-install fallback:
  • https://github.com/TechSologic/unolock-agent/releases
  • https://github.com/TechSologic/unolock-agent

Tier behavior:

  • Free: one included Safe space, one normal access key, plus one extra Agent Key for that same space
  • Inheritance: one included Safe space, one extra Agent Key is also supported for that same space
  • Sovereign / HighRisk: broader multi-Space and collaboration workflows

If possible, use a host with:

  • TPM
  • vTPM
  • Secure Enclave
  • or a platform-backed secure key store

On Windows and WSL, the UnoLock Agent MCP now prefers TPM-backed keys and falls back to a non-exportable Windows CNG key when TPM-backed creation is unavailable.

For normal customer use, this is not just a recommendation. The UnoLock Agent MCP is designed for high-security secret access and works best when the host can provide a production-ready TPM, vTPM, Secure Enclave, or equivalent platform-backed non-exportable key store. If it cannot, the MCP can still fall back to a lower-assurance software provider and will report that reduced assurance clearly.

Install the UnoLock Agent MCP

Install the official UnoLock Agent MCP from:

  • https://github.com/TechSologic/unolock-agent/releases
  • https://github.com/TechSologic/unolock-agent

Follow the install instructions in that repository for your MCP host and operating system before continuing.

In the normal hosted UnoLock setup, you should not need to preconfigure UnoLock-specific URLs, versions, or validation keys in the MCP host. The MCP can derive those from the Agent Key connection URL.

Create the Agent Key

  1. Open your Safe in UnoLock.
  2. Go to Configuration.
  3. Open the access key management screen.
  4. Create a new key.
  5. Choose Agent Key.
  6. Give the key a name.
  7. Choose its permission level:
  8. ro
  9. rw
  10. If needed, restrict the key to selected Spaces.
  11. Decide whether it should use the same PIN behavior as your current access or a different PIN.
  12. Finish the key-creation flow.

At the end, UnoLock will generate a one-time agent key connection URL.

Give the URL to the Agent Host

  1. Start the UnoLock MCP on the host where the AI agent will run.
  2. Let the AI agent inspect MCP registration status.
  3. When it asks for a UnoLock agent key connection URL, provide the generated URL.
  4. If the Agent Key uses a PIN, it is usually best to provide the PIN at the same time.

The expected format is an agent URL such as:

#/agent-register/...

Do not give the agent a normal browser access-key URL such as #/register/....

If the agent host starts cold and knows nothing about UnoLock yet, that is expected. The MCP should tell the agent to ask you for the UnoLock agent key connection URL and, if configured, the PIN. That lets registration finish with fewer steps.

Complete Registration

  1. The MCP uses the one-time connection URL to begin registration.
  2. If the key requires a PIN and you did not provide it already, the AI agent will ask you for it.
  3. Provide the PIN.
  4. The MCP finishes registration and stores the new agent credential on that host.

After successful registration:

  • the one-time connection URL cannot be reused
  • the MCP remains registered to that Safe
  • the PIN is kept only in process memory

Use the Agent

Once registered and authenticated, the agent can use the MCP to:

  • list visible Spaces
  • list notes
  • list checklists
  • retrieve records in an agent-friendly format
  • list Cloud files in the current Space
  • download a Cloud file by exact file name or archive id in the current Space
  • if the Agent Key is rw, create and update supported note/checklist content in allowed Spaces
  • if the Agent Key is rw, upload, rename, replace, and delete Cloud files in allowed Spaces
  • back up selected local agent files through the current one-way sync feature, with explicit restore

The agent will only see what the Agent Key is allowed to see.

This lets customers move important agent data out of fragile local memory files and into a Space-scoped encrypted Safe that remains under the user's control.

On Free and Inheritance, that means the agent works inside the Safe's single included space. For broader compartmentalization across multiple Spaces, use Sovereign or HighRisk.

Current write support includes:

  • create note
  • update note text
  • rename note or checklist title
  • create checklist
  • set checklist item checked state
  • add checklist item
  • remove checklist item
  • upload file
  • rename file
  • replace file
  • delete file
  • one-way sync-add, sync-run, and sync-restore for selected local files

Current write limits:

  • writes require the latest record version
  • writes are blocked for locked/read-only records
  • Cloud file actions are limited to UnoLock Cloud archives in the current Space
  • file uploads require explicit force when a same-name Cloud file already exists in that Space
  • broader rich-text editing is not part of the current MVP

Review the Device Assurance Details

After registration, you can review the key in UnoLock’s key-management UI.

If assurance data is available, UnoLock can show:

  • whether the registering client reported TPM, vTPM, platform, or WebAuthn-based protection details
  • whether the key was reported as exportable or non-exportable
  • basic registration metadata such as the recorded time and reported transport or provider details

Important:

  • this information is reported by the client that registered the key
  • UnoLock does not independently verify these claims
  • use it as a helpful security signal, not as proof

What Happens After Restart

If the MCP or host restarts:

  • the agent remains registered
  • the local session is gone
  • the agent must re-authenticate
  • if the key uses a PIN, the agent asks you for the PIN again

This is expected behavior.

Disconnect the Agent

If you want to remove the local MCP registration from a host:

  1. Run the MCP disconnect command or tool.
  2. Delete or rotate the agent key in UnoLock if you want full revocation.

Disconnecting locally removes the local host credentials, but it does not automatically delete the server-side access record.

Troubleshooting

The MCP says it needs a connection URL

Give it the agent key connection URL generated from an UnoLock Agent Key.

The MCP says the URL is the wrong type

You probably provided a normal access-key registration URL instead of an agent key URL.

The MCP asks for the PIN after restart

That is expected. The agent stays registered, but the PIN is not persisted in process memory.

The MCP says TPM or vTPM is not production-ready

Run the MCP TPM diagnostics and follow its advice. Some hosts support stronger device binding than others. The MCP can fall back to a lower-assurance software provider, but it should tell you when that happens so you can decide whether the host is acceptable for your Safe data.

The MCP says a write conflict requires reread

That means the underlying Space archive changed after the agent last read the target record. The agent should reread the record or Space, get the latest version, and retry only if the change still makes sense.

The MCP says a record is locked or the Space is read-only

That is expected behavior. The MCP surfaces the Safe's actual permissions and record lock state. A read-only Agent Key cannot write, and a locked record cannot be modified even by an rw agent.

UnoLock shows Device Assurance details for a key

That view is expected to show client-reported registration and device details. It is useful context for the Safe owner, but it is not independently verified by UnoLock.