OpenScopescoped, not open-ended
Try the demoDownload OpenScope

OpenScope Pilot Guide

OpenScope is a local application access broker for AI agents. It lets authorized agents access protected apps such as Apple Notes and Apple Mail via a policy-enforced, audited channel, without repeated macOS automation permission prompts.

Architecture Overview

AI agent
  -> openscope CLI          (thin client, invoked per request)
  -> openscoped daemon      (signed background process, holds macOS automation approval)
  -> Apple Notes / Apple Mail   (via in-process AppleScript)
  • openscope, CLI wrapper that sends requests to the daemon
  • openscoped, signed background daemon, enforces policy, executes app actions, logs audit events

Installation

Double-click OpenScope-<version>.pkg and follow the installer. No manual steps are required, the installer handles:

  • Copying OpenScope.app to /Applications
  • Registering and starting the openscoped background service
  • Installing openscope to /usr/local/bin
  • Creating ~/.openscope/ with a ready-to-use openclaw agent and default policy

After the installer completes, open a terminal and verify:

openscope status

You should see "running": true in the output.

If you have an older local config from previous pilot builds and want to reset it to the current app defaults, run:

openscope init --force

Granting macOS Automation Permission

The first time openscoped accesses Apple Notes or Apple Mail, macOS may show a one-time prompt. Accept it. You can also pre-grant via:

System Settings → Privacy & Security → Automation → OpenScope → Notes ✓ / Mail ✓

Quick Start

The installer creates an openclaw agent with default scoped access to Notes and Mail. For Notes, it has note list/read access but not list_folders. For Mail, it has read-only Inbox access. Run these immediately after install to confirm everything works:

# List notes in a folder (replace "Work" with a real folder name from your Notes)
openscope notes list_notes --agent openclaw --folder Work

# Read a note
openscope notes read_note --agent openclaw --folder Work --note "My Note"

# Read just the body (plain text)
openscope notes read_note --agent openclaw --folder Work --note "My Note" --body-only

# List up to 20 unread Inbox messages
openscope mail list_messages --agent openclaw --mailbox Inbox --limit 20 --unread true

# Read one Inbox message
openscope mail read_message --agent openclaw --mailbox Inbox --id "<message-id>" --body-only

Managing Agents

Register a new agent:

openscope agent register my-agent

List all registered agents:

openscope agent list

The openclaw agent is pre-registered by the installer.

Managing Policy

Policy rules control which agent can call which action, with optional parameter constraints. Rules are evaluated in order: deny overrides allow; no matching allow = deny by default.

Adding allow rules

# Allow access to a specific folder only
sudo openscope policy allow --agent my-agent --app notes --action list_notes --folder Work
sudo openscope policy allow --agent my-agent --app notes --action read_note  --folder Work

Adding deny rules

# Block access to a specific folder (overrides any allow)
sudo openscope policy deny --agent my-agent --app notes --action list_notes --folder Private
sudo openscope policy deny --agent my-agent --app notes --action read_note  --folder Private

Viewing policy

# Show all rules
openscope policy list

# Show rules for one agent
openscope policy show --agent openclaw

Validating policy

openscope policy validate

Try it: block a folder and verify the deny

  1. Create a folder called Private in Apple Notes and add a note to it.

  2. Confirm the openclaw agent is denied because the folder name matches the protected blacklist:

openscope notes list_notes --agent openclaw --folder Private
  1. Review the blacklist:
openscope notes blacklist list
  1. Add another protected keyword if needed:
sudo openscope notes blacklist add secret
  1. Confirm the audit log captured the deny decision:
tail -5 ~/.openscope/audit.jsonl

Apple Notes Actions Reference

list_notes

List notes in a folder.

openscope notes list_notes --agent <agent-id> --folder Work

{"ok": true, ..., "data": [{"title": "Weekly Notes"}, {"title": "Project Alpha"}]}

read_note

Read a note's body.

openscope notes read_note --agent <agent-id> --folder Work --note "Weekly Notes"

{"ok": true, ..., "data": {"title": "Weekly Notes", "body": "..."}}

Body-only mode (plain text, useful for piping into other tools):

openscope notes read_note --agent <agent-id> --folder Work --note "Weekly Notes" --body-only

Apple Mail Actions Reference

list_messages

List messages in a mailbox. The default openclaw policy allows this only for Inbox.

openscope mail list_messages --agent <agent-id> --mailbox Inbox --limit 20 --unread true

{"ok": true, ..., "data": [{"id": "...", "subject": "...", "sender": "...", "unread": true}]}

read_message

Read a message body by message id. The default openclaw policy allows this only for Inbox.

openscope mail read_message --agent <agent-id> --mailbox Inbox --id "<message-id>"

Body-only mode:

openscope mail read_message --agent <agent-id> --mailbox Inbox --id "<message-id>" --body-only

Checking Status

openscope status

Shows daemon liveness, socket path, config directory, and registered agent/app counts.

Diagnostics

openscope doctor

Runs checks on config layout, policy validity, daemon reachability, and agent registry.

Reviewing the Audit Log

Every allow and deny decision is recorded in ~/.openscope/audit.jsonl.

tail -20 ~/.openscope/audit.jsonl

Each line includes: timestamp, agent, app, action, parameters, decision, and reason.

Troubleshooting

Daemon is not running

# Check daemon log
cat /tmp/com.ezblock.openscope.openscoped.stderr.log

# Restart the daemon
launchctl kickstart -k gui/$(id -u)/com.ezblock.openscope.openscoped

Request denied unexpectedly

# Check what rules apply to your agent
openscope policy show --agent openclaw

# Check the audit log for the deny reason
tail -5 ~/.openscope/audit.jsonl

macOS Automation permission missing

  • Ensure OpenScope.app is in /Applications (signed copy, not a dev build).
  • Open System Settings → Privacy & Security → Automation, find OpenScope, enable Notes and Mail.

daemon unavailable error

ls ~/.openscope/run/openscoped.sock   # should exist
openscope status

If the socket is missing, restart via launchctl kickstart (see above).

Configuration Directory

~/.openscope/
  agents.yaml          # registered agent identities
  policies.yaml        # access rules
  audit.jsonl          # append-only audit log
  apps.d/              # user-defined app definitions (optional)
  state/
    enabled_apps.yaml  # which user-defined apps are enabled
  run/
    openscoped.sock       # daemon Unix socket

App Management (Advanced)

openscope app list                          # list all apps (bundled + user-defined)
openscope app show notes                    # show details for a specific app
openscope app validate /path/to/myapp.yaml  # validate a custom app definition
openscope app enable myapp                  # enable a user-defined app
openscope app disable myapp                 # disable a user-defined app

Bundled apps (like notes) are always enabled.

View raw markdown ↗← All docs