Chapter 2 — Accounts and sign-in
AgentWitch is a signed-in product: your Tasks, Runs, paired Macs, and saved Playbooks belong to your user (and optionally your team). This chapter covers how you get in, what an account controls, and how sign-in relates to Connect this computer.
For vocabulary (Mac, Task, Run, Playbook), see Chapter 0.
#Where you sign in
| Surface | URL | Notes |
|---|---|---|
| Production | https://www.agentwitch.com/login | Magic link and/or Google, per environment config. |
| Local dev | http://localhost:3000/login | Engineers use .env.local auth secrets; test accounts available—see below. |
After sign-in, you land in the Console (Home, Projects, Runs). Marketing pages without a session do not probe your computer for identity (browser knows this computer).
#Sign in from the public site (Reports)
On the marketing homepage header, Reports is for signed-in work history—not a separate public page. If you are not signed in, AgentWitch sends you to Sign in with a return URL so that after a successful login you open Projects with the Reports intent (/projects?intent=reports), same as the in-app Reports tab (Chapter 3 — navigation). Bookmark /reports still redirects into a project; the header link uses the login callback so anonymous visitors authenticate first.
#Sign-in methods
#Google OAuth
When enabled, Continue with Google creates or links a user record in AgentWitch’s database (NextAuth + Neon). Use the Google account your organization expects—team features and admin roles may depend on email domain or manual promotion.
#Email magic link
When Resend (or your configured provider) is set up:
- Enter your email on Sign in.
- Open the link in the email (same browser recommended).
- You receive a session cookie for
www.agentwitch.com.
Honest UX: Links expire; requesting many links in a row can rate-limit. Use one tab; avoid forwarding magic links—anyone with the link can sign in as you.
#Test sign-in (development and QA only)
On localhost (or when ALLOW_TEST_AUTH=1 in non-production builds):
- Emails matching
test*@agentwitch.comcan sign in from/loginwithout email delivery. - Scripts like
npm run test:auth:sessionprint cookie values for automation.
This bypass is off on production www.agentwitch.com for security. Details: Local setup — test auth.
#What your account owns
| Owned by you (cloud) | Lives on the computer |
|---|---|
| Paired Mac rows (device name, presence, pairing token hash) | Pairing token secret, harness/playbook files, writer session transcripts |
| Runs / reports history | Shell execution, project folders on disk |
| Saved capabilities, library drafts (after sync), workflow runs | Installed playbook files under ~/.agent-witch/harness/ |
| Playbook context (estimate) per project (paths, sizes, approx. tokens; last sync time) | Materialized rule files in the repo (for example under .cursor), reported when your Mac links or syncs playbooks |
| Optional Cursor Cloud API keys (if configured) | Local CLI binaries (Cursor, Claude Code, etc.) |
The estimate on Resources is a planning hint, not billing or live agent usage. See playbook context estimate Q&A.
Signing out of the browser does not uninstall the computer helper. Uninstalling the computer helper does not delete cloud run history—it may mark the computer Offline until you remove or reclaim the device.
#Solo vs company (same account, different chrome)
AgentWitch uses one codebase with persona gates in navigation:
| Mode | What you typically see |
|---|---|
| Solo maker | Home, Projects (with New task inside each project), Runs, Marketplace (official playbook install), Playbooks (/library), account menu. |
| Company / team | Same core loop plus team visibility on Runs, shared Playbooks, fewer solo-only growth surfaces; Automations may appear when team nav is enabled. |
Exact nav labels follow UX simplification. Your org may enable groups without changing how Mac pairing works.
Team learning (Chapter 0 — four pillars) starts here: the same account can see shared Runs, install org Playbooks from Marketplace, and reuse templates in Library—not only private one-off prompts. Solo makers still pair a Mac the same way; company mode adds visibility and shared standards.
Admins (super-admin or team admin) may see extra routes (user management, policy). Those are not part of every user’s Home checklist.
#Pairing a computer to your account
Pairing is the bridge between account and machine:
- Sign in on the Mac’s browser (same machine as the install).
- Run the install script from Home (Chapter 1).
- Complete Connect this computer so the cloud stores a claimed device with a
tokenHash. - On macOS, the browser reads
GET http://127.0.0.1:{wakePort}/identityfrom the Mac bridge and matches hashes—see Q&A: this computer and localhost identity / CORS.
Two UI phrases (do not confuse them):
| Copy | Meaning |
|---|---|
| “This computer” (connect row) | Product copy: link the computer you’re sitting at now. |
| “This computer” badge / On this computer | Computed match: cloud device hash equals local bridge identity. |
If identity is not linked after install, run Connect this computer again while signed in—pairing token under ~/.agent-witch must match a claimed device (update / reconnecting Q&A).
#Account menu essentials
Open your profile / account menu (top bar) for:
| Item | Purpose |
|---|---|
| Mac & devices | List paired computers, presence, install bundle version hints. |
| Settings | Profile, notifications, integrations (as shipped). |
| Sign out | Ends browser session; Mac helper may keep running. |
Mac settings links often open the local helper or #your-setup anchors for update, wake, and repositories—browser daily work stays on Home and Projects (Chapter 4).
#Guest vs signed-in (library only)
Unsigned visitors may browse Marketplace / guest library drafts in browser storage on that device only. Running workflows and dispatch require sign-in and a dispatch-ready Mac (or configured Cursor Cloud key). See guest library Q&A.
After you sign in, guest drafts can sync to your cloud library (newer updatedAt wins). That handoff is personal reuse today; team Library and Marketplace are where org-wide team learning lives (Chapter 7).
#Security habits (plain language)
- Treat magic links like passwords—do not paste them in public chats.
- Pairing tokens on disk prove your computer to the cloud; protect your computer login and disk encryption.
- The Console never receives your raw pairing token in the device list—only a hash (Q&A).
- Loopback identity is allowed only from AgentWitch origins to your
127.0.0.1on the same computer—not from random websites (CORS Q&A).
Threat model for engineers: security/threat-model.md.
#Troubleshooting sign-in
| Symptom | Try |
|---|---|
| Google error / redirect loop | Confirm AUTH_SECRET and OAuth URLs on custom deployments; production uses AgentWitch’s configured Google app. |
| No magic email | Spam folder; resend once; verify Resend/domain on self-hosted envs. |
| Signed in but no computer badge | Must be macOS browser on same computer as bridge; refresh tab; check helper running (Chapter 4). |
| Test account rejected on production | Expected—use real auth on www.agentwitch.com. |
#AI self-registration (no email, or Agent Mail)
On the homepage, copy the short prompt under For your AI. Your bot follows that prompt (and the public guide at /for-agents) to create its own AgentWitch account. There is no directory of other people's bots. AgentWitch does not publish an account, email, or token for you to share.
An AI can sign itself up with no mailbox, or with an Agent Mail inbox when the server supports it. After signup it can install on its computer, save a Playbook, and run work on computers it owns. Calls are rate limited. A bot token cannot attach to an existing human account. If the bot is told to wait (busy or rate limited), it should wait instead of retrying in a loop. Details for engineers: AI self-registration Q&A.
#Related docs
- Chapter 1 — Getting started
- Chapter 3 — Home and navigation
- Auth domain (engineers)
- System Q&A
#Query aliases
- AgentWitch sign in, login, Google OAuth, magic link
- account pairing Mac, connect this computer, this computer badge
- dang nhap AgentWitch, tai khoan, lien ket Mac
- AI tu dang ky khong email, Agent Mail, WebMCP prompt trang chu
- email magic link AgentWitch, test auth localhost
- team nav solo marketplace AgentWitch account
- team learning shared runs library account, team chia se kinh nghiem tai khoan