AI Cloud Security Scanner — Local Agent

The local agent runs on your PC and reports safe metadata (process names, startup programs, active network connections, and file hashes) to the AI Cloud Security Scanner backend over HTTPS. File contents never leave your machine — only SHA-256 hashes are sent.

Requirements

• Node.js 22+
• Access to the AI Cloud Security Scanner server

Install

The fastest way is to run the agent directly with npx — no install required:

npx @ai-scanner/agent pair

Or install it globally so the ai-scanner-agent command is always on your PATH:

npm install -g @ai-scanner/agent

That's it — no need to clone the repo. After install you'll have a single binary called ai-scanner-agent.

Pair with the dashboard

1. Open the AI Cloud Security Scanner dashboard in your browser.
2. Navigate to My Device and click Generate Pairing Code. A 6-character code appears (valid for 10 minutes).
3. In your terminal, run:

AGENT_SERVER_URL=https://your-server.example.com ai-scanner-agent pair

4. Enter the 6-character code when prompted.
5. The agent saves credentials to ~/.ai-scanner-agent/config.json (mode 0600).

Start scanning

ai-scanner-agent start

The agent will:

• Collect running processes, startup entries, network connections, and file hashes from common download/desktop directories.
• Send the data to the server every 5 minutes.
• Send a heartbeat every 60 seconds so the dashboard shows it as "Connected".
• Print a summary line after each successful report.

Press Ctrl+C to stop.

Run as a background process

macOS / Linux (nohup)

AGENT_SERVER_URL=https://your-server.example.com nohup ai-scanner-agent start > ~/.ai-scanner-agent/agent.log 2>&1 &
echo $! > ~/.ai-scanner-agent/agent.pid

To stop:

kill $(cat ~/.ai-scanner-agent/agent.pid)

Linux (systemd user service)

Create ~/.config/systemd/user/ai-scanner-agent.service:

[Unit]
Description=AI Scanner Agent
After=network.target

[Service]
ExecStart=/usr/bin/env ai-scanner-agent start
Environment=AGENT_SERVER_URL=https://your-server.example.com
Restart=on-failure
RestartSec=30
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=default.target

systemctl --user daemon-reload
systemctl --user enable --now ai-scanner-agent
journalctl --user -u ai-scanner-agent -f

Windows (Task Scheduler)

Create a scheduled task that runs:

ai-scanner-agent start

with AGENT_SERVER_URL set as an environment variable, triggered at log-on and repeating every 5 minutes.

Log location

Logs are printed to stdout. When running with nohup above, they go to ~/.ai-scanner-agent/agent.log.

Check status

ai-scanner-agent status

Uninstall / Unpair

ai-scanner-agent stop

This removes ~/.ai-scanner-agent/config.json. To fully uninstall the binary itself:

npm uninstall -g @ai-scanner/agent

What data is collected

| Category | Data sent | |---|---| | Processes | Process name + PID only | | Startup entries | Entry name + file path | | Network connections | Local/remote address + port, connection state, PID | | Files | File path + SHA-256 hash + size (no content) |

Privacy & security

• Only metadata leaves your machine — never file contents.
• All transport is HTTPS.
• The agent token is stored in ~/.ai-scanner-agent/config.json with permissions 0600.
• You can revoke access at any time from the My Device page in the dashboard (Disconnect Agent button), or by running ai-scanner-agent stop.

End-to-end setup (server + agent + extension)

1. Start the API server: cd artifacts/api-server && pnpm dev
2. Start the web dashboard: cd artifacts/scanner-web && pnpm dev
3. Pair and start the agent (see above).
4. (Optional) Load the Chrome extension from the extension/ directory via chrome://extensions → Load unpacked.

For the agent to reach the server, set AGENT_SERVER_URL to the public URL of the API server (e.g., https://yourapp.replit.app).

Develop the agent locally

If you've cloned this repo and want to hack on the agent itself instead of using the published package:

cd agent
npm install
npm run build              # compile TypeScript to dist/
node dist/index.js pair    # run the locally built binary

Or run the source directly with Node 22's experimental TypeScript support:

npm run pair               # equivalent to: node --experimental-strip-types src/index.ts pair

To publish a new release to npm:

npm version patch          # bumps version
npm publish --access public

The prepublishOnly script automatically rebuilds dist/ before publishing.