> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Porta il tuo agente
> Punta il tuo agente di codifica AI, o i tuoi script, all'ambiente cloud che contiene il codice della tua app
Porta il tuo agente di codifica AI, o i tuoi script, in un'app Base44 collegandoti alla sua sandbox. La sandbox è un ambiente cloud privato che contiene il codice del branch attualmente attivo nell'editor dell'app, ed esegue il suo server di sviluppo. È lo stesso ambiente e lo stesso codice che l'editor dell'app Base44 modifica, senza fork o copia da mantenere sincronizzata. Quando scrivi un file tramite un comando sandbox, stai modificando direttamente la tua app reale, sul suo branch attivo, allo stesso modo in cui farebbe l'editor dell'app.
Questo ti permette di sviluppare un'app con i tuoi strumenti invece che con l'editor dell'app, senza checkout locale e nulla da installare. Lavora su un'app da una macchina che non ne ha copia, o esegui uno script per una modifica su un'app che hai costruito interamente nell'editor.
Modificare tramite la sandbox non è lo stesso che pubblicare. La tua modifica diventa parte del codice dell'app subito e appare nell'editor dell'app e nella sua anteprima live, ma per raggiungere il sito pubblico dell'app serve comunque lo stesso passaggio di pubblicazione che servirebbe per una modifica fatta nell'editor.
Hai bisogno di un [**piano Builder**](/Account-and-billing/Billing-and-plans) o superiore per raggiungere la sandbox di un'app dall'esterno dell'editor. Senza, i comandi falliscono con `PREMIUM_REQUIRED`.
La sandbox stessa è un processo di calcolo attivo, non solo storage: si spegne quando resta inattiva per un po', e si riaccende al comando successivo. Il tuo codice non è interessato in nessun caso, poiché vive in git piuttosto che in quel processo. Se la sandbox non è attualmente in esecuzione, il primo comando la avvia, e quella chiamata richiede più tempo di quelle successive.
## Due modi per connettersi
La sandbox espone lo stesso insieme di operazioni tramite due superfici, supportate dalla stessa implementazione. Usa quella che si adatta alla tua configurazione.
* **[CLI](/developers/references/cli/get-started/overview):** adatto a qualsiasi cosa in esecuzione sulla tua macchina, incluso un agente di codifica locale e i tuoi script. Autenticati una volta con [`base44 login`](/developers/references/cli/commands/login), poi indirizza l'app con [`--app-id`](/developers/references/cli/commands/introduction#select-a-target-app) o la variabile d'ambiente `BASE44_APP_ID`. Non è richiesto un progetto locale.
* **[Server MCP](/developers/backend/overview/mcp-server):** adatto a un assistente AI che si connette tramite MCP, inclusi gli assistenti basati sul web che non possono eseguire una CLI. Connettilo una volta e autorizza con OAuth.
| Operazione | Comando CLI | Strumento MCP |
| ---------------------------- | ------------------------------------------------------------------------------ | ------------------- |
| Elenca una directory | [`sandbox ls`](/developers/references/cli/commands/sandbox-ls) | `list_directory` |
| Leggi file | [`sandbox read`](/developers/references/cli/commands/sandbox-read) | `read_file` |
| Cerca contenuti dei file | [`sandbox grep`](/developers/references/cli/commands/sandbox-grep) | `grep` |
| Crea un file | [`sandbox write`](/developers/references/cli/commands/sandbox-write) | `write_file` |
| Modifica un file esistente | [`sandbox edit`](/developers/references/cli/commands/sandbox-edit) | `edit_file` |
| Esegui un comando shell | [`sandbox run`](/developers/references/cli/commands/sandbox-run) | `run_command` |
| Salva un punto di ripristino | [`sandbox checkpoint`](/developers/references/cli/commands/sandbox-checkpoint) | `create_checkpoint` |
I connettori non passano attraverso il file system della sandbox, quindi non sono nella tabella sopra. Per configurare un connettore su un'app con cui stai lavorando in questo modo, usa invece [`connectors initiate`](/developers/references/cli/commands/connectors-initiate). Indirizza lo stesso app id direttamente, senza sandbox o progetto locale.
Il modo più rapido per iniziare con il tuo agente di codifica è usare **Send to Coding Agent** nell'editor dell'app Base44. Su desktop, apri **More actions** (i tre puntini accanto a **Publish**, nell'angolo in alto a destra) e seleziona **Send to Coding Agent**. Scegli un agente CLI locale o una chat web, e ti fornisce un prompt pronto da incollare, così non devi configurare nulla di questo manualmente. Non è offerto per app mobile o app con codice sorgente non gestito.
## Le modifiche vengono salvate automaticamente
Una chiamata [`sandbox write`](/developers/references/cli/commands/sandbox-write) o [`sandbox edit`](/developers/references/cli/commands/sandbox-edit) fa il commit della modifica come parte della stessa richiesta, prima che il comando termini, quindi non c'è un passaggio separato di salvataggio, deploy o push. Una modifica al file fatta tramite [`sandbox run`](/developers/references/cli/commands/sandbox-run), come `rm` o `mv`, viene invece committata qualche secondo dopo, una volta che si chiude una breve finestra di debounce. Se scrivi o modifichi di nuovo prima che un commit precedente sotto debounce sia atterrato, la nuova chiamata attende su di esso e fallisce con `COMMIT_FLUSH_PENDING` se non può confermare che quel commit sia terminato in tempo. Una volta che un commit atterra:
* La modifica è visibile nell'editor dell'app Base44.
* È al sicuro anche se l'ambiente di calcolo della sandbox viene riciclato dopo essere rimasto inattivo, poiché uno nuovo parte sempre dal tuo commit più recente piuttosto che da uno snapshot più vecchio.
* È inclusa la prossima volta che pubblichi l'app.
Le risorse strutturate si sincronizzano allo stesso modo: a differenza di un progetto locale, dove eseguiresti [`entities push`](/developers/references/cli/commands/entities-push) o [`functions deploy`](/developers/references/cli/commands/functions-deploy) dopo aver aggiunto un file, creare `base44/functions/send-email/entry.ts` nella sandbox è tutto ciò che serve per aggiungere quella funzione.
* Non eseguire [`deploy`](/developers/references/cli/commands/deploy), [`functions deploy`](/developers/references/cli/commands/functions-deploy), [`entities push`](/developers/references/cli/commands/entities-push) o gli altri comandi push su un'app che stai modificando nella sua sandbox. Quei comandi sincronizzano un progetto locale con Base44, e non c'è un progetto locale quando si lavora con una sandbox.
* Se la tua ultima azione è stata un comando shell eseguito tramite `sandbox run` piuttosto che una chiamata `write` o `edit`, il suo commit è ancora indietro di un momento. Concedigli qualche secondo prima di disconnetterti.
## Checkpoint
Un checkpoint è un punto di ripristino nella cronologia delle versioni dell'app, ancorato a un commit specifico. Creane uno con [`sandbox checkpoint`](/developers/references/cli/commands/sandbox-checkpoint) per contrassegnare uno stato noto come funzionante, poi ripristinalo dall'editor dell'app se una modifica successiva va storta. Le modifiche in sospeso vengono committate prima che il checkpoint venga preso, così cattura sempre il tuo codice più recente.
## Lavorare a fianco dell'editor dell'app
Il tuo agente di codifica e l'editor dell'app Base44 possono lavorare sulla stessa app allo stesso tempo. Non c'è alcun lock da acquisire e nessuna sessione da rilasciare. Le modifiche da entrambi i lati atterrano nello stesso posto, quindi trattalo come tratteresti un collega che modifica lo stesso progetto.
Non c'è un passaggio di merge. Se il tuo agente di codifica e l'editor dell'app modificano lo stesso file allo stesso tempo, la scrittura che atterra per ultima vince, e la modifica precedente scompare. Evita di far toccare a entrambi i lati lo stesso file nello stesso tratto di lavoro.
## Permessi
Due controlli separati regolano l'accesso alla sandbox: se puoi accedere a questa app in generale, e se la tua sessione corrente ha ottenuto l'accesso in scrittura ad essa.
### Accesso all'app
Hai bisogno dell'accesso admin all'app stessa, come admin del workspace o come collaboratore su questa specifica app. L'accesso viene controllato a ogni chiamata, quindi una modifica al tuo ruolo nel workspace ha effetto immediato.
Un semplice viewer del workspace non può raggiungere la sandbox. L'unica eccezione è un viewer che possiede anche un ruolo legacy di editor per app da prima che il tuo workspace passasse all'accesso basato sui ruoli. Quella combinazione può ancora leggere dalla sandbox, ma non modificare nulla. I superagent non supportano i comandi sandbox.
### Ambito della sessione
Oltre all'accesso all'app, leggere e modificare la sandbox richiede permessi diversi sulla tua sessione:
| Comandi | Permesso necessario |
| -------------------------------------------------------------------- | -------------------------------------------------- |
| `sandbox ls`, `sandbox read`, `sandbox grep` | `apps:read`, concesso per impostazione predefinita |
| `sandbox write`, `sandbox edit`, `sandbox run`, `sandbox checkpoint` | `sandbox:write` |
I permessi della tua sessione sono fissati quando viene creata e non possono essere ampliati in seguito. La CLI chiede `sandbox:write` durante `base44 login`, e tramite MCP lo concedi nel passaggio di consenso OAuth. Rinnovare una sessione esistente non lo aggiunge.
Quindi se i comandi di lettura funzionano ma quelli di modifica falliscono con `NOT_AUTHORIZED`, sei su una sessione che non ha mai avuto `sandbox:write`. Esegui di nuovo [`base44 login`](/developers/references/cli/commands/login), o riconnetti il server MCP e approva l'accesso alla sandbox, per avviare una sessione che ce l'ha.
## Limiti e protezioni
I comandi sui file sono confinati alla radice dell'app. I percorsi assoluti e i percorsi che salgono sopra la radice sono rifiutati con `PATH_OUTSIDE_SANDBOX`. Le directory `.agents` e `.git` non sono raggiungibili dai comandi sui file, e falliscono con `PROTECTED_PATH`, perché contengono i secret della tua app e le credenziali del repository. L'unica eccezione è `.agents/skills`, che puoi leggere e scrivere in modo che il tuo agente possa lavorare con le [skill](/developers/backend/overview/skills) che l'app ha installato.
In tutta la funzionalità, sei limitato a 120 richieste di lettura, 60 richieste di modifica e 30 comandi run al minuto, per app. Superare uno qualsiasi di questi fallisce con `RATE_LIMITED`. La pagina di riferimento di ogni comando copre i suoi limiti di dimensione e conteggio, come quanti percorsi accetta `sandbox read` o quanto grande può essere un file `sandbox write`.
## Vedi anche
* [Server MCP di Base44](/developers/backend/overview/mcp-server): connetti un assistente AI al tuo account Base44
* [Panoramica CLI](/developers/references/cli/get-started/overview): installa e usa la CLI Base44
* [Struttura del progetto](/developers/backend/overview/project-structure): come sono organizzati i file di un progetto Base44
* [Sviluppo locale](/developers/backend/overview/local-dev/local-development-overview): esegui un progetto Base44 sulla tua macchina
* [Skill](/developers/backend/overview/skills): insegna agli agenti di codifica AI come lavorare con Base44
* [`connectors initiate`](/developers/references/cli/commands/connectors-initiate): configura un connettore su un'app senza sandbox o progetto locale
Questa pagina è stata tradotta con l'AI. Per le informazioni più accurate e aggiornate, consulta la [versione inglese](/).