skate 🛼

Launch an AI-agent bot on a chat channel by answering three questions:

skate is a thin launcher, not a framework. It deploys a small long-poll gateway that bridges the channel to the agent's headless CLI, runs it under systemd, and gets out of the way. Architecture reverse-engineered from openClaw & Hermes — see PLAN.md.

How it works

operator machine                         target VPS (systemd service)
  skate up  ──SSH/rsync──▶  agent CLI (claude) + OAuth creds
                            gateway daemon  ── long-poll ──▶ api.telegram.org
                              ├─ allowlist gate (numeric user IDs)
                              ├─ per-chat session (sqlite + claude --resume)
                              └─ each turn: claude -p --output-format json

Long-polling means no public URL, no inbound ports, no TLS — the bot dials out, so it runs on any box with outbound HTTPS.

Quick start (MVP: Claude Code + Telegram + existing VPS)

1. Create a bot with @BotFather → /newbot → copy the token.
2. Get your numeric user ID from @userinfobot.
3. Deploy:

pip install -e .
skate up \
  --name yann-bot \
  --agent claude --auth oauth \
  --host <vps-ip> --ssh-key ~/.ssh/id_ed25519 \
  --allow 8581449495 \
  --save specs/yann-bot.json
# (prompts for the BotFather token; or pass --token / $TELEGRAM_BOT_TOKEN)

Then message your bot. Manage it:

skate status --spec specs/yann-bot.json
skate logs   --spec specs/yann-bot.json
skate down   --spec specs/yann-bot.json

Test the gateway locally (no VPS)

skate run-local --spec specs/yann-bot.json --token <bot-token>

Auth (OAuth, MVP)

For Claude Code the launcher copies your local ~/.claude/.credentials.json to the target (so the box you run skate up from must be logged in: claude setup-token). API-key auth (--auth api-key) is planned.

Bot commands

/start · /help · /new (reset conversation) · /status. Anything else is sent to the agent.

Status

MVP scaffold. Working: spec model, Telegram long-poll gateway, Claude Code adapter, existing-VPS deploy (rsync + systemd), local run. Planned: codex/gemini/copilot adapters, Hetzner/AWS/GCP/Fly provisioning, Slack/Discord channels, voice/image.