Install

Install Agent Sean

Three ways in. All of them provision on first run, never on npm install — there is no postinstall script, because npm 12+ disables those by default and a background job that touches your machine at install time is exactly the surprise this product refuses to be. Below: what each path writes, where it puts it, and how to take it all back out.

Run it once with npx

The fastest way to try it. npx fetches the package into a temp directory, runs it, and leaves nothing installed.

$ npx agentsean Copy

This drops you into the interactive onboard: it asks what site to work on, where it lives (WordPress, Shopify, a Git repo, Cloudflare, or other), and whether to connect Search Console. It provisions the files below and starts the daemon.

Install the sean command globally

A global install gives you the short sean binary everywhere and is the right choice once you've decided to keep it.

$ npm i -g agentsean Copy

Then the whole surface is available as sean <command>:

$ sean onboard Copy

Still no postinstall. The package ships two bin names — sean and agentsean — and both provision on first run, never during npm i.

The curl installer

For a box where you'd rather not reach for npm. The script checks your Node version, installs the package, and runs onboard.

$ curl -fsSL https://raw.githubusercontent.com/seziro-team/agentsean/main/install/install.sh | sh Copy

Piping a script to sh deserves a read first — the source is install/install.sh in the repo. It installs the same npm package the two commands above do; there is no separate binary.

Docker Compose

Runs the daemon in a container with its state on a named volume. The one thing you must supply is the auth token — the container exits rather than start without it, because an unauthenticated daemon that holds your CMS keys is the incident this whole product is built to avoid.

$ SEAN_AUTH_TOKEN="$(openssl rand -base64 32)" docker compose up Copy

• Compose publishes the port on loopback only — 127.0.0.1:7777, never 0.0.0.0.
• The token must be ≥ 32 characters and ≥ 8 distinct characters; openssl rand -base64 32 clears both. A weak token is refused at startup.
• State (the database, logs) lives on the volume, so docker compose down and back up keeps your history. To undo: docker compose down -v also removes the volume and its data.

Your first run

However you installed, the first minutes look the same. Onboard runs automatically the first time; here is what it does, and how to drive it by hand.

1. 1 Check the machine is ready

   $ sean doctor Copy

   doctor is read-only and prints a check per line: your Node version, whether ~/.sean is writable and locked to mode 700, whether port 7777 is free, whether an auth token exists yet, whether the database and a Google grant are present, and whether Playwright is installed. Anything marked FAIL blocks a clean start; ! is a warning you can proceed past.

2. 2 Connect a site

   Onboard asks for the URL and the platform. To connect Search Console — optional, but it's what turns crawl findings into ranked opportunities — Sean opens the local dashboard and walks you through Google's consent screen. The hosted OAuth broker never talks to your machine; the grant is stored locally.

   $ sean connect google Copy

   No Google account? Skip it. sean audit https://your-site.com crawls and runs all 425 checks with zero credentials.

3. 3 Let the first crawl run

   Sean crawls the site, runs the checks, and scores it. A small site (dozens of pages) finishes in seconds; the demo run on the home page shows 80 pages · 6s. Pages that need JavaScript to render trigger a one-time Chromium download the first time — after that it's cached.

4. 4 The observe window

   New sites start in a 7-day observe-only period. Sean watches and proposes but writes nothing until it ends — the action validator vetoes every write with OBSERVE_PERIOD in the meantime. When you're ready to stop everything regardless, sean freeze halts all writes across every site and survives a restart.

What Agent Sean writes, and where

Everything the daemon owns lives under one directory: ~/.sean on macOS and Linux, or wherever SEAN_HOME points. It is created with permissions 700 (owner-only) and nothing is written outside it unless you explicitly install a service.

The auth token is not in this directory as plaintext. It's stored through the OS credential store — Keychain on macOS, the Secret Service on Linux — with an encrypted-file fallback. doctor reports its length, never its value.

Run it as a service

To survive a reboot, install Sean as a user service. This is the one action that writes a file outside ~/.sean, so it is never a side effect of onboard or npm — it prints exactly what it will write and refuses to proceed without your confirmation (--yes, or typing yes at the prompt).

$ sean service install Copy

Prefer to see the plan first without writing anything:

$ sean service status Copy

What it writes depends on your OS. In every case the unit binds 127.0.0.1 only — the installer refuses to write a service that binds any other host.

~/Library/LaunchAgents/dev.agentsean.plist

~/.config/systemd/user/agentsean.service

%SEAN_HOME%\agentsean.schtasks.xml

Upgrading

Check where you stand against a release channel:

$ sean update Copy

It compares your version against the channel (stable by default; --channel extended-stable or --channel dev for the others) and, if you're behind, prints the exact command to move — a global reinstall pinned to the new version:

$ npm install -g agentsean@latest Copy

An auto-update never runs while an Action is mid-flight — a fix in the middle of being written and verified is never interrupted by a version swap.

Uninstalling completely

One command stops the daemon, unwinds the service, and — by default — leaves your data alone:

$ sean uninstall Copy

That stops Sean, removes the user service (the plist / unit / task from above), and tells you your history is still in ~/.sean. To erase everything it ever wrote, add --purge:

$ sean uninstall --purge Copy

Then remove the package itself:

$ npm rm -g agentsean Copy

Any diffs Sean wrote to your site are unaffected by uninstalling — they live in your CMS or Git history and remain reversible there. Uninstalling removes the engine, not its past work.

Troubleshooting the things that actually bite