Documentation · Setup Guide

Setup Guide

From download to first approval in under 5 minutes

IamAgent is a macOS app that sits between your AI agents and dangerous actions. When an agent tries to do something risky, you get a notification and approve it with Face ID on your phone. This guide walks you through downloading the app, running the setup wizard, and connecting the iOS companion app.

01 Quick Start

  1. Download IamAgent for Mac
  2. Open the app — the setup wizard launches automatically on first run
  3. Walk through the five wizard steps: Sign In → Install → Configure → Setup → Done
  4. Install the iOS companion app to approve actions from your phone

The whole process takes about 5 minutes. Most of it is automated — you just make a few choices along the way.

02 Setup Wizard

The wizard walks you through five screens. Here's what each one does and what choices you'll make.

Sign In

You'll sign in with your Google account. This creates your IamAgent account (or signs you into an existing one) and links the agents on this machine to your web dashboard.

Install

This screen installs dependencies and lets you toggle optional features.

Node.js (required)

Node.js powers the IamAgent CLI that runs on your machine. A compatible version is bundled inside the app — no separate installation needed.

Ollama + Gemma 4 (optional)

Gemma 4 is a local AI model (~3.6 GB) that runs privately on your Mac. It powers:

  • Smart rule suggestions based on your activity
  • Pattern detection across agent sessions

If you skip it, IamAgent still works — you just won't get AI-powered rule suggestions. You can install it later from the IamAgent menu bar. The download happens in the background while you continue setup.

MCP Server Discovery (optional)

Scans your agent configurations for installed MCP servers. When enabled, approval cards show you which external service is being accessed (e.g. GitHub, Slack, a database). Only server names and basic metadata are collected.

Approval Device Only

If you toggle this on, the wizard skips agent configuration entirely. This machine becomes a dedicated approval device — it can approve or deny requests from agents running on your other machines, but it won't run any agents itself.

Configure

This screen is where you name your agent, choose which tools to protect, and pick a security posture.

Agent Name

The wizard picks a random star name (like "sirius" or "vega") for your agent. You can change it to anything — lowercase letters, numbers, and hyphens, up to 32 characters.

AI Agents

The wizard scans your system for AI agents it can protect. For each agent type, you choose a scope:

  • All projects — one global agent policy for everything. Optionally restrict to a specific projects folder.
  • Per-project — a separate agent for each project folder. More granular control, but more to manage.

Security Posture

Baseline rules that decide what your agents can do without asking. Pick the one that matches how you use AI:

  • Developer Workstation (recommended) — permissive on dev tools, strict on deploy, publish, and install
  • Personal Assistant — permissive on reads and drafts, strict on sending emails, posting, and external actions
  • Restrictive — everything except reading files requires your approval

You can always adjust individual rules later from the web dashboard.

Setting Up

This screen runs automatically — just wait for it to finish. Behind the scenes, IamAgent:

  • Registers your agent(s) and links them to your account
  • Installs hooks so your AI tools route actions through IamAgent
  • Seeds your chosen security posture rules
  • Continues downloading Gemma 4 in the background (if you enabled it)

When it finishes, IamAgent moves to your menu bar and starts monitoring agent activity.

If you installed Gemma 4, a history analysis kicks off once the model download completes. It scans your recent activity to generate personalized rule suggestions. This can take a few minutes depending on how much history there is — you'll see progress on the Done screen, and the suggestions will appear in your web dashboard when ready.

03 Approving Actions

There are several ways to review and approve agent actions.

The IamAgent menu bar icon shows pending approval requests right on your Mac. You can approve or deny actions directly from the menu without reaching for your phone. If the notifications get noisy during a focus session, you can mute them from the menu.

Standalone Approval Device

If you'd rather not use the iOS app at all, you can install IamAgent on a second Mac and set it up as an "Approval Device Only" during the wizard. This gives you a dedicated machine for reviewing and approving requests from agents running on your other Macs.

iOS Companion App

