Work with an agent (Claude Code, Codex, OpenCode)

ShakerScan is built for an engineer working with an AI agent. The open-source launcher's shakerscan agent claude starts the agent inside a workspace that already knows ShakerScan: project commands such as /scan, /findings, /status and /deep-hunt, the skills, and the operating rules. The shakerscan client gives you exactly that against your Enterprise instance, from a laptop, without Docker and without the engine:

pipx install shakerscan                                                 # once
shakerscan connect https://scanner.example.com/_enterprise/connect/<code>  # the line from the console
shakerscan agent claude                                                 # or codex, opencode

Inside the session the agent starts scans, reads findings, drives Hunts and checks status the same way it does against a local engine. Every call goes through the gateway under your service token's identity and role and lands in the audit history. The agent's own model does the reasoning; your instance's model credentials are not involved.

One command

1. An administrator opens the Enterprise console, Service tokens, and creates a token for a service account with the operator role, a short lifetime, and a label naming the person.

2. The console shows one command with a Copy button. Paste it on the laptop:

   shakerscan connect https://scanner.example.com/_enterprise/connect/<code> --claude
   

That is the whole setup. The link in the command works once and expires after ten minutes, and the command carries no secret: the client fetches the token through the link, saves it to ~/.config/shakerscan/token (readable only by you) with the instance address beside it, checks the connection, and, with --claude, registers ShakerScan in Claude Code. From then on shakerscan mcp, shakerscan hunt … and shakerscan doctor need no options.

You need Python 3.10 or newer on the laptop and the client itself: pipx install shakerscan (or uv tool install shakerscan, or brew install andriyze/shakerscan/shakerscan). If the open-source engine is also installed on this laptop with the curl one-liner, the same command name is already there; that is deliberate, the client behaves identically and hands engine commands to the local install. If pipx refuses to overwrite it, pipx install --force shakerscan.

The agent session

shakerscan agent prepares a workspace (~/.config/shakerscan/agent, or the current directory with --here) with the ShakerScan operating rules, skills and project commands, a note naming the connected instance, and the MCP server registered for that workspace; then it starts the agent there. Two things differ from a local session, and the note tells the agent so:

• There is no local engine, so nothing starts or stops from the workspace; the instance is already running.
• A route the beta keeps closed answers with a refusal that names what is missing; the agent reports it and takes another path.

Underneath, the kit's API calls go through shakerscan api METHOD PATH [JSON], which you can use yourself (shakerscan api GET "/findings?limit=20"); shakerscan scan … submits and follows scans, shakerscan hunt … drives Hunts, and shakerscan status reports the instance.

Check the connection

connect runs this for you; run it again any time:

shakerscan doctor

A healthy answer names the client version and the saved instance, confirms the token is set (sent as a bearer token, over HTTPS only), reports the engine reachable, and lists the tool catalogue the gateway exposes: read-only Arsenal tools plus Hunt tools (24 in total on the current beta).

Register the MCP server in an agent

connect --claude registers Claude Code for you. To do it by hand, or for another agent:

claude mcp add --scope user shakerscan -- shakerscan mcp

Any MCP client that spawns a stdio server, in its configuration (the saved profile supplies the instance and token):

{
  "mcpServers": {
    "shakerscan": {"command": "shakerscan", "args": ["mcp"]}
  }
}

On a machine without a saved profile, a CI runner for example, pass the connection explicitly with --url and the SHAKERSCAN_API_TOKEN_FILE environment variable.

The agent now sees the Hunt tools (shakerscan_hunt_start, shakerscan_hunt_get, shakerscan_hunt_query, skills, capabilities, candidates, verification, finish and cancel) and the read-only inspection tools (targets, findings, evidence manifest, timeline, plans, tool status, attack-surface gaps). Every Hunt is bound to a target your instance has authorized, and the engine's own scope, approval, budget, evidence and proof rules apply unchanged.

Scripted Hunts

The same client carries the Hunt command line, using the saved instance:

shakerscan hunt list
shakerscan hunt start --help

Connection options come first; everything after them is the Hunt subcommand (start, get, list, query, call, candidate, verify, finish, cancel, resume).

Rules worth telling every token holder

• One token per person, operator role only when Hunt is needed, viewer otherwise. Tokens expire within 90 days and can be revoked at any time in the console; disabling the identity revokes them immediately.
• The token lives in a file only you can read. It is sent only over HTTPS and never printed by the client. shakerscan disconnect deletes it when you are done with an instance.
• A service token cannot open the Enterprise console or sign out a browser session; it is for the client only.

Not in this beta

Running Arsenal commands with execute=true through the client is refused by name; the read-only commands run as bounded reads. The autonomous Hunt, where the instance reasons with a model you configure, does not need a laptop client and does not work yet in this beta (Hunt).