Controllare Claude Code da remoto: SSH, SDK, trigger via canale

Claude Code gira in locale, sulla workstation dove hai il repo, le chiavi SSH, i container. Funziona bene finché sei seduto davanti al PC. Il problema arriva quando esci di casa: una build lunga sta ancora andando, un agente sta refattorizzando un modulo, o semplicemente vuoi lanciare un task senza aspettare di tornare alla scrivania. Ci sono due approcci per controllare Claude Code da remoto, con trade-off molto diversi.

Opzione 1: SSH + tmux, la via vecchia scuola

La soluzione più semplice e meno sorprendente: un server SSH sulla workstation, una sessione tmux o screen persistente, e Claude Code lanciato dentro. Da mobile ci si collega via un client SSH decente e si riprende la sessione dove l’hai lasciata.

• Pro: zero software nuovo. Se SSH è già configurato, bastano tre comandi
• Pro: la sessione sopravvive a disconnessioni mobile
• Contro: su iOS servono client seri (Blink Shell, Prompt 3, Termius), tastiera scomoda
• Contro: la workstation deve essere raggiungibile — IP pubblico, reverse tunnel via Tailscale, o port forwarding sul router
• Contro: copiare/incollare prompt lunghi da smartphone è doloroso

Tailscale o un reverse tunnel (Cloudflare Tunnel, ngrok) evitano di esporre SSH su Internet e risolvono il problema NAT. La sessione tmux diventa il tuo “Claude Code persistente”: chiudi il terminale mobile, rientri più tardi, tutto è ancora lì.

Opzione 2: trigger remoto via SDK

L’alternativa è costruire un ponte: un processo in ascolto su un canale (Telegram, Slack, webhook HTTP, una mailbox IMAP) che riceve messaggi e li inoltra al Claude Agent SDK. A quel punto il “telecomando” diventa qualsiasi cosa sappia mandare testo — un bot Telegram, uno shortcut iOS, un comando vocale.

Il Claude Agent SDK (Python e TypeScript) espone le stesse primitive di Claude Code come libreria. Si avvia un agente programmaticamente, si passa un prompt, si ottiene la risposta. La logica “ascolto canale + sanifico input + lancio agente + rispondo” è codice tuo, ma il cuore è poche righe.

Snippet minimo: dispatcher con Claude Agent SDK

import anyio
from claude_agent_sdk import query, ClaudeAgentOptions

async def run_remote_prompt(prompt: str, cwd: str) -> str:
    options = ClaudeAgentOptions(
        cwd=cwd,
        permission_mode="acceptEdits",  # o "plan" per dry-run
        allowed_tools=["Read", "Grep", "Glob", "Bash"],
    )
    chunks = []
    async for message in query(prompt=prompt, options=options):
        chunks.append(str(message))
    return "\n".join(chunks)

if __name__ == "__main__":
    # esempio: un webhook o un bot avrebbe già validato mittente e input
    result = anyio.run(
        run_remote_prompt,
        "riassumi gli ultimi 3 commit e segnala regressioni evidenti",
        "/home/user/repo",
    )
    print(result)

Questo è lo scheletro. La parte interessante è cosa ci metti davanti: un handler Telegram che verifica l’ID utente, un endpoint FastAPI con token bearer, un listener Gmail che legge solo email firmate. Il pattern è sempre lo stesso: canale autenticato → coda → SDK → risposta sullo stesso canale.

Sicurezza: il vero nodo

Un dispatcher remoto che esegue codice sulla tua macchina è una superficie d’attacco ovvia. Le regole minime:

• Autenticazione forte del mittente: token random lunghi, ID Telegram in allowlist, firme HMAC sui webhook
• Permission mode ristretto: default a plan o acceptEdits, mai bypassPermissions su canali remoti
• Allowlist di tool: un agente remoto non ha bisogno di Write su directory arbitrarie
• Sandbox di directory: il parametro cwd va forzato a un path specifico, mai preso dal messaggio in ingresso
• Rate limit e logging: ogni prompt remoto va registrato con timestamp e sorgente

Chi conosce le https://www.smartworkers.cloud/?p=3425 sa che già in locale conviene limitare cosa può fare un agente. Da remoto il limite va stretto di un altro giro.

Trigger schedulati: cron + SDK

Un’estensione naturale del dispatcher remoto è il trigger a tempo. Cron o un scheduler cloud lancia lo stesso script SDK a orari fissi: ogni mattina alle 8 un agente rilegge il changelog notturno, produce un sommario, lo manda su Telegram. Nessun umano ha chiesto nulla, ma il lavoro è fatto.

Questo pattern si sovrappone ai https://www.smartworkers.cloud/?p=3429: la differenza è che qui l’agente parte da zero ogni volta, senza una sessione interattiva. Task ricorrenti, report, audit di sicurezza schedulati sono candidati ideali.

Latenza, costi, debugging

I limiti pratici da tenere a mente prima di investirci tempo:

• Latenza: una sessione agente che fa ricerche nel repo e chiama tool può impiegare 30-120 secondi. Da mobile non è immediato come una chat
• Costi: sessioni lunghe con molto contesto costano. Un trigger schedulato che gira ogni ora su un repo grosso va monitorato
• Debugging: quando un agente remoto sbaglia, non hai il terminale sotto gli occhi. Il logging strutturato diventa obbligatorio, non opzionale
• Stato: il Claude Agent SDK parte stateless a ogni query. Se vuoi continuità tra messaggi devi gestire tu il thread (file di sessione, database)

Quando ne vale la pena

SSH + tmux è la risposta giusta per il 90% dei casi: sessione interattiva, controllo pieno, niente infrastruttura da mantenere. Il dispatcher SDK ha senso in tre scenari:

• Sessioni autonome di ore che producono output da notificare — build, migrazioni, refactor massivi
• Integrazione con un canale già usato dal team (Slack, Telegram), dove il threshold di attrito è basso
• Schedulazioni ricorrenti che non richiedono presenza umana

Il resto — “voglio chattare col mio codice dal divano” — si risolve meglio con un client SSH mobile serio e una VPN tra telefono e workstation. Meno codice, meno superficie d’attacco, stesso risultato.

La domanda da porsi prima di costruire il dispatcher: il canale remoto mi fa risparmiare davvero tempo, o sto riproducendo un terminale in versione peggiore? Se la risposta è la seconda, SSH basta e avanza.