Install Portainer-AiGrid and onboard Windows 11 workers

Portainer and the appliance host

Portainer's version, Edge Compute settings, Trust on first connect and SSRF mode are documented requirements; the appliance does not read or check any of them.

Each Windows 11 desktop

• Windows 11, build 22000 or later.
• WSL 2.9.13 or later with WSL containers, which provides wslc.exe. WSL 3.0.1 is recommended.
• An administrator PowerShell to run the install script.
• 2 CPUs and 4 GB of RAM as the sensible floor. A ceiling below 4 GiB means the desktop is never offered work.
• Outbound access to the appliance, to Portainer and to the container registry. No inbound port is opened.
• A hostname that is unique in your estate. The hostname becomes the Portainer environment name and the machine's identity in Portainer-AiGrid, so two desktops with the same name are one machine. Rename cloned desktops before running the script.

1. Enable edge compute and set the Edge Portainer URL to an address your desktops can reach.
2. Turn on Trust on first connect. Portainer-AiGrid does not set it for you, because it is global to your Portainer and also applies to environments unrelated to Portainer-AiGrid.
3. Confirm SSRF protection is Off if you are enrolling Windows desktops.
4. Create an API token on an administrator account and keep it for the setup form.

The setup form asks for the bucket, so create it first. Any S3-compatible store works: your own MinIO, SeaweedFS or Ceph, or a cloud bucket.

1. Create a bucket that holds the corpus and nothing else. The whole bucket is indexed and there is no prefix to narrow it.
2. Create two identities. A writer, which you use to upload documents, and a reader for Portainer-AiGrid with ListBucket and GetObject only. Documents are discovered by listing, so a reader without ListBucket fails the setup test.
3. Upload documents with the writer. An empty bucket is fine at setup; the scanner picks up whatever arrives later.

Portainer-AiGrid reads these file types: .pdf, the images .png .jpg .jpeg .tiff .tif .bmp .webp, and .txt .md .html .htm .docx .pptx .xlsx .csv. Other objects are skipped.

How the library behaves afterward

• The appliance scans the bucket every 300 seconds by default and queues only what is new or changed.
• Replacing a document supersedes the old version in the index automatically.
• Deleting a document from the bucket does not remove it from the index. It keeps answering searches until the index is rebuilt.
• The original files stay where you put them and are only ever read. Workers fetch them directly from the bucket with the reader credential the appliance hands over with each claim.

Install KubeSolo on the appliance host, as a user with sudo:

curl -sfL https://get.kubesolo.io | sudo sh -

Wait until kubectl get storageclass lists local-path. It appears about a minute after the node reports Ready, and the appliance's two volumes cannot bind until it does. With KubeSolo, kubectl reads /var/lib/kubesolo/pki/admin/admin.kubeconfig.

Then register the host in Portainer as an edge-standard Kubernetes environment, with async left off. An async agent does not re-apply an updated edge stack, so the appliance could be installed and never upgraded. Use Portainer's own process for adding an edge Kubernetes environment.

In Portainer: Registries → Add registry → Docker Hub. Enter a name, the username and token you were given, and test the connection.

• Choose Docker Hub, not the custom registry option. Docker Hub sets the address to docker.io, which must match exactly for the workers' pull secret to work.
• You give this credential to Portainer once, never to the appliance. You select the registry on the stack form in the next step.
• If the token is scoped to named repositories, it must include all three. A token missing portainer/aigrid-worker leaves the appliance healthy and every worker in ImagePullBackOff with insufficient_scope.

The appliance is a Kubernetes edge stack, which is also how you upgrade it later.

1. Create an edge group

Edge → Edge Groups → Add edge group. Name it aigrid-appliance and add only the appliance's environment. Do not reuse the name aigrid-fleet; Portainer-AiGrid creates and manages that group itself.

2. Create the edge stack

Edge → Edge Stacks → Add edge stack:

There is nothing else to configure. A Kubernetes stack in Portainer has no deploy-time variables, so the manifest carries no secrets. Do not edit the image tags to :alpha or :latest; under Kubernetes' default pull policy that silently runs whatever image the node already has.

