Soroka: Instructions file for Codex

AGENTS.md — Deployment protocol for AI agents

This file is the authoritative protocol for AI agents (Claude Code, Cursor, etc.) deploying Soroka. Humans should read README.md.

Required values from the user

Ask the user for these (and only these) before doing anything else:

• VPS — user@host, e.g. [email protected] or an SSH alias
• TELEGRAM_BOT_TOKEN— from @BotFather
• OWNER_TELEGRAM_ID — from @userinfobot

DO NOT ask the user for any other keys (Jina, Deepgram, OpenRouter, GitHub). Those are collected later via the bot's /start wizard, in Telegram.

If ssh "$VPS" 'echo ok' fails (password prompt or permission denied), stop and tell the user to set up an SSH key first — either ssh-copy-id "$VPS" or the vps-setup-skill (server hardening flow that creates a non-root user with a key).

Deployment

The installer runs on the VPS itself (not from the local machine). Drive it through SSH with the non-interactive flags:

ssh "$VPS" "git clone https://github.com/AndyShaman/Soroka.git soroka \
  && cd soroka \
  && ./bin/install --tg-token '$TELEGRAM_BOT_TOKEN' --owner-id '$OWNER_TELEGRAM_ID'"

If the repo already exists from a previous attempt:

ssh "$VPS" "cd soroka && git pull --ff-only \
  && ./bin/install --tg-token '$TELEGRAM_BOT_TOKEN' --owner-id '$OWNER_TELEGRAM_ID'"

Verify success:

ssh "$VPS" docker ps | grep soroka-bot

Hand-off

After successful deployment, tell the user:

"Готово. Открой Telegram, найди своего бота и отправь /start. Бот проведёт через 6 шагов: ключи Jina, Deepgram, OpenRouter, выбор моделей, GitHub-зеркало и канал-инбокс."

Diagnostics

# Bot logs
ssh "$VPS" docker logs --tail 200 soroka-bot

# Setup wizard state — DB lives inside the repo dir, not /opt/soroka
ssh "$VPS" "cd soroka && sqlite3 data/soroka.db 'SELECT setup_step FROM owners'"

# Note count
ssh "$VPS" "cd soroka && sqlite3 data/soroka.db 'SELECT count(*) FROM notes'"