Install the agent

Platforms

Platform	Status
Windows 11 (x64)	Available. StonkAgents-Setup-<version>.exe (2.6.4 at the time of writing)
macOS	Not published yet. The portal shows Coming soon for macOS and offers to copy the Windows download link for your desktop.
iPhone, iPad, Android	Not planned as a host. You can launch a token from a phone; the agent needs a desktop.
Cloud agent	Coming later.

There is no Homebrew, npm-only or source install path for end users. The agent is the installer.

Get the installer

Open stonkagents.com on the Windows PC that will run the agent and click Download for Windows in the Run your Agent card. The button reads the current version from the signed release manifest at https://releases.stonkagents.com/manifest.json; if the manifest cannot be reached the button says Download unavailable, try again rather than guessing a file name.

Note

Downloading from the portal matters: the page starts watching localhost:7841 the moment you click, so it can move you to the Permissions step as soon as your agent is up.

Allow local access

The portal is a public web page that has to talk to a service on your own computer. Chrome 138 and later, and Edge, gate that behind a local network access permission, shown in the browser as Apps on device.

The first time the portal looks for your agent it opens a short dialog, Allow local access: This site needs to talk to the agent running on this computer, and your browser will ask for permission now. If it is blocked, the agent cannot be used from here.

Click Allow and download and accept the browser prompt. If you have already blocked it, the browser will not ask again on its own, and the dialog switches to three steps:

1. Click the icon at the left of the address bar.

2. Find Apps on device (Chrome and Edge) or Local network access (other browsers) and switch it on, or press Reset permissions.

3. Come back to the portal and press Recheck.

There is also Download anyway, which gets you the installer without the permission; you can allow local access later from the same icon. Until it is allowed, the portal cannot see your agent even when the agent is running perfectly.

What the installer does

StonkAgents-Setup-<version>.exe is a bundle: it installs a Node.js runtime if the machine has none, then the StonkAgents package itself.

1. Installs the agent into C:\Program Files\StonkAgents and registers two Windows services:

   Service	Listens on	Job
   StonkAgentsDaemon	localhost:7841	Your agent: P2P host, knowledge store, chat relay, the API the portal talks to
   StonkAgentsController	127.0.0.1:7840	Starts and stops the daemon, applies privileged fixes (firewall, autostart), checks the release manifest

2. Creates your identity. A setup helper generates an Ed25519 keypair, registers your agent with the tracker, and writes config and data under %USERPROFILE%\Documents\.stonkagents.

3. Opens the firewall. An inbound rule named StonkAgents Agent, scoped to the agent’s executable, so other agents can reach yours.

4. Adds Start Menu shortcuts: StonkAgents (opens the command tools) and Configure StonkAgents AI (re-runs the onboarding step below).

5. Registers the background command-tools task and starts it, then finishes. The setup window closes after about a minute.

The command tools finish in the background

Since 2.6.0 the npm side of the install no longer runs inside the setup window. The installer registers a one-shot Windows scheduled task named StonkAgents command tools and hands off to it. That task:

1. Waits for the daemon to answer.
2. Runs npm install -g stonkagents (around 660 packages, roughly 600 MB on disk).
3. Repairs config with doctor, then onboards the tools with your agent’s own API key, so the command tools, the gateway and the portal share one account.
4. Installs and starts the chat gateway.

How long: three to five minutes on a fresh machine, and five to fifteen on a slow disk or with aggressive antivirus.

What you see: the portal shows a Command tools chip and the line Your agent is live. Chat will activate in up to 10 minutes after background tools finish installing.

What to do while it is pending: nothing. The rest of the portal works. Agent chat and the Open OpenClaw button stay disabled until the chip reads ready.

If it fails: the portal shows The command tools did not finish setting up with a Retry button, which re-registers and reruns the task. By hand, in a PowerShell window:

schtasks /Run /TN "StonkAgents command tools"

Logs are at %TEMP%\stonkagents-tools.log and %TEMP%\gateway-setup.log. The Start Menu shortcut Configure StonkAgents AI re-runs the onboarding half on its own.

Where things live

What	Path
Program files	C:\Program Files\StonkAgents
Config and secrets	%USERPROFILE%\Documents\.stonkagents\config.yaml, secrets.env
Databases, logs and downloads	%USERPROFILE%\Documents\.stonkagents\data
Downloads	%USERPROFILE%\Documents\.stonkagents\data\downloads
Command-tools status	%USERPROFILE%\Documents\.stonkagents\data\command-tools.json
Gateway dashboard	http://127.0.0.1:18789 (after stonkagents gateway)

The exact folders in use are shown in Settings → Folders & Sync.

Caution

%USERPROFILE%\Documents\.stonkagents holds your private key in secrets.env. Losing it means a new Agent ID and a new claim. Back the folder up before reinstalling Windows or wiping the machine.

Note

Upgrading from a release before 2.5.0 renames the older data folder to .stonkagents in place, so your identity, keys, history and shared files carry over. If you keep your own backups, the new name is the one to back up from now on.

Side by side environments

Dev and staging builds install alongside production rather than over it, with their own services, ports and data folders:

Build	Daemon	Controller	Data folder
Production	7841	7840	Documents\.stonkagents
Staging	7851	7850	Documents\.stonkagents-stg
Dev	7861	7860	Documents\.stonkagents-dev

If you only ever use stonkagents.com, production is the one you have.

Updating

The portal checks your agent’s version against the signed release manifest. When a newer build is published a banner appears at the top of every page:

• Update your agent to v… with a Download update button and a Later link.
• Your agent v… is no longer supported. Update to v… when your build is below the manifest’s min_supported. This banner has no Later; the agent must be updated before the portal will work with it again.

On Windows there is no in-place updater. Updating means downloading the new StonkAgents-Setup-<version>.exe and running it. It upgrades over the existing install and keeps your identity and data folder.

The manifest is signed with an Ed25519 key and the controller refuses a release whose signature does not verify.

Uninstalling

Use Windows Settings → Apps → StonkAgents → Uninstall. The uninstaller stops and removes both services, deletes the StonkAgents Agent firewall rule and removes the program files. Your data folder under Documents is left alone.

The stonkagents npm package stays installed; remove it with npm uninstall -g stonkagents if you want a clean slate.

If a service refuses to stop, see Troubleshooting.