Deployment on Windows

This guide covers running Celly as a long-lived service on a Windows 11 host, including Task Scheduler setup and the personal-access-token (PAT) flow for re-authenticating sbx without an interactive browser. The bot must run as the logged-in user on the host: the sbx daemon and its credentials are per-user, and only the host can invoke the sbx CLI. NSSM or a LocalSystem service will not work.

1. One-time host bootstrap

Run these steps once, in order, as the user who will own the bot. Steps 1–2 need an elevated PowerShell prompt; the rest run as the normal user.

Enable the Windows Hypervisor Platform:

Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All

Install sbx:
winget install -h Docker.sbx
Run the host prep step:
sbx setup
Log in to Docker:
sbx login
Initialize the network policy preset. It is required before the first sandbox, otherwise sbx create blocks on an interactive prompt:
sbx policy init balanced
Register provider credentials used by the sandboxed agent (see Providers):
sbx secret set <provider>
Record the installed version. Celly targets sbx >= 0.45.0:
sbx version

2. Build and configure the bot

Install the pinned Node version (24.x) and clone the repository.
Copy .env.example to .env and fill in DISCORD_TOKEN and DISCORD_GUILD_ID. See Configuration for the full variable list.
Install dependencies and build:
npm ci npm run build
Run the bot once in the foreground to confirm it boots:
node dist/index.js
On boot it performs a preflight (sbx version, policy check, single-instance lock) and fails fast with an actionable message. Logs are written to data/bot.log.

3. Task Scheduler at logon

The task must run only when the user is logged on. Do not choose “Run whether user is logged on or not”: that option requires storing the account password and can start the task outside the user’s sbx session.

Option A: PowerShell (recommended)

Run the following in a normal (non-elevated) PowerShell prompt. It registers a task that starts Node with the repo as its working directory, never times out, and restarts on failure.

$node    = (Get-Command node).Source
$repo    = "C:\Users\artur\projects\discordAI"
$action  = New-ScheduledTaskAction -Execute $node -Argument "dist\index.js" -WorkingDirectory $repo
$trigger = New-ScheduledTaskTrigger -AtLogOn -User $env:USERNAME
$settings = New-ScheduledTaskSettingsSet `
  -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries `
  -ExecutionTimeLimit ([TimeSpan]::Zero) `
  -RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 1)
Register-ScheduledTask -TaskName "Celly" -Action $action -Trigger $trigger `
  -Settings $settings -Description "Celly Discord bot" -Force

-ExecutionTimeLimit ([TimeSpan]::Zero) clears the default 72-hour limit so the bot is not killed. Adjust $repo to the clone location. To inspect, run, or remove the task:

Get-ScheduledTask -TaskName Celly | Get-ScheduledTaskInfo
Start-ScheduledTask -TaskName Celly
Unregister-ScheduledTask -TaskName Celly -Confirm:$false

Option B: Task Scheduler GUI

Open Task Scheduler and choose Create Task (not “Basic Task”).
General: name it Celly; select Run only when user is logged on.
Triggers: add At log on, scoped to the user who owns sbx.
Actions: Start a program with:
- Program/script: the full path to node.exe (for example C:\Program Files\nodejs\node.exe).
- Add arguments: dist\index.js.
- Start in: the repository root.
Settings: uncheck Stop the task if it runs longer than…, and enable If the task fails, restart every 1 minute (up to 3 times).

The bot’s single-instance lock prevents a second copy from double-driving sandboxes, so a logon and a manual start cannot both run. sbx normally signs in through an interactive browser. On a headless or re-login scenario (for example, the machine reboots and the user session starts without a browser, or the stored credential expires), the at-logon task starts but sbx is not authenticated. Re-authenticate non-interactively with a Docker personal access token (PAT).

Create a Docker PAT: sign in at https://hub.docker.com, open Account settings → Personal access tokens, and create a token with at least read access.

