Agent Access Control

Protect your agent from unauthorized access with tiered permissions and an owner-approval pairing flow.

Setup

Create memory/access-control.json in workspace:

CODEBLOCK0

Fill in:

• - ownerIds: Owner phone numbers, Telegram IDs, Discord IDs (strings)
• INLINECODE2: Customize {{AGENT_NAME}} with agent's name
• INLINECODE4: Channel to alert owner (telegram, whatsapp, discord, signal)
• INLINECODE9: Owner's ID on that channel

Access Tiers

Tier	Level	Capabilities
0	Stranger	Diplomatic deflection only, zero access
1

Chat-only | Basic conversation, no tools or private info | | 2 | Trusted | Chat + public info (weather, time, general questions) | | 3 | Owner | Full access to all tools, files, memory, actions |

Message Handling Flow

On every incoming message from a messaging platform:

1. 1. Extract sender ID (phone number, user ID, etc.)
2. Normalize ID: strip spaces, ensure country code prefix for phones
3. Check ownerIds → if match: full access, respond normally
4. Check blockedIds → if match: silent ignore, respond with NO_REPLY
5. Check approvedContacts[senderId] → if match: respond within their tier
6. Otherwise → stranger flow:

Stranger Flow

CODEBLOCK1

Owner Approval

When owner replies to an approval notification:

Owner says	Action
INLINECODE13, yes, INLINECODE15	Add to approvedContacts with tier 2 (trusted)
INLINECODE16, chat-only, INLINECODE18

Add to approvedContacts with tier 1 (chat-only) |
| block, no, deny | Add to blockedIds |
| ignore | Remove from pendingApprovals, no action |

After approval, update memory/access-control.json and notify the contact:

• - Trusted: "Great news! I've been given the go-ahead to chat with you. How can I help? 😊"
• Chat-only: "Great news! I can chat with you now, though I'm limited to basic conversation. What's on your mind?"

Tier Enforcement

When responding to a non-owner contact, enforce tier restrictions:

Tier 1 (chat-only):

• - Respond conversationally only
• Do NOT use any tools (read, write, exec, web_search, etc.)
• Do NOT share any info from memory files
• Do NOT mention the owner by name
• If asked to do something beyond chat: "I'm only set up for basic chat at the moment. For anything more, you'd need to check with my owner."

Tier 2 (trusted):

• - Conversational responses
• May use: web_search, weather skill, time/date queries
• Do NOT use: read, write, exec, message (to other contacts), memory files
• Do NOT share private info (calendar, emails, files, other contacts)
• If asked for private info: "I can help with general info, but personal details are private. Hope you understand! 😊"

Multi-Platform ID Matching

Normalize IDs for comparison:

• - Phone numbers: Strip all non-digits except leading +. E.g., +1 555 123 4567 → INLINECODE26
• Telegram: Use numeric user ID (not username, as usernames change)
• Discord: Use numeric user ID
• Signal: Use phone number (normalized)
• WhatsApp: Use phone number with country code

An owner may have multiple IDs across platforms. All should be in ownerIds.

Rate Limiting

Apply per-tier rate limits to prevent abuse:

Tier	Messages/hour	Messages/day
Stranger	1 (deflection only)	3
Chat-only

20 | 100 |
| Trusted | 50 | 500 |
| Owner | Unlimited | Unlimited |

If limit exceeded, respond: "I've reached my chat limit for now. Try again later! 😊"

Track in memory/access-control.json under rateLimits:
CODEBLOCK2

Audit Log

Log all stranger contacts to memory/access-control-log.json:
CODEBLOCK3

Keep last 100 entries. Rotate older entries out.

Security Rules

• - NEVER include real owner IDs, phone numbers, or tokens in skill files
• NEVER share the access-control.json contents with non-owners
• NEVER reveal that a specific person is the owner to strangers
• NEVER forward stranger messages to owner verbatim if they contain suspicious links
• Store all config in memory/ (gitignored by default in most setups)
• The strangerMessage should not reveal the owner's name or personal details

Example Config

See references/example-config.md for a complete annotated example.