130 lines
8.1 KiB
Markdown
130 lines
8.1 KiB
Markdown
# 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. |
|
|
| `FORTRESS_ENABLED=` | Set to `true` to give the assistant the Fortress stealth browser, for reading pages that block normal browsers. Needs Python: open a terminal and run `pip install "tilion[mcp]" "mcp<2"` once. The browser engine (about 200 MB) downloads the first time it is used. |
|
|
| `FORTRESS_COMMAND=` | Leave empty. If the console says `fortress bridge failed to start` with `ENOENT`, set it to `python -m tilion.mcp`. |
|
|
|
|
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:
|
|
|
|
```powershell
|
|
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 |
|
|
| `fortress bridge failed to start` with `ENOENT` | `tilion-mcp` is not on PATH | Set `FORTRESS_COMMAND=python -m tilion.mcp` in `.env` |
|
|
| `fortress bridge failed to start` with `ModuleNotFoundError: No module named 'mcp.server.fastmcp'` | pip installed the 2.x MCP library, which Fortress doesn't support yet | Run `pip install "mcp<2"` |
|
|
| 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.
|