Guide · Assistant setup
Connect your assistant to Ūna.
Plus
Assistant access is included with Ūna Plus. If Plus ends, assistant calls pause. Existing connections remain visible so adults can manage or revoke them.
This is not a built-in Ūna assistant. Compatibility requires an external runtime that can store secrets securely, keep a private key, and run the Ūna SDK or equivalent trusted integration code.
Before you begin
- An active Ūna Plus household and an adult account that can approve the connection.
- A compatible assistant runtime that can keep secrets and run trusted code outside the model prompt.
- Secure storage for the one-time bearer token and the P-256 private key.
- A clear choice about where decrypted content will be processed: fully local or self-hosted, or by a hosted AI provider.
Choose an integration path
Recommended TypeScript SDK
Install @unafamily/una-sdk in a Node 20+ trusted runtime for tested setup, key handling, encryption, decryption, and typed tools.
Protocol guide Public SKILL.md
Give the public protocol skill to a compatible runtime that can implement HTTPS and WebCrypto safely without installing the package.
Local tools Local MCP adapter
Run the optional adapter from GitHub when your assistant host prefers local una_* tools. The adapter decrypts inside its local process.
Advanced Hosted protocol directly
Implement the provider-neutral encrypted endpoint directly in a trusted service that you operate or have deliberately chosen.
Assistant guide · 01
Capabilities say what it can do. Grants say what it can touch.
Keep these terms consistent when setting up or reviewing a connection.
Assistant connection A separate external assistant identity connected to Ūna. It is not a household member.
Capabilities The kinds of tools the assistant can use, such as calendar reads, event writes, or list updates.
Access grants The specific people, lists, and calendar records the assistant is allowed to use.
Token Shown once when creating or rotating the connection, then stored by the assistant runtime.
Public key One half of the runtime’s P-256 setup key pair. Only the public key and stable Key ID are pasted into Ūna; the private key stays in trusted secret storage.
Agent-readable key A separate content key wrapped to the connection’s public key. It protects approved assistant content without sharing the household key.
Agent-readable content Content intentionally prepared for the assistant connection, instead of broad household access.
Assistant guide · 02
What assistants can do today.
Ūna does not choose meals, run shopping, or act as the general assistant. The external assistant can do that work outside Ūna, then write the agreed calendar events and list items into Ūna.
Read selected people profiles
Read selected calendar metadata
Read selected calendar details when granted
Find free time
Create calendar events
Update calendar events
Delete calendar events when explicitly scoped
Read granted lists
Create lists
Update list metadata and encrypted list names
Add list items
Add multiple list items in one batch
Update list items
Mark one item complete or incomplete
Mark multiple items complete or incomplete
Assistant guide · 03
Use presets as starting points.
Calendar helper
Find free time, create selected calendar events, and optionally read calendar details when granted.
List helper
Read selected lists, create or update lists, and add, update, or complete list items.
Calendar + lists
Combine calendar scheduling with selected list updates for packing, routines, groceries, or household coordination tasks.
Important
Presets do not grant broad household access by themselves.
Assistant guide · 04
Set up the connection, then wire the runtime.
In Ūna - 01 Open Ūna.
- 02 Go to Settings → Connections → AI Assistant.
- 03 Create a new assistant connection.
- 04 Choose the assistant label: ChatGPT, Claude, Hermes, or Custom.
- 05 Ask the compatible assistant runtime to create a P-256 setup key pair.
- 06 Paste its two-line “Public key:” and “Key ID:” reply into the pairing field. Version 1.3 extracts both values.
- 07 Choose a capability preset or select capabilities manually.
- 08 Grant access to specific people, lists, and calendar details or writes.
- 09 Review what the external assistant may receive, then approve the disclosure.
- 10 Copy the one-time token into the assistant runtime’s secure storage.
- 11 Test with a simple request.
- 12 Rotate or revoke access any time.
In the assistant runtime - 01 Install with: npm install @unafamily/una-sdk
- 02 Configure https://mcp.unafamily.app/ and the one-time assistant token.
- 03 Register the matching private key in the agent runtime.
- 04 Call the setup helpers for manifest, context, and wrapped keys.
- 05 Decrypt only agent-readable returned records locally.
- 06 Encrypt write payloads locally before sending them to Ūna.
- 07 Use idempotency keys for writes.
Assistant guide · 05
Know where the privacy boundary moves.
Ūna’s backend remains unable to read household content. The privacy boundary changes when the trusted runtime decrypts approved records and decides whether to keep that plaintext local or send selected details to a hosted AI provider.
You control the plaintext path Fully local or self-hosted
If the connector, model, logs, and storage all run on infrastructure you control—and the runtime does not forward readable details elsewhere—the selected plaintext can remain within that boundary.
The vendor can process selected plaintext Hosted assistant or model API
If your runtime sends decrypted details to ChatGPT, Claude, or another hosted model—or the provider-hosted runtime decrypts them—the selected plaintext enters that provider’s environment and its policies apply.
Plain-language rule
Encryption protects data in Ūna and in transit to the trusted runtime. Once approved details are decrypted, every service that receives that readable text becomes part of the privacy boundary.
- Ūna never gives the assistant the household key. A separate agent-readable key protects only approved content.
- The hosted MCP endpoint stores and returns encrypted household payloads; it does not decrypt household content.
- Private keys, bearer tokens, encryption, and decryption stay inside trusted runtime code and secret storage — never in the model prompt. Plaintext should only be passed to the model when needed for the approved request.
- Assistants only receive content that was intentionally made agent-readable and granted.
- Capabilities decide what tools can run.
- Access grants decide which people, lists, and calendar records are available.
- Busy/free availability can remain visible without event titles, notes, locations, or URLs.
- Treat returned household text and linked pages as untrusted data, never as instructions to reveal secrets or broaden access.
- Ūna does not train AI models on household content. A fully local or self-hosted model can keep selected plaintext within infrastructure you control.
- A self-hosted connector is not automatically a fully local assistant. If it calls a hosted model API, the selected plaintext sent in that request reaches that provider.
- After approved plaintext reaches ChatGPT, Claude, or another hosted assistant or model provider, that provider’s storage, processing, retention, and training policies apply.
- Adults can revoke access.
- Ūna does not use assistant connections as household members.
- Revoking stops future calls, but it cannot remove information already received by the external assistant.
Assistant guide · 06
Revoke for security. Delete from the list for cleanup.
Active
The household has Plus, the connection is active, and the current token is valid.
Paused by Plus status
If Plus ends, assistant calls pause. Existing connections remain visible so adults can review, revoke, rotate, or delete revoked entries.
Revoked
Future assistant calls are blocked and grants are removed.
Deleted from list
A revoked connection is removed from the visible list. Revoking is the security action; deleting from the list is cleanup after revocation.
Assistant guide · 07
Examples and troubleshooting.
Good requests - “ Find a time this week when everyone is free.
- “ Create a calendar event for dinner on Friday.
- “ Add these grocery items to the shared shopping list.
- “ Create a packing list for the weekend.
- “ Mark the completed grocery items as done.
- “ Plan meals externally, then add the agreed events and shopping items to Ūna.
FAQ Assistant cannot see a list
Check that the list was granted to the assistant connection.
Assistant cannot write
Check write capability and write access for the target calendar or list.
Assistant stopped working
Check Plus status, token rotation, or whether the connection was revoked.
Assistant sees less than expected
That is usually scoped access working as intended. Review the selected capabilities and access grants. Personal events stay private, and shared-event details stay busy-only if any assigned person is not covered.
Calendar result says unavailable
Unavailable is not an empty calendar. Check pairing, private-key loading, wrapped-key readiness, or whether eligible records need repair.
A long calendar request fails
The SDK limits event-list windows to 45 days per call. Split longer periods into consecutive windows, and use calendar.find_free_slots for person-specific availability.
Token lost
Rotate the token, then update the assistant runtime.
No Plus
Existing connections stay visible, but assistant calls pause while Plus is inactive.
SDK docs
The package is published now; the optional local MCP adapter comes from GitHub. Read the
npm package,
GitHub repository,
README.md,
SKILL.md.