64 lines
3.2 KiB
Markdown
64 lines
3.2 KiB
Markdown
# xBot
|
|
|
|
AI-powered Twitter/X bot that generates tweets via the Anthropic Claude API and posts them using stealth browser automation through Kernel.sh (residential proxies + CAPTCHA solving).
|
|
|
|
## Key Features
|
|
- AI tweet generation (claude-sonnet-4-6, max 280 tokens)
|
|
- Multi-account support (credentials keyed by account name in .env)
|
|
- Configurable scheduling (daily or random interval posting)
|
|
- Tweet history tracking to avoid repetition
|
|
- Link injection (URLs added post-generation, never sent to AI)
|
|
- Anti-detection: keyboard.type() with delays, adaptive login flow
|
|
|
|
## Tech Stack
|
|
Node.js 18+ (ES modules), @onkernel/sdk, dotenv
|
|
|
|
## Project Structure
|
|
- `bot.js` — Core logic: login to X, generate tweet via Claude, post it
|
|
- `scheduler.js` — Picks random times within a window, invokes bot.js via child_process
|
|
- `cron.js` — Docker entrypoint: writes prompts.json from env, fires scheduler.js daily at 4pm UTC
|
|
- `Dockerfile` — Node 18 alpine image
|
|
- `package.json` — Dependencies & scripts
|
|
- `prompts.json` — Prompt configs with account mapping, schedule, and link placeholders (not tracked)
|
|
- `infra/docker-compose.yml` — One service per prompt, named volume for history files
|
|
- `infra/deploy-stack.sh` — Deploys stack to Portainer (run once, or on compose changes)
|
|
- `infra/.env` — All secrets + PROMPTS_JSON (not tracked)
|
|
- `infra/.env.example` — Template
|
|
|
|
## Entry Points
|
|
- `node bot.js <prompt-name>` — Post a single tweet immediately (local dev)
|
|
- `node scheduler.js <prompt-name>` — Schedule random posts for the day (local dev)
|
|
- `node cron.js` — Docker entrypoint (production)
|
|
|
|
## External Services
|
|
| Service | Purpose | Config Key |
|
|
|---------|---------|------------|
|
|
| **Kernel.sh** | Stealth browser automation (residential proxies, CAPTCHA solving, Playwright) | `KERNEL` env var |
|
|
| **Anthropic Claude API** | Tweet generation | `ANTHROPIC` env var |
|
|
| **X/Twitter** | Target platform for posting | Per-account: `{PREFIX}_USER`, `{PREFIX}_PW`, `{PREFIX}_EMAIL`, `{PREFIX}_PHONE` |
|
|
|
|
Multi-account credentials use uppercase prefix pattern in .env (e.g., MYACCOUNT_USER, MYACCOUNT_PW).
|
|
|
|
## Deployment
|
|
Deployed on **docker-server** (Portainer):
|
|
- Portainer: `https://portainer-1.docker.pq.io`
|
|
- Registry: `registry.docker.pq.io`
|
|
- Stack: `xbot`
|
|
- Containers: `xbot-<account>-<prompt>` (e.g. `xbot-thejunipersky-tease`)
|
|
- Scheduling: `cron.js` fires at 4pm UTC daily — no host cron needed
|
|
|
|
### To redeploy after code changes
|
|
1. Boot a t3.micro x86 build machine in AWS us-west-2 (key: `twitter-bot-key`, SG: `sg-088158905150b9051`, subnet: `subnet-08fe6b8d1dc82f243`)
|
|
2. Build and push: `docker build --platform linux/amd64 -t registry.docker.pq.io/xbot:latest . && docker push registry.docker.pq.io/xbot:latest`
|
|
3. Watchtower auto-restarts containers within 30s
|
|
4. Terminate build machine
|
|
|
|
### To redeploy after compose/config changes
|
|
Run `infra/deploy-stack.sh` with `PORTAINER_URL` and `PORTAINER_API_KEY` set.
|
|
|
|
## Guidelines
|
|
- All changes must preserve stealth/anti-detection behavior and multi-account architecture
|
|
- bot.js is the core; scheduler.js orchestrates timing
|
|
- Config lives in .env + prompts.json
|
|
- All project memory/context stays in this file (or a `CLAUDE-memory/` folder in the repo) — never save to the external `~/.claude/projects/.../memory/` system
|