Guida a OpenRouter Shell Tool e Files API (Beta)

Il flusso Shell di OpenRouter è utile quando un modello deve leggere un file, eseguire del codice, analizzare un errore e restituire un artefatto. C’è però un limite da tenere presente: openrouter:shell, i container e la Files API sono ancora in beta. Meglio quindi partire da un’attività circoscritta, non da un processo critico per la produzione.

In breve: quando conviene usare OpenRouter Shell

openrouter:shell mette a disposizione di un modello capace di usare strumenti un ambiente Linux gestito da OpenRouter. Il modello può eseguire comandi, ricevere stdout, stderr e il codice di uscita, quindi correggere il proprio lavoro. La Files API gestisce il passaggio di consegne tra input e output.

È una buona scelta se ti serve:

• Un agente indipendente dal modello, capace di eseguire codice lontano dal server della tua applicazione.
• Un processo ripetibile per elaborare file, ad esempio analizzare CSV, estrarre dati da PDF o generare report.
• Esecuzione di strumenti lato server senza dover costruire subito una sandbox proprietaria.

Non considerarlo però un sostituto diretto della shell locale. La rete è disabilitata per impostazione predefinita, i container non restano automaticamente persistenti e l’API può cambiare durante la beta.

L’architettura da capire prima di iniziare

openrouter:bash è l’alternativa compatibile con Anthropic. Per impostazione predefinita chiede all’applicazione di eseguire i comandi localmente; imposta engine: "openrouter" quando serve l’esecuzione remota, come spiegato nell’annuncio di Shell.

Il percorso di un file nel sistema

1. Carica il file e allegalo alla richiesta

Carica il file con POST /api/v1/files usando dati multipart. Il riferimento per l’upload indica una dimensione massima di 100 MB per singolo file e un parametro query opzionale, workspace_id.

curl -X POST https://openrouter.ai/api/v1/files \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -F "file=@data/sales.csv"

La risposta include metadati come ID del file, nome, tipo MIME, dimensione in byte, ora di creazione e flag downloadable. Inserisci l’ID restituito nell’array file_ids dell’ambiente Shell.

I file allegati vengono copiati nel container e le copie sono scrivibili. Ogni container può ricevere fino a 20 file allegati, secondo l’annuncio di Shell. Modificare la copia non cambia il file originale presente nel workspace.

Un developer ha accolto con favore il supporto alla Files API dopo aver descritto le difficoltà incontrate in precedenza con PDF e OCR: un segnale piccolo ma concreto del fatto che la gestione dei file fosse un vero punto critico dell’integrazione (post).

2. Esegui i comandi, controlla il risultato, correggi il tiro

Il modello invia al container un gruppo di comandi. Ogni esecuzione restituisce l’output e lo stato di uscita, così il modello può correggere uno script fallito invece di limitarsi a fare ipotesi a partire dal prompt originale (annuncio di Shell).

La politica di rete predefinita nega tutto. Se il processo deve scaricare pacchetti o fare richieste esterne, configura una allowlist quando crei il container. OpenRouter documenta le porte 80 e 443 per gli host autorizzati; la policy non può essere modificata dopo l’avvio. Le richieste verso domini fuori dalla allowlist possono fallire con HTTP 520 (annuncio di Shell).

Nei risultati di Shell vengono acquisiti solo i file che si trovano sotto /workspace/home. Se vuoi che l’API li segnali, salva lì l’artefatto. I file creati o modificati da Shell ricevono identificativi cfile_ (annuncio di Shell).

3. Scarica l’output o trasferiscilo nello storage persistente

Un file prodotto da Shell può essere recuperato tramite l’endpoint del contenuto dei file del container:

GET /api/v1/containers/{container_id}/files/{file_id}/content

L’identificativo cfile_ appartiene al container. Se l’artefatto deve sopravvivere al ciclo di vita del container, promuovilo nello storage del workspace. La promozione crea un nuovo identificativo or_file_, che potrà essere allegato a un’esecuzione successiva (annuncio di Shell).

I file dei container vengono conservati per 30 giorni. Promuovi tutto ciò che deve restare disponibile più a lungo (annuncio di Shell). L’endpoint generico per il download restituisce byte grezzi e documenta HTTP 400 per i file caricati dagli utenti. Un upload diretto va quindi considerato un input, non un oggetto generico in stile object storage.

Costi e limiti che possono cambiare il progetto