Feed the token to sbx over stdin with --password-stdin. Never pass the token as a command-line argument, where it would be visible in the process list and PowerShell history:

$pat   = Read-Host "Docker PAT" -AsSecureString
$plain = [Runtime.InteropServices.Marshal]::PtrToStringAuto(
           [Runtime.InteropServices.Marshal]::SecureStringToBSTR($pat))
$plain | sbx login --username <docker-username> --password-stdin
Remove-Variable plain

Verify:
sbx diagnose
If the bot is already running, restart the scheduled task so the daemon picks up the new credential:
Restart-ScheduledTask -TaskName Celly

Store the PAT the same way you store other host secrets (for example, Windows Credential Manager) if you need to automate this step; do not commit it or put it in .env.

5. Verifying a deployment

sbx diagnose reports a healthy install, daemon, and authentication.
sbx policy ls shows the balanced preset as the floor.
node scripts/smoke.mjs C:\path\to\a\project\dir prints smoke OK (full chain: create → bootstrap → serve → health → create session → prompt → abort → stop → remove, with teardown on failure).
After an at-logon start, data/bot.log shows the preflight passing and the Discord client logging in.

6. Troubleshooting

Symptom	Cause	Fix
Boot fails: `sbx CLI not found`	`sbx` not on the user’s PATH	Reinstall with `winget install -h Docker.sbx`; open a new shell.
Boot fails: `run sbx login`	Expired/unauthenticated session	Run the PAT flow in section 4.
`sbx create` hangs	Policy preset not initialized	Run `sbx policy init balanced`.
Bot exits: `already running`	A second instance holds the lock	Stop the other process or the duplicate scheduled task.
Task starts but nothing happens	Task configured as LocalSystem / “run whether logged on”	Recreate the task as “Run only when user is logged on”.
Sandboxes not stopped after reboot	Expected	Sandboxes stop automatically when idle; the next prompt wakes them via `ensureReady`.

7. Sensitive paths

PROJECTS_ROOT may live under the user profile (the default is %USERPROFILE%\Celly\projects). The sensitive-path denylist rejects specific sensitive subtrees (.ssh, .aws, .gnupg, .config, .docker, .kube, .azure, .npmrc, .netrc, .celly, AppData), DATA_DIR, the bot repository, and system directories, so keep projects out of those. See Configuration for the complete list.

8. Limitations to plan around

The in-memory message queue is lost on bot restart. Active runs are re-attached from session history, but queued-but-unsent prompts are dropped.
Role configuration accepts role IDs only, not role names.
The finalization token/duration footer is descoped.
Per-user command rate limiting, sandbox disk-usage warnings, and the DATA_DIR cloud-sync warning are backlog. Keep DATA_DIR outside any OneDrive/Dropbox-synced folder yourself.
The smoke script (node scripts/smoke.mjs) and live Discord interactions are host-only and are not exercised by the Linux test suite.

Deferred commands and features are listed in the commands reference and the changelog.

Get started

Guides

Reference

Project

Deployment on Windows

1. One-time host bootstrap

2. Build and configure the bot

3. Task Scheduler at logon

Option A: PowerShell (recommended)

Option B: Task Scheduler GUI

5. Verifying a deployment

6. Troubleshooting

7. Sensitive paths

8. Limitations to plan around

​1. One-time host bootstrap

​2. Build and configure the bot

​3. Task Scheduler at logon

​Option A: PowerShell (recommended)

​Option B: Task Scheduler GUI

​4. PAT headless re-login

​5. Verifying a deployment

​6. Troubleshooting

​7. Sensitive paths

​8. Limitations to plan around

1. One-time host bootstrap

2. Build and configure the bot

3. Task Scheduler at logon

Option A: PowerShell (recommended)

Option B: Task Scheduler GUI

4. PAT headless re-login

5. Verifying a deployment

6. Troubleshooting

7. Sensitive paths

8. Limitations to plan around