> ## 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.

# Cloud sandbox

> L'ambiente cloud privato che contiene il codice della tua app, e come lavorarci senza una copia locale

Ogni app Base44 ha una sandbox: un ambiente cloud privato che contiene il codice dell'app ed esegue il suo server di sviluppo. È lo stesso ambiente, e lo stesso codice, che l'editor dell'app utilizza, senza fork o copie da mantenere sincronizzate. Connettiti tramite la CLI, un client MCP o l'API per leggere, cercare, modificare ed eseguire comandi sulla tua app da qualsiasi macchina, senza checkout locale e senza nulla da installare.

Quando scrivi un file tramite la sandbox, stai modificando direttamente la tua app reale, allo stesso modo in cui lo farebbe l'editor dell'app. Il motivo più comune per farlo è [portare il tuo agente di codifica](/it/developers/app-code/sandbox/bring-your-own-agent) in un'app che hai creato nell'editor.

<Warning>
  Ti serve un [**Builder plan**](/it/Account-and-billing/Billing-and-plans) o superiore per raggiungere la sandbox di un'app dall'esterno dell'editor. Senza uno, i comandi falliscono con `PREMIUM_REQUIRED`.
</Warning>

## Quando usare la sandbox

Puoi lavorare sul codice di un'app che hai creato nell'editor nei modi seguenti:

| Opzione                                                                | Usala quando                                                                           | Configurazione richiesta                                                                                |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| [Code tab](/it/developers/app-code/editor/code-tab)                    | Vuoi una modifica rapida nel browser.                                                  | Nessuna.                                                                                                |
| Cloud sandbox                                                          | Vuoi che il tuo agente di codifica o i tuoi script modifichino l'app senza scaricarla. | Accedi con la CLI o connettiti tramite MCP.                                                             |
| [GitHub integration](/it/developers/app-code/local-development/github) | Vuoi il codice nel tuo repository e una configurazione locale completa nel tuo IDE.    | Un proprietario dell'app collega un repository una volta. Ogni macchina lo clona poi e installa la CLI. |
| [Eject](/developers/references/cli/commands/eject)                     | Vuoi una copia del codice al di fuori di Base44 che non si sincronizzi.                | Un comando.                                                                                             |

La sandbox e l'integrazione GitHub si sovrappongono maggiormente, poiché entrambe ti permettono di lavorare con i tuoi strumenti. La differenza è dove risiede il codice mentre lavori. Con l'integrazione GitHub, sviluppi in un clone locale e le tue modifiche raggiungono Base44 quando vengono unite a `main`. Con la sandbox, lavori direttamente sul codice dell'app. Non c'è nulla da scaricare, un assistente web-based può usarla, e ogni modifica appare nell'anteprima live dell'editor non appena viene fatta.

## Modi per connettersi

Puoi raggiungere la sandbox nei modi seguenti:

