VolcanicSecretary/SETUP-WINDOWS.md

Setting up Volcanic Secretary on Windows

This guide takes you from a fresh checkout to a Telegram bot that answers you. No Docker involved. Budget about ten minutes.

What you need

• Windows 10 or 11.
• Node.js 24 or newer, from https://nodejs.org. Check with node -v in a terminal.
• Git for Windows at its default location, which gives the assistant a bash for running scripts.
• Pi installed and able to reach a model. If typing pi in a terminal and sending hi gets an answer, you are set; the bot reuses the same credentials from ~/.pi/agent.
• A Telegram account on your phone or desktop.

Step 1: Create the bot and get its token

1. In Telegram, open a chat with @BotFather.
2. Send /newbot.
3. Give it a display name (for example Volcanic Secretary) and then a username that ends in bot (for example volcanic_secretary_bot). Usernames must be unique across Telegram, so add digits if the first try is taken.
4. BotFather replies with a token that looks like 123456789:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. Copy the whole thing.

Treat the token like a password. Anyone who has it can send messages as your bot.

Step 2: Find your own Telegram user id

The bot only talks to one person, identified by a number, not a username.

1. Open a chat with @userinfobot and send /start.
2. It replies with a line such as Id: 987654321. That number is your user id.

Any other user who messages the bot is ignored. Their id is written to the bot's log once, which is also how you can double check your own id later.

Step 3: Create and fill in .env

1. Double-click run.bat in the project folder. On the first run it copies .env.example to .env, opens it in Notepad, and stops.
2. Edit the two required lines:

TELEGRAM_BOT_TOKEN=123456789:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TELEGRAM_OWNER_ID=987654321

No quotes, no spaces around =.

3. Optional lines, leave them as they are unless you want the feature:

Line	What it does
OPENAI_API_KEY=	Enables voice notes. Paste an OpenAI API key and voice messages get transcribed before the assistant sees them. Without it, voice notes get a polite "not configured" reply.
STT_MODEL=gpt-4o-transcribe	The OpenAI transcription model. Fine as is.
PI_MODEL=	Forces a model. Empty means the first model Pi has credentials for; with the Claude Code subscription package that is pi-claude-code-provider/sonnet. To use Opus through that package set PI_MODEL=pi-claude-code-provider/opus. Ids such as anthropic/claude-opus-4-7 belong to Pi's built-in Anthropic provider and only work with an ANTHROPIC_API_KEY. pi --list-models prints every id Pi knows.
SECRETARY_TIMEZONE=	IANA zone for reminders and cron jobs, for example Europe/Berlin. Empty means the Windows system zone.
SECRETARY_SHELL=	Full path to bash.exe if Git is not installed at C:\Program Files\Git.
WORKSPACE_DIR=./workspace	Where the assistant keeps its memory file, scripts, and files you send.
LOG_LEVEL=info	Set to debug to see more in the console.

4. Save the file and close Notepad.

Step 4: Start the bot

Double-click run.bat again. It installs dependencies the first time, builds, and starts. The console should show lines like these:

workspace D:\...\VolcanicSecretary\workspace
telegram bot @volcanic_secretary_bot
agent ready: anthropic/claude-opus-4-8
scheduler ready with 0 job(s)
polling started

Within a second or two your Telegram chat with the bot receives 🟢 Online. followed by a short status block.

Send hi. You will see a ⚙️ Working… message that updates while the assistant works, then the reply.

Useful commands in the chat:

Command	Effect
/status	Busy or idle, model, context usage, number of scheduled jobs
/new	Start a fresh conversation, the old one stays on disk
/stop	Abort what the assistant is doing right now
/jobs	List scheduled jobs
/cancel <id>	Delete a scheduled job by its id from /jobs
/compact	Shrink the conversation context

Step 5: Stop the bot

Press Ctrl+C in the console window. The bot shuts down cleanly. Windows then asks Terminate batch job (Y/N)?, answer Y. Closing the window also works.

Everyday use

• Photos are shown to the model. Files you send land in workspace\inbox\ and the assistant is told the path.
• The assistant writes durable facts to workspace\MEMORY.md. You can edit that file yourself; the bot reads it fresh every turn.
• workspace\AGENTS.md holds standing instructions and the persona. Edit it to change how the assistant behaves; changes apply after /new or a restart.
• Scheduled jobs are stored in workspace\.secretary\jobs.json and survive restarts.
• After pulling code updates, delete the node_modules folder or run npm install once so the launcher picks up new dependencies.

Keeping it running in the background

run.bat is meant for a visible console window. To run the bot unattended, install pm2 once and register it:

npm install -g pm2
npm run build
pm2 start "node --env-file-if-exists=.env dist/main.js" --name secretary --cwd "D:\Projects\Names\VolcanicSecretary"
pm2 save

Alternatively, Windows Task Scheduler can start run.bat at logon, but any startup error then waits on the pause prompt inside a window you may not see.

Troubleshooting

What you see	Cause	Fix
Config error: TELEGRAM_BOT_TOKEN is required	.env is missing or the line is empty	Run run.bat, fill in the token, save
.env still contains the placeholder bot token	The example value was never replaced	Paste the real token from BotFather
Startup failed: GrammyError: Call to 'getMe' failed! (401: Unauthorized)	The token is wrong or was revoked	Copy it again from BotFather, or send /revoke there and use the new one
Startup failed: Error: Model "anthropic/..." (from PI_MODEL) has no credentials for provider "anthropic"	PI_MODEL names a model from a provider you have no key for	Use one of the ids the message lists, for example pi-claude-code-provider/opus, or leave PI_MODEL empty
Startup failed: Error: No model available or No model has credentials at all	Pi has no working model credentials	Run pi in a terminal and log in, or set PI_MODEL plus the provider's API key in .env
Bot says 🟢 Online. but never answers your messages	TELEGRAM_OWNER_ID is not your id	Look in the console for ignoring update from user 987654321, put that number in .env, restart
409: Conflict in the console	A second copy of the bot is running with the same token	Stop the other one (another window, pm2, or Docker)
Voice notes reply "Voice transcription is not configured"	No OpenAI key	Add OPENAI_API_KEY to .env and restart
A scheduled script fails with failed to start bash	Git for Windows is not at the default path	Set SECRETARY_SHELL to the full path of bash.exe
Replies arrive as raw text with <b> tags	Telegram rejected the formatting, the bot fell back to plain text	Harmless; report the message content if it repeats
The window closes before you can read anything	An error happened before the launcher's pause	Open a terminal in the folder and run .\run.bat from there

If the console shows a message not in this table, start the bot with LOG_LEVEL=debug in .env and read the last few lines before the exit.