The iOS app lets you approve or deny actions from anywhere — no need to be at your Mac.

Install

The iOS app is available via TestFlight. Tap the link on your iPhone to join the beta and install.

Sign In

Sign in with the same Google account you used on your Mac. That's it — no QR code, no pairing code, no manual linking. The shared account connects everything automatically.

Approving Actions

When an agent on your Mac tries to do something that needs approval, you'll see it in the Pending tab. Tap approve, confirm with Face ID (or passcode), and the agent continues. Denials are instant — no biometric needed.

Trust Windows

If you don't want to approve every action during a focused work session, you can open a trust window — a temporary period where actions are auto-approved. Choose a duration (15 minutes to 4 hours) and confirm with Face ID. You can limit it to specific agents or apply it to all of them.

History

The History tab shows an audit log of every action your agents requested and how it was resolved — approved, denied, or auto-allowed by a rule.

04 How IamAgent integrates with your agent

IamAgent is the authorization layer for whatever agent you run. It doesn't replace your tools — it sits in front of them, intercepting sensitive actions before they execute so you can approve or deny from your phone.

  • Claude Code (Live) — fully supported; the setup wizard installs everything automatically.
  • Codex (Beta) — supported via the same hook mechanism.
  • Hermes (Beta) — Hermes Agent by Nous Research, integrated through its shell hook system.
  • OpenClaw (Beta) — supported; lightly tested so far.

Under the hood, IamAgent installs a hook into each agent. Before the agent runs a tool (a shell command, a file write, an email send), the hook hands the action to IamAgent, which checks your rules and — when something is sensitive — escalates to your phone for a biometric approval. The agent waits for your answer, then continues or stops.

05 What stays local

IamAgent is a security product, so it's worth being precise about what touches the network and what never leaves your machine.

Your prompts, code, and file contents never leave your machine. Rule evaluation runs locally, and the optional smart-rule suggestions run on a local LLM (Ollama) on the same computer as your data — nothing about what your agent is doing is sent to us.

What does use the network, and why:

  • Action rulebase — your rules sync to your account so your agents enforce the same policy on every machine, and so you can manage and edit them from the dashboard. A rule is just the shape of an action — a tool or command pattern like git push* or a file-path — plus your decision: allow, ask, or deny. No source code, prompts, or file contents; just the pattern and the decision.
  • Approval notifications — when an action needs your sign-off, a push notification is sent to your phone via Apple's APNs. The notification carries a short summary of the action, not your source files or full prompts.
  • Device registration & sync — your agents and approval devices are linked to your account so the right phone gets the right prompt.
  • App & model downloads — the Mac app checks for updates and downloads the local LLM the first time.

Approvals are signed on-device with an Ed25519 key generated on your phone — the private key never leaves it. And there's no account beyond a Google sign-in: we don't store your prompts or code, so we literally can't see what your agents are doing.

06 Troubleshooting

Node.js not detected after installation

IamAgent bundles its own Node.js binary inside the app. If the wizard doesn't detect it, try quitting and re-opening IamAgent. If the issue persists, check that the app wasn't moved or modified after installation.

Agent not appearing in the web dashboard

After setup, the wizard links your agent to your account automatically. If it doesn't appear, make sure you completed the wizard through the "Done" screen. If the issue persists, try uninstalling and reinstalling the app to re-run the wizard.

iOS app not showing pending actions

Make sure you're signed in with the same Google account on both the Mac app and the iOS app. The iOS app polls for new actions every 10 seconds, so there may be a brief delay. Pull down to refresh.

Ollama download stalled

The Gemma 4 model is about 3.6 GB. If the download stalls, check your disk space and internet connection. You can retry later from the IamAgent menu bar.

Switching from Approval Device Only mode

If you set up this Mac as an approval-only device and want to switch to running agents, uninstall IamAgent (drag it to Trash) and reinstall from the download link. The setup wizard will launch again on first open.

Still stuck?

Reach out and we'll help you get set up.

[email protected]