Four pods start: Postgres, Milvus, central and the dashboard. Allow about a minute.

Open https://<appliance-host>:30444. Your browser warns about the certificate, which is a temporary self-signed one served until setup completes. That is deliberate, because the form carries your Portainer token and bucket key.

The form has four steps and all three groups are required. It cannot be reopened once applied, so have the Portainer token and the S3 key pair ready. Back and clicking a completed step both keep what you typed.

Step 1: where this appliance is reached

Enter every IP and DNS name the appliance will be reached by, primary first. These become the certificate's names. Adding one later re-mints the certificate, so include the name your AI assistant will use.

Step 2: Portainer

Enter the URL, the API token and whether to verify Portainer's TLS. Clear the verify box if Portainer is self-signed. The button is Test connection and continue and there is no way past it without a pass. The test runs from the appliance, not your browser. A failure names its layer:

Step 3: document corpus

Enter the S3 endpoint, the bucket and the read-only key pair. Same test button.

A pass that reads "It is currently empty" is fine to apply.

Step 4: review and apply

The review shows every value as it will be written, with the token and secret masked, above a checklist of what applying is waiting on. After Apply configuration the appliance writes its configuration, mints its own CA and certificates, and restarts. It returns in about fifteen seconds. The form waits out the restart and reloads into the dashboard, and your browser asks about the certificate once more, because it is now the real one.

Create the pools before you enroll desktops, because the install script is generated per pool. The appliance is installed with the fleet switched off, so nothing runs on any desktop until you turn it on.

• A pool is a named group of machines with its own hours and its own switch. A fresh appliance has one pool, general, with the window mon-fri 19:00-06:00, evaluated on each machine's own clock including daylight saving. You can rename it and edit its window, but never remove the window.
• Add a pool when one group needs different hours, for example workstations after six and servers around the clock. A new pool's switch is on by default.
• The fleet switch is the master stop. Off means no machine claims anything, whatever any pool says.
• Changes land within a minute. Nothing is redeployed and a document already being converted is not interrupted.

The page header on every screen reads Grid active or Grid paused. It does not say whether a window is open right now, because each window belongs to the machine's own clock.

1. Get the script

On the dashboard, open Add a machine, choose Windows desktop and the pool these desktops belong to, then download aigrid-install.ps1. The Windows option is offered once the appliance has the shared edge key and the aigrid-windows tag from Portainer.

The script is byte-identical for every desktop in the pool. Nothing in it names a machine, so it can go in a golden image or be pushed by your management tooling. Treat it as a credential: it carries Portainer's shared edge key and Portainer-AiGrid's claim token.

2. Run it as administrator

powershell -NoProfile -ExecutionPolicy Bypass -File .\aigrid-install.ps1

It prints [ok] for each stage and stops at the first [stop], saying whether anything changed. It checks Windows 11, WSL 2.9.13 or later and wslc.exe before changing anything. Then it:

• creates a standard account, aigrid, with a random password that only its scheduled task is given and that is never shown or written down;
• restricts C:\ProgramData\AiGrid to SYSTEM, Administrators and aigrid, and writes the helper script, this pool's aigrid.conf and the appliance CA there;
• registers the task AiGrid Window to start at boot as aigrid, whether or not anyone is signed in, and waits for the helper to reach the appliance and start Portainer's agent.

3. What the desktop does afterward

Each minute the helper asks the appliance for the pool's window and compares it with the desktop's own clock.

• Inside the window it starts the account's WSL containers VM and runs Portainer's stock edge agent there. The agent enrolls as an ordinary Docker edge environment named after the hostname, tagged aigrid-windows, and Portainer delivers the worker to it. The worker then asks the appliance for work, and that first request is how Portainer-AiGrid learns the machine exists.
• Outside the window the worker gets five minutes to hand its document back, then the VM is allowed to shut down. Nothing of Portainer-AiGrid's runs in business hours. The worker stack stays deployed, so the next open picks up where it left off.
• If the appliance cannot be reached, the desktop stays as it is. A desktop that has never reached the appliance does nothing until it can ask.

The VM is sized at the memory ceiling plus 1 GiB, capped at the host's memory minus 2 GiB. The worker never touches your own files; it only reads what the appliance hands it.

