1Getting started
Three ideas carry the whole product:
- We can't read your secrets. They're encrypted on your device (in the browser, or in the desktop app and command line) before they're uploaded. Even their names are hidden from the server.
- Approve the bot. An agent asks before it reads secrets; you approve on your phone or the website.
- Approve the action. Through connectors, an agent also asks before it sends an email, merges a pull request, deletes something, or runs a command as root. Your rules decide what asks and what doesn't.
The usual path:
- Sign in (new here? create a free account; during the beta new accounts are approved by hand). Save the recovery key shown at sign-up.
- Make a project for one bot, app or environment, and add its secrets (2).
- Make a machine token for the agent (3), and install the client on the agent's machine.
- Turn on connectors if the agent should act in other apps (Gmail, GitHub, your own), and set its rules (6).
- Optional: approvals on your phone (5), passkeys and two-factor sign-in (12).
2Projects and secrets
A project holds the secrets for one purpose: one bot, one app, one environment. A token reads only its own project, so keep projects narrow: an agent that only reads mail shouldn't sit in a project with your cloud keys.
- Add, change, reveal, delete secrets on the website (Secrets tab), in the
swadmindesktop window, or withswctl admin secret set PROJECT NAME(the value is read from a prompt, never from the command line). - Values are shown only when you choose Show value. Copied values are cleared from the clipboard after a minute.
- Invisible and control characters are refused, which catches a broken copy-paste before it's stored.
3Machine tokens
An agent never gets your keys directly. It gets a machine token: one per bot or machine, able to read only its project, and limited by your settings.
- Create it under the project's Tokens tab. The steps that follow set its approval, connectors, the agent app's MCP settings (with copy buttons) and a one-time setup code. The agent's machine stores the token from the code, readable only by its user. No long token is copied around.
- Allowed client addresses: the token works only from the IP addresses or ranges you list. Tokens that work from any address show a warning badge. You can change this any time without reissuing the token.
- Expires after: an end date, if you want one.
- Revoke: the token stops on its next request, and anything it was waiting for is cancelled. The agent goes back to set-up.
- Rotate: a replacement token; the agent's existing settings follow the new one.
4Approving secret reads
Each token's Human approval setting decides whether a person is asked before it gets secrets:
| Choice | What happens |
|---|---|
| Once per session (default) | The first read asks. After you approve, the agent reads without asking until the session ends (8 hours by default, up to 24 hours). |
| Every time it reads secrets | Every read asks, and each approval works once. For high-value keys. |
| No, never | No approval. Shown with a warning; choose it on purpose. |
- Match codes: every request shows a short number on the agent's side and in your prompt. Approve only if they match.
- Started by: a session request shows which programs started the agent's client (as the machine reports it), so you can tell "hermes gateway" from code the agent wrote and ran itself.
- Limits: how long a request waits, how many may wait at once, and how many per hour, so an agent can't flood you into tapping Approve. No time limit and No hourly limit are there if you need them.
- Where you approve: the website's Approvals page (live), the
swadminwindow, and phone channels (5).
5Approvals on your phone
Each project's Approval setup tab connects phone channels. Each has a Send a test button.
- Telegram: a bot of your own (from @BotFather). Approve, Deny or Deny with comment buttons, and replies for comments.
- ntfy: a push notification with Approve and Deny buttons. The topics are generated for you.
- Discord: a message with Approve, Deny and Deny-with-comment buttons in a channel you choose.
Then pick the channels per token (Ask in). One bot can serve several projects; a button press only counts through the bot and chat of the request's own project.
Phone channels are a convenience, not a security feature: every plan can approve everything on the website and
in swadmin. On the Free plan they come with a 14-day trial that starts when you connect your first
phone channel. When a trial or plan ends nothing breaks: approvals fall back to the website, and your settings
stay saved.
6Approving actions: rules
With connectors, aiSecurityWarden sits between the agent and the apps it uses, and every action goes through the token's Rules:
| Rule | Example | What happens |
|---|---|---|
| Allow | gmail.read.*=allow | Runs, and is logged. |
| Time window | gmail.label=window:30m | The first request asks; the same kind of action is then allowed for that long (1 minute to 24 hours). |
| Ask every time | gmail.send=each | Every one asks. |
| Deny | github.repo.delete=deny | Refused, no question asked. |
- Anything without a rule asks first. Each connector comes with suggested rules you add with one click: they ask for every high-risk action (send, forward, delete, merge, push). You can loosen any rule; the rules box points out each line that lets a high-risk action run without asking, and lines that match no action (a typo). The first matching rule wins.
- Rules by argument: a rule can match what an action is about, e.g.
github.pr.merge[repo=acme/website]=allowwithgithub.pr.merge=eachbelow it.acme/*matches every repository of acme. The values are stored as keyed hashes, so the server matches them without reading them. - Changes apply to the agent's next request: nothing to restart. And the rules live in aiSecurityWarden, not on the agent's machine, so a confused or compromised agent can't loosen them.
- What you approve is what runs: each request carries a fingerprint of the exact action; a changed action is refused.
- Deny with comment: tell the agent what to change ("shorter, and cc Dana"). It revises and asks again; a plain Deny stops it.
- Waiting doesn't block: the agent hears "waiting for approval" right away and can check back.
- What the phone shows (per project, Shown in phone messages): full details (recipient, subject, preview), or only the action name, with the details end-to-end encrypted and reviewed on the website.
- Outside content is marked untrusted to the agent (emails, web pages, tool results), which makes prompt injection harder.
7Gmail
The Gmail connector gives the agent: search, read, read thread, list labels, label, archive, mark read, draft, send, reply, forward (with the original's attachments), read an attachment's text and trash. Suggested rules: read freely, tidy up with a time window, approve every send and delete. There's no permanent delete: trash only.
Attachments: send, reply, forward and draft can attach up to 10 files (18 MB together): files the agent saved in its outbox folder, short text it wrote, or attachments of an email in the mailbox. The approval request lists each file's name, size, type and fingerprint, and the approval covers exactly those files. The agent can also read the text of PDF, Word and text attachments.
Google Drive links (client 0.7.10): files too big for Gmail, or of a type Gmail blocks, go to a folder "aiSecurityWarden shared" in your Google Drive, and the email carries the link. You can also ask the agent to send a file as a Drive link. Only the email's To and Cc recipients can open it, view only, each by their own address; it is never shared with "anyone with the link". The approval request shows exactly who gets access. Needs the Google Drive API enabled in your Google Cloud project and Google Drive ticked when you sign in.
Connect Gmail (on the project's Secrets tab) walks you through it. Once connected, the same tab shows Reconnect Gmail (sign in again, keeping the Google client), Disconnect Gmail, and when the Google sign-in ends (7 days after signing in for an app still in Testing). Connecting:
- Create a Google Cloud project, enable the Gmail API (and the Google Drive API for Drive links), add yourself as a test user and create an OAuth client (about 10 minutes, with each step shown). See Testing, or publishing your Google app to avoid the 7-day sign-out.
- Sign in with Google in your browser.
- The Google sign-in token is encrypted in your browser and stored as a secret of the project. Our server never sees it, and the agent's machine never signs in to Google.
During the beta you use your own Google Cloud app; a verified aiSecurityWarden app comes later. Already connected before Drive links? Enable the Google Drive API, then press Reconnect Gmail and tick Google Drive.
Testing, or publishing your Google app
On Google's Audience page choose External and add the Gmail address the bot will use under Test users. That is enough to connect, but while the app is in Testing, Google signs the bot out every 7 days: press Reconnect Gmail (the project's Secrets tab) when it happens. Using Google Workspace? Choose Internal instead (the Google Cloud project must be created with your Workspace account): no test users, no publishing, no 7-day sign-out.
To stop the weekly sign-out, publish the app. Google first wants the Branding page complete: a home page, a privacy policy and terms of service on a domain you own. Point them at your own pages, not aisecuritywarden.com: the app is yours, and Google's rules say to use only domains you own. If you have no website, a free GitHub page works:
- Sign in to GitHub (a free account is fine) and create a public
repository named exactly
YOUR-USERNAME.github.io. - In it, add three files (Add file → Create new file):
index.html,privacy.htmlandterms.html, using the text below. Replace the words in capitals. - In the repository's Settings → Pages, set the source to Deploy from a branch, branch
main, folder/ (root). After a minute or two the pages open athttps://YOUR-USERNAME.github.io/. - On Google's Branding page enter:
home page
https://YOUR-USERNAME.github.io/, privacy policyhttps://YOUR-USERNAME.github.io/privacy.html, termshttps://YOUR-USERNAME.github.io/terms.html, and the authorized domainYOUR-USERNAME.github.io. Save. - On the Audience page press Publish app and confirm. Google may say the app needs verification: that is only for apps offered to the public, and you don't need it for your own bot. Sign-ins show "Google hasn't verified this app" (choose Advanced, then Go to your app); the app is limited to 100 users.
- Press Reconnect Gmail in aiSecurityWarden once (and choose "In production"), so the bot gets a sign-in that no longer expires after 7 days (sign-ins made while in Testing still do).
index.html:
<!doctype html><meta charset="utf-8"><title>YOUR APP NAME</title>
<h1>YOUR APP NAME</h1>
<p>A private Google Cloud app used only by YOUR NAME to let their own AI assistant work with their own
Gmail account (and Google Drive files the app uploads) through aiSecurityWarden. Every sensitive action,
such as sending an email or sharing a file, is approved by the account owner first.</p>
<p><a href="privacy.html">Privacy policy</a> · <a href="terms.html">Terms of service</a></p>
privacy.html:
<!doctype html><meta charset="utf-8"><title>Privacy policy: YOUR APP NAME</title>
<h1>Privacy policy</h1>
<p>YOUR APP NAME is used only by YOUR NAME with their own Google account. It reads, organizes and sends
Gmail messages, and uploads and shares Google Drive files it created, only for actions the account owner asks
for and approves. The data stays between Google and the owner's own computer; it is not sold, shared with
third parties or used for advertising. Use of information received from Google APIs follows the Google API
Services User Data Policy, including the Limited Use requirements. Access can be removed at any time at
https://myaccount.google.com/permissions. Contact: YOUR EMAIL.</p>
terms.html:
<!doctype html><meta charset="utf-8"><title>Terms of service: YOUR APP NAME</title>
<h1>Terms of service</h1>
<p>YOUR APP NAME is a private app for YOUR NAME's own use. It is not offered to anyone else and is
provided as is, without warranty. Contact: YOUR EMAIL.</p>
After an update the agent still shows old tools (for example no Drive option): the agent app kept its old
tool list. Restart the program the update named, then open a new chat. Hermes also keeps tool lists in
~/.hermes/cache/mcp_schema_cache.json; if the old list survives a restart, stop Hermes, delete that
file, and start it again. Don't let the agent kill processes or edit its own files to get there.
8GitHub and other MCP servers
The approval proxy puts aiSecurityWarden in front of an existing MCP server. Every tool call goes through the same rules, approvals and log, and you write no code.
- GitHub is built in: it sits in front of GitHub's official MCP server (local, or GitHub's hosted HTTP endpoint), with its tools mapped to actions and risks. Reading is low risk; creating issues and pull requests asks; merging, pushing and deleting are high risk.
- Any other MCP server:
sw-mcp proxy-initdrafts a mapping file (.swproxy) from the server's live tool list. Tools with names like delete, merge, push, send or pay start as high risk. Review it and upload it in Connectors. Tools missing from the mapping are refused or ask first. - Tool-list pins: if a server changes what its tools say (a known way to trick agents), nothing runs until you approve the new tool list. No rule can skip that.
9Custom connectors
For apps without a built-in connector (internal tools, niche APIs, home automation):
sw-mcp new-connector my_crm
sw-mcp check --connector my_crm
sw-mcp pack my_crm
new-connectormakes a starter project, with instructions written for AI coding assistants;checkrefuses mistakes and flags suggested rules that would let a high-risk action run unasked;packmakes the one file you upload.- Ask your AI assistant to build it:
sw-mcp guideprints the guide to give it. A testing kit runs without the real app. - Upload once in Connectors (Upload…), preview its tools and risks, and turn it on per project. It's encrypted like a secret, and only machines whose project has it turned on can read it.
- Updates reach agents automatically. The previous version is kept as a backup, a failing new version leaves the old one running, and machines refuse to roll back to older versions.
- Connectors run on your machines, never on ours. The connector author writes no approval logic, and a connector can't give an agent more than your rules allow.
10Connecting agents
Any agent that speaks MCP works. Tested with Claude Desktop, Claude Code and Hermes Agent. The install guide has the steps per app and system. In short: install the client, paste the MCP settings the website shows when you create the token, give the agent the setup code.
- Tools straight away: the agent sees its tools at start-up, even while its session waits for approval; the first call asks.
- Teach it the rules:
sw-mcp skill install hermes(orclaude) installs a skill that explains approvals, waiting and denials to the agent. - Check the set-up:
sw-mcp doctorgoes through token, server, approval, connectors and tools, and says whether a short tool list comes from aiSecurityWarden or the agent app. It never prints a secret. - Bots and scripts without MCP:
swctl exportprints the secrets for a start-up script, andswctl run -- your-programstarts a program with them in its environment. Values never appear on the command line or in shell history. - Updates: ask the agent to "update aiSecurityWarden" (you approve the exact version), or run
sw-mcp update. Only releases signed by aiSecurityWarden install. Then restart the program the update names: the one that actually runs aiSecurityWarden for the agent (for Hermes often the dashboard or gateway, not the desktop app). The agent tells you what to restart and restarts nothing itself.
11Root commands with approval (sw-sudo, Linux)
Run your agent as its own limited user. When it needs root, it asks for one exact command, and you see the command, the machine and the agent's reason before you approve. The agent never gets the root password, and can't read the helper's token.
sudo sw-sudo -- apt install -y ffmpeg
sudo sw-sudo --reason "the user asked for video conversion" -- apt install -y ffmpeg
Needs client 0.7.6 or newer. Set-up:
- Install the client for root, so the agent's user can't change what runs as root:
sudo pipx install --global aisecuritywarden. - On the website: a project with no secrets (e.g. "jarvis root") and a token in it named
sw-sudo. Set its Human approval to No, never (it reads no secrets; every command is approved by its rules), set Allowed client addresses to the machine, and add rules, for example:system.run[cmd=apt/update]=allow system.run[cmd=systemctl/status/*]=allow system.run[cmd=apt/install/*]=each system.run=eachcmdis the command and its arguments joined by/, so[cmd=apt/install/*]matches anyapt install …. - On the machine:
sudo sw-sudo install --agent-user hermes --sudo-shim, and type the token's setup code. It stores the token for root only, adds one checked sudoers line, and puts a smallsudoin/usr/local/lib/securitywarden/bin. - Make sure the agent's user has no other sudo rights (
sudo -l -U hermes), put/usr/local/lib/securitywarden/binfirst in the agent's PATH (in its service settings), and restart the agent.
How the agent knows. Its aiSecurityWarden connection offers it a system_run tool for root
commands: it gets "waiting for approval" with a match code at once and checks back, like any other approval. Its
built-in instructions and skill say to use that tool (or sudo sw-sudo -- … in a terminal), and the
small sudo turns a plain sudo COMMAND into a request too. Without any of these, plain
sudo simply fails: nothing runs as root without your approval either way.
Refused before you're asked: shells, interpreters and other programs that run commands (approving
bash -c … would hand over root), user and sudo management, programs or files the agent could change
(including anything in /tmp), options that run commands (apt -o, find -exec
…), and sudo, password and aiSecurityWarden files. The command runs once, with no shell, a clean environment, a
time limit and capped output. If the program file changes after you approve, it doesn't run.
12Your account
- Two-factor sign-in: any authenticator app (Microsoft Authenticator, Google Authenticator, 1Password, Authy, Bitwarden…), with single-use recovery codes. Your server operator may require it for everyone.
- Passkeys (fingerprint, face, Windows Hello, Android), under Account, Passkeys, all optional:
- Sign in with a passkey: on devices that support it, this signs in and unlocks your encrypted data without the password, still end to end;
- passkey as the second factor instead of the authenticator code;
- fingerprint to approve: approving on the website then needs the passkey, so an unlocked device left lying around can't approve.
- Change password: your data doesn't need re-encrypting.
- Sign out everywhere ends every session. You're signed out after 15 minutes without activity, and after 12 hours in any case; after a page reload only your password (or passkey) is asked again.
- Appearance: dark by default; light, or follow your device.
13Security model
- Zero-knowledge by architecture: the server never receives your password, your keys, or secret names or values. Encryption is AES-256-GCM with keys from PBKDF2-SHA256 (600,000 iterations) and HKDF, using only well-known libraries. The protocol and its test vectors are published with the open-source client.
- The gate: each time an agent wants secrets or wants to act, a person can be asked, and every use is logged. Approval protects the moment of access; for what an agent can do after that, give it narrow, short-lived credentials.
- Browser or desktop: the website encrypts in your browser, but a web page runs code the site delivers,
so you trust that code. The desktop window (
swadmin) andswctldo the same encryption entirely on your computer, from open-source code you can check.
What if my agent can run code on its machine?
Then it can start its aiSecurityWarden tools by itself, even ones its agent app doesn't list. Every request still goes through the same approvals and rules on the server, and session requests show what started them. To keep an agent to its own tools, turn off its code or terminal tool, or run it as its own user.
Can I let an agent send or delete without asking?
Yes: your rules decide. The suggested rules ask for every high-risk action, and the rules box warns about each line that loosens that. A time window is usually better than Allow, for example 30 minutes for a big inbox clean-up. One thing always asks, whatever the rules: approving a connected MCP server's changed tool list.
14Recommended set-up
- Approval at least once per session for bot tokens (the default); every time for high-value projects.
- Allowed client addresses on every bot token.
- Start from the suggested rules; loosen only what you need (a time window beats allow).
- One project per purpose; narrow, read-only, expiring credentials from your vendors.
- Run agents as limited users, never as root or Administrator; root only through sw-sudo.
- A passkey to approve; turn phone channels off for tokens that should need it.
- After anything suspicious: revoke the token, rotate the vendor credentials, and check the activity log.
15What we store
| Stored on our server | Never on our server |
|---|---|
| Secret values and names, encrypted on your device (the names as keyed hashes) | Readable secret values or names |
| Your project keys, wrapped (encrypted) under keys only you and your tokens hold | Your password, recovery key, account key or project keys |
| Hashes (Argon2id) of your sign-in and recovery proofs | Anything that would let us sign in as you or decrypt your data |
| Your email, account settings, token names, allowed addresses and rules (values in rules by argument as keyed hashes) | The apps' credentials connectors use (stored as your encrypted secrets) |
| Approval requests and the activity log: who, what action, when, from which address. Action details only if the project shows them in phone messages; otherwise encrypted | Your email, code or other app content: connectors run on your machines and talk to the apps directly |
| Phone channel settings (bot tokens, topics), encrypted at rest with a server key |
One honest note: with any AI connector, ours included, what the agent reads goes to the AI provider (for example Anthropic or OpenAI), because the model has to read it. Our promise is that aiSecurityWarden never sees it.
16Activity log
The Activity page shows every sign-in, approval, denial, action, setting change and connector download: who, what and when, what started each session request, and passkeys added or removed. Warnings appear there too, for example when a proxied MCP server runs as the agent's own user. Every plan has it; plans differ in how long it goes back. Export to CSV or JSON is coming soon.
17Troubleshooting
- The agent says it's waiting for approval, but nothing arrives. Check the token's Ask in channels and the project's Approval setup (Send a test). Everything can always be approved on the website's Approvals page.
- Telegram buttons do nothing. Another program reads the same bot, usually the AI agent's own Telegram bot. Use a bot only for aiSecurityWarden.
- "Address not allowed". The token's Allowed client addresses don't include the machine's current address (home connections change address now and then). Update them on the website.
- The agent shows fewer tools than expected. It read the tool list before you approved its session: start
a new session.
sw-mcp doctorsays which. - An action keeps asking although I allowed it. Rules apply top to bottom and the first match wins: a broader rule above may match first. The rules box shows which line applies.
- sw-sudo says "refused". The message says which guard.
sudo sw-sudo check -- COMMANDshows what would be asked without asking. - Lost your phone? Sign in with a recovery code. Lost those too? Your server operator can reset your two-factor sign-in; your data isn't affected.
- Install problems: see the install guide.
- Still stuck? Contact us, with what
sw-mcp doctorsays (it contains no secrets).