L’annuncio di Shell di OpenRouter indica un costo di $0.0001 al secondo per il tempo di attività della sandbox. Un container avviato a freddo ha un minimo di 30 secondi, quindi il costo minimo della sandbox è di $0.003 per calcolo. I token vengono conteggiati separatamente.

Riutilizza un container caldo per i passaggi collegati, evita cicli modello-tool non necessari e registra separatamente il costo dei token e quello della sandbox. L’annuncio specifica che la vista Logs mostra l’attività del modello e l’esecuzione della sandbox su righe distinte della timeline.

La struttura di base della richiesta

Lo schema esatto dell’ambiente può cambiare durante la beta, ma il flusso documentato è questo: prima carichi il file, poi passi l’ID restituito a una richiesta che abilita Shell. Mantieni piccolo l’adapter della richiesta, così potrai aggiornarlo facilmente se lo schema della beta dovesse cambiare.

{
  "model": "your/tool-capable-model",
  "tools": [
    {
      "type": "openrouter:shell",
      "environment": {
        "type": "container_auto",
        "file_ids": ["or_file_your_uploaded_file_id"]
      }
    }
  ],
  "input": "Analyze the attached CSV and write a summary to /workspace/home/report.md"
}

Invia questa struttura all’endpoint Responses descritto nell’annuncio. Prima di usarla in produzione, verifica lo schema aggiornato della richiesta e i campi della risposta nella documentazione live dei server tools.

Per la prima integrazione, procedi così:

1. Carica un singolo file di input di piccole dimensioni e salva l’ID restituito.
2. Crea una richiesta per un modello compatibile con i tool, includendo openrouter:shell in tools.
3. Allega esplicitamente il file tramite file_ids.
4. Chiedi al modello di scrivere gli output sotto /workspace/home.
5. Controlla il codice di uscita e l’elenco dei file prima di considerare il job riuscito.
6. Scarica l’artefatto dal container o promuovilo se dovrà essere riutilizzato.
7. Registra in campi separati l’uso dei token e la durata della sandbox.

Per un flusso composto da più richieste, passa un session_id o un riferimento esplicito al container. In caso contrario, la richiesta successiva potrebbe ricevere un container nuovo, privo dello stato precedente.

I problemi più probabili e come prevenirli

Domande frequenti su OpenRouter Shell e Files API

OpenRouter Shell esegue i comandi sul mio computer?

No. openrouter:shell è pensato per eseguire i comandi in una sandbox ospitata da OpenRouter. openrouter:bash, compatibile con Anthropic, ha impostazioni predefinite diverse: usa engine: "openrouter" per l’esecuzione remota (annuncio di Shell).

Come posso conservare i file tra una richiesta e l’altra?

Riutilizza una sessione o un riferimento al container. Senza questo percorso esplicito di riutilizzo, la richiesta successiva potrebbe partire da un container nuovo.

Qual è la differenza tra or_file_ e cfile_?

or_file_ identifica un oggetto della Files API nel workspace. cfile_ identifica un file creato o modificato all’interno di un container. La promozione trasforma un artefatto del container in un nuovo ID di file del workspace.

La Files API prevede un costo separato?

L’annuncio di Shell afferma che l’uso della Files API non comporta un costo separato, mentre lo storage del workspace è limitato a 10 GiB. Il tempo della sandbox Shell e l’uso dei token del modello vengono comunque fatturati secondo le tariffe applicabili.

Lo Shell tool è pronto per la produzione?

È documentato come beta e l’annuncio avverte che l’API potrebbe cambiare. Prima di inserirlo in un flusso di produzione non supervisionato, usa limiti espliciti, comandi circoscritti, restrizioni a livello applicativo e un percorso alternativo.

Ha senso se il flusso produce un artefatto concreto

Shell e Files API di OpenRouter si adattano bene a una pipeline a fasi che produce un CSV ripulito, un report, un’immagine trasformata o un artefatto compilato. Usa ID dei file espliciti, una policy di rete definita in anticipo, il riutilizzo dei container e la promozione per gli output da conservare.

Se il compito consiste soltanto nel fornire una risposta testuale, i costi aggiuntivi della sandbox e la gestione del ciclo di vita non sono necessari. Se invece servono credenziali locali, accesso di rete senza restrizioni o garanzie produttive stringenti, continua a eseguire il lavoro su un’infrastruttura sotto il tuo controllo finché la beta non sarà abbastanza matura per questo livello di rischio.

Fonti: annuncio di OpenRouter su Shell e Files API, riferimento per l’upload della Files API, riferimento per il download del contenuto dei file.