* **[CLI](/developers/references/cli/get-started/overview):** Per un agente di codifica o script che girano sulla tua macchina. Non è richiesto alcun progetto locale. Per la configurazione, consulta [Collegare un agente locale con la CLI](/it/developers/app-code/sandbox/bring-your-own-agent#connect-a-local-agent-with-the-cli).
* **[MCP server](/it/developers/backend/overview/mcp-server):** Per un assistente AI che si connette tramite MCP, inclusi gli assistenti web-based che non possono eseguire una CLI. Per la configurazione, consulta [Collegare un agente tramite MCP](/it/developers/app-code/sandbox/bring-your-own-agent#connect-an-agent-over-mcp).
* **[App Management API](/developers/references/apps-api/get-started/overview):** Per le tue integrazioni personalizzate, usando gli endpoint elencati sotto.

| Operazione                     | Comando CLI                                                                    | Strumento MCP       | Endpoint API                                                              |
| ------------------------------ | ------------------------------------------------------------------------------ | ------------------- | ------------------------------------------------------------------------- |
| Elencare una directory         | [`sandbox ls`](/developers/references/cli/commands/sandbox-ls)                 | `list_directory`    | [List app files](/api-reference/list-app-files)                           |
| Leggere file                   | [`sandbox read`](/developers/references/cli/commands/sandbox-read)             | `read_file`         | [Read app files](/api-reference/read-app-files)                           |
| Cercare nei contenuti dei file | [`sandbox grep`](/developers/references/cli/commands/sandbox-grep)             | `grep`              | [Search app files](/api-reference/search-app-files)                       |
| Creare un file                 | [`sandbox write`](/developers/references/cli/commands/sandbox-write)           | `write_file`        | [Write an app file](/api-reference/write-an-app-file)                     |
| Modificare un file esistente   | [`sandbox edit`](/developers/references/cli/commands/sandbox-edit)             | `edit_file`         | [Edit an app file](/api-reference/edit-an-app-file)                       |
| Eseguire un comando shell      | [`sandbox run`](/developers/references/cli/commands/sandbox-run)               | `run_command`       | [Run a sandbox command](/api-reference/run-a-sandbox-command)             |
| Salvare un punto di ripristino | [`sandbox checkpoint`](/developers/references/cli/commands/sandbox-checkpoint) | `create_checkpoint` | [Create a sandbox checkpoint](/api-reference/create-a-sandbox-checkpoint) |

I connettori non passano dal 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). Punta allo stesso app id direttamente, senza una sandbox o un progetto locale.

## Branch

I comandi della sandbox puntano al branch `main` dell'app se non specifichi diversamente. Per lavorare su un altro [branch](/it/Building-your-app/working-with-branches), esegui [`branches list`](/developers/references/cli/commands/branches-list) per trovarne il nome esatto, poi passa [`--branch <name>`](/developers/references/cli/commands/introduction#target-a-branch) su ogni comando della sandbox. Le letture e le modifiche si applicano quindi solo a quel branch.

## Le modifiche si salvano automaticamente

Una chiamata [`sandbox write`](/developers/references/cli/commands/sandbox-write) o [`sandbox edit`](/developers/references/cli/commands/sandbox-edit) esegue il commit della modifica come parte della stessa richiesta, prima che il comando ritorni, quindi non c'è un passaggio separato di salvataggio, deploy o push. Una modifica di file fatta tramite [`sandbox run`](/developers/references/cli/commands/sandbox-run), come `rm` o `mv`, esegue invece il commit qualche secondo dopo, una volta chiusa una breve finestra di debounce. Se scrivi o modifichi di nuovo prima che un commit precedente in debounce sia arrivato, la nuova chiamata attende su di esso e fallisce con `COMMIT_FLUSH_PENDING` se non riesce a confermare che quel commit sia terminato in tempo.

Le risorse strutturate si sincronizzano nello stesso modo. In un progetto locale, eseguiresti [`entities push`](/developers/references/cli/commands/entities-push) o [`functions deploy`](/developers/references/cli/commands/functions-deploy) dopo aver aggiunto un file. Nella sandbox, creare `base44/functions/send-email/entry.ts` è tutto quello che serve per aggiungere quella funzione.

<Warning>
  **Due regole quando modifichi in una sandbox:**

  * 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. Questi comandi sincronizzano un progetto locale con Base44, e non c'è alcun progetto locale quando lavori con una sandbox.
  * Se la tua ultima azione è stata un comando shell eseguito tramite `sandbox run` invece di una chiamata `write` o `edit`, il suo commit è ancora un momento indietro. Concedigli qualche secondo prima di disconnetterti.
</Warning>

## Modifica e pubblicazione

Modificare tramite la sandbox non è la stessa cosa che pubblicare. La tua modifica diventa parte del codice dell'app subito e appare nell'editor e nella sua anteprima live. Raggiungere il sito pubblico dell'app richiede ancora lo stesso passaggio di pubblicazione di una modifica fatta nell'editor.

## 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 buono conosciuto, poi ripristinalo dall'editor dell'app se una modifica successiva va male. Le modifiche in sospeso vengono committate prima che il checkpoint venga preso, quindi cattura sempre il tuo codice più recente.

## Lavorare insieme all'editor dell'app

Il tuo agente di codifica e l'editor dell'app Base44 possono lavorare sulla stessa app contemporaneamente. Non c'è alcun lock da acquisire e nessuna sessione da rilasciare. Le modifiche da entrambi i lati arrivano nello stesso posto, quindi trattala come tratteresti un collega che modifica lo stesso progetto.

<Warning>
  Non c'è un passaggio di merge. Se il tuo agente di codifica e l'editor dell'app modificano lo stesso file contemporaneamente, vince l'ultima scrittura che arriva, e la modifica precedente è persa. Evita che entrambi i lati tocchino lo stesso file nello stesso periodo di lavoro.
</Warning>

## Avvio e arresto

La sandbox è un processo in esecuzione, non solo storage. Si arresta quando rimane inattiva per un po' e si riavvia al comando successivo. Il tuo codice non è interessato in entrambi i casi. Le modifiche committate vivono in git, e una sandbox riavviata parte sempre dal tuo commit più recente. Se la sandbox non è in esecuzione, il primo comando la avvia, il che significa che quella chiamata probabilmente impiega più tempo di quelle successive.

## Permessi

Due controlli separati regolano l'accesso alla sandbox. Uno è se puoi accedere all'app, e l'altro è se alla tua sessione corrente è stato concesso l'accesso in scrittura.

### Accesso all'app

Ti serve accesso di admin all'app stessa, sia come admin del workspace sia come collaboratore su questa specifica app. L'accesso viene verificato a ogni chiamata, quindi una modifica al tuo ruolo nel workspace ha effetto immediato.

Un semplice viewer del workspace non può raggiungere affatto la sandbox. L'unica eccezione è un viewer che detiene anche un ruolo legacy di editor per singola app di 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 della sandbox.

### Ambito della sessione

Oltre all'accesso all'app, leggere e modificare la sandbox richiedono 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 al momento della sua creazione e non possono essere ampliati in seguito. La CLI richiede `sandbox:write` durante `base44 login`, e tramite MCP lo concedi al 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 lo abbia.

## Limiti e protezioni

I comandi sui file sono confinati alla root dell'app. I percorsi assoluti e i percorsi che salgono sopra la root vengono 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 segreti dell'app e le credenziali del repository. L'unica eccezione è `.agents/skills`, che puoi leggere e scrivere.

Su tutta la funzionalità, hai un limite di 120 richieste di lettura, 60 richieste di modifica e 30 comandi di esecuzione al minuto, per app. Superare uno di questi limiti 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 con `sandbox write`.

## Vedi anche

* [Porta il tuo agente](/it/developers/app-code/sandbox/bring-your-own-agent): Collega il tuo agente di codifica AI alla sandbox di un'app
* [Panoramica CLI](/developers/references/cli/get-started/overview): Installa e usa la CLI di Base44
* [Server MCP di Base44](/it/developers/backend/overview/mcp-server): Collega un assistente AI al tuo account Base44
* [Integrazione GitHub](/it/developers/app-code/local-development/github): Sviluppa localmente con una sincronizzazione bidirezionale sul tuo repository
* [Struttura del progetto](/it/developers/backend/overview/project-structure): Come sono organizzati i file di progetto di Base44

<Note>Questa pagina è stata tradotta utilizzando l'IA. Per informazioni più accurate e aggiornate, consulta la [versione inglese](/). </Note>