4. Verify

1. The script ends with [ok] on every stage after the helper reaches the appliance and starts the agent. A new desktop is opened once whatever the hours, because its first request is what registers it. A desktop the appliance already knows, re-installed outside its window, finishes at closed now instead, which is correct.
2. The log at C:\ProgramData\AiGrid\logs\window.log shows the appliance answering and, in hours, the agent running.
3. In Portainer, an environment named after the desktop's hostname appears with the aigrid-windows tag.
4. On the dashboard, Machines lists the desktop once its worker has made its first request, with the capacity it reports. A machine in no pool is counted on a card at the top and takes no work.

What the owner can change

C:\ProgramData\AiGrid\aigrid.conf holds the per-machine values. Lowering PORTAINER_AIGRID_MEM_LIMIT or PORTAINER_AIGRID_CPUS is always safe and applies at the helper's next poll. The appliance can lower what a desktop is offered but never raise it. Below 4 GiB the desktop takes no work at all, and its row on Machines says so under Refusing. Re-running the install rewrites the file. The file holds the two credentials, so keep its permissions as the install set them.

1. On Fleet policy, turn the fleet switch on. A pool's own switch must be on as well.
2. Open Documents. The scanner lists the bucket on its next pass, and documents move through discovered, queued, processing and indexing to processed.
3. Work happens inside the pool's hours. Switching off later does not abandon work in flight; a machine finishes its document and then stops asking.

There is nothing to tune for routing. If a conversion runs out of memory, the appliance records the size of the machine and never offers that document to one no larger. A document that no machine can convert appears as Stuck on Documents; onboard a bigger machine or raise a pool's ceiling and it becomes claimable again. Whether a stuck document is too large or simply unconvertible is shown in its row.

1. On Connect a client, download aigrid-search.zip. It holds SKILL.md, which already carries the search token and the appliance's address, and ca.pem beside it. The archive is a credential: anyone holding it can search every indexed document, though it cannot enroll or start work on a machine.
2. Unpack it where your agent loads skills from. Claude Code reads ~/.claude/skills.
3. Run the one-line curl check the page shows. Any JSON back means the certificate, token and address agree.

Search is POST /api/v1/search on port 30443. Results come back as passages with filename and page number, and a low_text flag when a document had almost no readable text. If the endpoint answers 503, setup has not completed.

Remove a Windows desktop

Remove the aigrid-windows tag from its environment in Portainer to take the desktop out of the grid. To take Portainer-AiGrid off the desktop entirely, run the same script as administrator with -Uninstall. It stops everything the aigrid account runs, then removes the task, the folder, the account and its profile; if the profile is still in use it asks for a reboot.

Change a desktop's time zone

The change reaches Portainer-AiGrid only after the helper restarts and the worker stack is redeployed. Restart the desktop or the AiGrid Window task, then redeploy the Windows worker stack from the appliance (admin redeploy). Until then the desktop keeps working its pool's hours on the old zone. Summer and winter time need nothing.

Rotate the appliance CA or claim token

Neither reaches a desktop on its own. Re-run the install on every desktop afterward.

Upgrade the appliance

In Portainer, open Edge → Edge Stacks → aigrid-appliance, paste the new release's appliance.yaml (or replace the image tags) and click Update. Central applies migrations on restart; your configuration, CA, data and desktops are untouched, and desktops move to the new worker at the next fleet redeploy. The version is shown at the bottom of the dashboard sidebar. Rolling back after a migration is not supported; the way back is a restore, and there is no restore mechanism yet.

Known limits on Windows

• The agent reaches Docker in the VM through wslc system session run, which WSL calls a debugging path. It bypasses WSL's container policies, such as the registry allowlist and the privileged-container setting, for everything it runs. A future WSL policy could close it.
• The agent is root on the VM, not on Windows.
• A desktop nobody has ever signed in to cannot start the helper until one interactive sign-in and sign-out. The script detects this and says so.
• The worker's memory detection sees the VM, never the whole desktop.
• Sleep, Windows Update reboots and battery inside the window are unhandled.

Troubleshooting