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

# Base44 nella sandbox cloud

> Scrivi il codice di un'app Base44 all'interno della sandbox cloud di Base44 con il tuo agente di codifica. Non c'è alcun checkout locale: leggi, scrivi ed esegui file tramite gli strumenti della sandbox (via MCP o la CLI base44 sandbox...

<Warning>
  Questa pagina fa parte di una skill per agenti di codifica IA ed è scritta per gli agenti, non per gli esseri umani. Per la documentazione Base44 leggibile dagli umani, consulta la [documentazione per sviluppatori](/developers).
</Warning>

# Base44 nella sandbox cloud

Scrivi il codice di un'app Base44 **all'interno della sandbox cloud di Base44** con il tuo agente di codifica. Non c'è alcun checkout locale: leggi, scrivi ed esegui file tramite gli strumenti della sandbox (via MCP o la CLI `base44 sandbox`), e la piattaforma effettua build e deploy di ciò che scrivi.

Per **come collegarti** alla sandbox (endpoint MCP o CLI `base44 sandbox`, gli strumenti `read_file` / `write_file` / `edit_file` / `run_command` / `grep` / `list_directory` / `create_checkpoint` — che la CLI espone sotto nomi più brevi (`sandbox read` / `sandbox write` / `sandbox edit` / `sandbox run` / `sandbox grep` / `sandbox ls` / `sandbox checkpoint`), il ciclo modifica→anteprima→verifica, la persistenza e la concorrenza), usa la skill **`base44-remote-dev`**. Questa skill copre **cosa puoi scrivere e come** una volta connesso.

> **Controlla prima questi riferimenti.** Questa skill e le sue sorelle (`base44-remote-dev`, `base44-sdk`) sono la fonte di verità — consultale prima di cercare sul web. Vedi [Ordine dei riferimenti e README completo](#ordine-dei-riferimenti-e-readme-completo).

## ⚡ Il modello mentale: scrivere il file *è* il deploy

Stai lavorando su un'app **remota**, non su un checkout locale. Il flusso CLI a livello di progetto **non** si applica — non eseguire mai `base44 deploy`, `base44 functions deploy`, `base44 ... push`, `base44 create` o `base44 scaffold`. Presuppongono un progetto locale e un passo di deploy manuale che qui non esiste.

Invece: **non appena scrivi un file di risorsa nella sandbox — una funzione backend, un'entità o un agente — la piattaforma effettua il deploy/sync da lì.** La tua scrittura viene auto-committata (debounce di \~5s) e va in produzione. Non esegui, e non devi aspettare, alcun comando `deploy` / `push`.

**Un'unica eccezione — i connettori.** I connettori OAuth non vengono scritti come file; vengono configurati contro l'app remota tramite il suo id, sia con gli strumenti MCP per connettori sia con i comandi dedicati e senza progetto `base44 connectors` (che accettano `--app-id` e non richiedono un progetto locale). Vedi [Connettori](#connettori-integrazioni-oauth) più avanti.

Puoi *ancora* usare `run_command` (`sandbox run` nella CLI) per controlli ordinari (ad esempio `npm run build`, `npx tsc --noEmit`, `npm run lint`) e anteprima — è verifica, non deploy. Vedi il ciclo modifica→anteprima→verifica in `base44-remote-dev`.

## Cosa puoi scrivere oggi

| Risorsa                                    | Stato nella sandbox                                                                                                                  |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Funzioni backend** (`base44/functions/`) | ✅ Supportato — scrivi i file; vengono distribuiti dalla sandbox.                                                                     |
| **Entità** (`base44/entities/`)            | ✅ Supportato — scrivi il file schema `.jsonc`; si auto-sincronizza. Nessun `entities push`.                                          |
| **Agenti** (`base44/agents/`)              | ✅ Supportato — scrivi il file di configurazione `.jsonc`; si auto-sincronizza. Nessun `agents push`.                                 |
| **Codice frontend** (`src/…`)              | ✅ Supportato — modifica normalmente; HMR/anteprima lo riflette. Usa la skill **`base44-sdk`** per l'uso dell'API SDK.                |
| **Connettori** (integrazioni OAuth)        | ✅ Supportato — configurati tramite il flusso di connessione qui sotto (strumenti MCP o `base44 connectors`), **non** scrivendo file. |

## Funzioni backend

Le funzioni backend vivono in `base44/functions/`, una directory per funzione (nome kebab-case). Nella sandbox devi solo creare il file **`entry.ts`** direttamente sotto `base44/functions/<name>/` — **non è richiesto alcun `function.jsonc`** (la sandbox deduce la funzione dalla directory; il file di configurazione viene ignorato in questa modalità):

```
base44/functions/
  process-order/
    entry.ts
```

File entry — le funzioni girano su **Deno** (non Node.js), esportano con `Deno.serve()` e usano il prefisso `npm:` per i pacchetti npm:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);   // inherits the caller's auth
  const { orderId } = await req.json();
  const order = await base44.entities.Orders.get(orderId);
  return Response.json({ success: true, order });
});
```

Convenzioni:

* Nome della directory e della funzione in **kebab-case**; entry tipicamente `entry.ts`.
* `createClientFromRequest(req)` per un client nel contesto di autenticazione del chiamante; `base44.asServiceRole.…` per operazioni a livello admin.
* Leggi i segreti con `Deno.env.get("KEY")` (configurati nelle impostazioni dell'app).
* Rispondi con `Response.json(body, { status })`; gestisci gli errori e imposta codici di stato appropriati.

Questo è sufficiente per scrivere correttamente le funzioni. Per dettagli più approfonditi e più esempi (ruolo di servizio, segreti, errori comuni), consulta il riferimento della skill `base44-cli`: [`functions-create.md`](https://docs.base44.com/developers/skills/base44-sandbox/../base44-cli/references/functions-create.md) — ma **ignora le sue sezioni "Deploying Functions" / CLI** e le sue indicazioni su **`function.jsonc`**, che presuppongono un progetto locale e non si applicano nella sandbox (qui scrivi solo `entry.ts`).

> **Chiamare la funzione dal frontend:** `base44.functions.invoke(name, data)` restituisce la **risposta axios grezza** — il JSON della tua funzione è su **`.data`** (`const result = res.data`), non sull'oggetto di livello superiore, e **lancia eccezioni su non-2xx** (corpo di errore in `err.response.data`). Vedi la skill `base44-sdk` [`functions.md`](https://docs.base44.com/developers/skills/base44-sandbox/../base44-sdk/references/functions.md) per i dettagli.

## Entità

Un file `.jsonc` per entità in `base44/entities/`. Scrivi semplicemente il file — si auto-sincronizza; **non eseguire `base44 entities push` o `deploy`.**

* **Nome file:** `{kebab-case}.jsonc` — es. `team-member.jsonc` per un'entità chiamata `TeamMember`.
* **`name` dell'entità:** PascalCase, solo alfanumerico (`/^[a-zA-Z0-9]+$/`).
* **Nomi dei campi:** `snake_case`.

```jsonc theme={null}
// base44/entities/task.jsonc
{
  "name": "Task",
  "type": "object",
  "properties": {
    "title": { "type": "string", "description": "Task title" },
    "status": { "type": "string", "enum": ["todo", "doing", "done"], "default": "todo" },
    "due_date": { "type": "string", "format": "date" },
    "board_id": { "type": "string", "description": "Owning board" }
  },
  "required": ["title"]
}
```

Tipi dei campi: `string`, `number`, `integer`, `boolean`, `array`, `object`, `binary`. I formati stringa includono `date`, `date-time`, `email`, `uri`, `uuid`, `file`, `richtext`. Per i dettagli completi dello schema e la row-level security (RLS), consulta i riferimenti `base44-cli` [`entities-create.md`](https://docs.base44.com/developers/skills/base44-sandbox/../base44-cli/references/entities-create.md) e [`rls-examples.md`](https://docs.base44.com/developers/skills/base44-sandbox/../base44-cli/references/rls-examples.md) — ma **ignora le loro sezioni `entities push` / deploy**; la sandbox sincronizza il file per te.

## Agenti

Un file `.jsonc` per agente in `base44/agents/`. Scrivi semplicemente il file — si auto-sincronizza; **non eseguire `base44 agents push` o `deploy`.**

* **Nome file:** `{agent_name}.jsonc` — es. `support_agent.jsonc`.
* **`name` dell'agente:** `/^[a-z0-9_]+$/` (minuscole, underscore, 1–100 caratteri).

```jsonc theme={null}
// base44/agents/support_agent.jsonc
{
  "name": "support_agent",
  "description": "Brief description of what this agent does",
  "instructions": "Detailed instructions for the agent's behavior",
  "tool_configs": [
    { "entity_name": "tasks", "allowed_operations": ["read", "create", "update", "delete"] },
    { "function_name": "send_email", "description": "Send an email notification" }
  ],
  "whatsapp_greeting": "Hello! How can I help you today?"
}
```

Richiesti: `name`, `description`, `instructions`. Opzionali: `tool_configs` (default `[]`), `whatsapp_greeting`. Le tool config sono o uno **strumento entità** (`entity_name` + `allowed_operations`: uno tra `read`/`create`/`update`/`delete`) o uno **strumento funzione backend** (`function_name` + `description`). Per lo schema completo dell'agente, consulta la sezione **Agent Schema** di [`SKILL.md`](https://docs.base44.com/developers/skills/base44-sandbox/../base44-cli/SKILL.md) della skill `base44-cli` — ma **ignora i suoi comandi `agents push` / `agents pull` / deploy**, che presuppongono un progetto locale; nella sandbox il file si auto-sincronizza.

## Connettori (integrazioni OAuth)

I connettori (Google Calendar, Gmail, Slack, …) forniscono alle tue funzioni backend token per chiamare API di terze parti. In remote-dev non ci sono **file di connettori da scrivere** — operi direttamente sul connettore contro l'app tramite il suo id. Due superfici, stesso backend e stesso comportamento:

> **Scope dichiarativi — leggi prima di impostare.** Connettere un connettore **sostituisce** il suo insieme di scope esattamente con gli scope che passi (non fonde). Qualsiasi scope che ometti viene rimosso e all'utente viene richiesto nuovamente il consenso. **Elenca sempre prima gli scope attuali del connettore e passa l'insieme desiderato completo** (quelli che vuoi mantenere **più** quelli nuovi).

> **OAuth richiede un umano.** La connessione restituisce un **URL di autorizzazione** che l'utente deve aprire in un browser per accedere e dare il consenso — non puoi completarlo tu stesso. Dopo che ha finito, elenca di nuovo per confermare che è connesso e leggere gli scope **concessi** (un provider potrebbe concederne meno di quelli richiesti).

### Tramite MCP (trasporto `base44-remote-dev`)

Due strumenti, entrambi accettano `appId`. Scope: `list_connectors` richiede `apps:read`; `initiate_connector_connection` richiede `apps:write` (nota: **non** `sandbox:write`).

1. **`list_connectors`** — `{ appId, integrationTypes? }`. Senza `integrationTypes`, restituisce il catalogo completo; ogni voce ha il nome del connettore, la descrizione, se è connesso e (se connesso) il suo stato e gli scope concessi. Passa `integrationTypes` per il dettaglio completo su connettori specifici.
2. **`initiate_connector_connection`** — `{ appId, integrationType, scopes, connectionConfig? }`. `scopes` è l'insieme desiderato **completo** (vedi la nota sugli scope dichiarativi). Restituisce o `already_authorized: true` (niente da fare) o un `redirect_url` che l'utente deve aprire. Dopo che ha effettuato l'accesso, chiama di nuovo `list_connectors` per verificare.

```
On appId <APP_ID>: call list_connectors to read googlecalendar's current scopes,
then initiate_connector_connection for googlecalendar with the full scope set
(existing + the calendar.events scope I need). Give me the authorization URL.
```

### Tramite CLI (senza progetto, `--app-id`)

Questi sottocomandi `base44 connectors` funzionano **senza un progetto locale** — risolvono l'id dell'app da `--app-id`, poi `BASE44_APP_ID`, poi un `.app.jsonc` locale. Non è richiesto alcun `config.jsonc`.

```bash theme={null}
# 1. See available integration types for the app
npx base44 connectors list-available --app-id <APP_ID>

# 2. Initialize the connector and start OAuth (sets it to EXACTLY these scopes).
#    Non-interactive: prints the authorization URL. Interactive: also opens the
#    browser and polls until authorized.
npx base44 connectors initiate --app-id <APP_ID> \
  --integration-type googlecalendar \
  --scopes https://www.googleapis.com/auth/calendar.readonly https://www.googleapis.com/auth/calendar.events

# 3. (optional) Fetch the resulting connector config
npx base44 connectors pull --app-id <APP_ID> --dir ./connectors
```

`--scopes` accetta un elenco separato da spazi o virgole. Come con MCP, l'utente deve aprire l'URL di autorizzazione stampato per finire il consenso; successivamente `list-available` / `pull` riflettono lo stato connesso e gli scope concessi.

> Questo è l'**unico** uso della CLI di Base44 che appartiene a remote-dev — punta a un'app remota tramite id senza progetto locale e senza passo di deploy. Non è in contraddizione con la regola "no CLI" sopra, che riguarda i comandi di progetto locale/deploy.

### Usare un connettore connesso nel codice

Connettere autorizza solo il connettore. Per chiamare effettivamente l'API di terze parti, recupera il suo token di accesso OAuth **all'interno di una funzione backend** con il modulo connectors del ruolo di servizio — `base44.asServiceRole.connectors.getConnection(integrationType)` — e usa `accessToken` restituito (e `connectionConfig` opzionale) nel tuo `fetch`:

```typescript theme={null}
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);

  // App-scoped OAuth token — backend / service role only.
  const { accessToken, connectionConfig } =
    await base44.asServiceRole.connectors.getConnection("googlecalendar");

  const events = await fetch(
    "https://www.googleapis.com/calendar/v3/calendars/primary/events",
    { headers: { Authorization: `Bearer ${accessToken}` } },
  ).then((r) => r.json());

  return Response.json({ events });
});
```

Note: il connettore ha **scope dell'app** (un account connesso condiviso da tutti gli utenti); Base44 aggiorna il token per te; tu effettui le chiamate API. `getConnection()` sostituisce il deprecato `getAccessToken()`. Per il riferimento completo del modulo (firme, `connectionConfig`, l'elenco dei servizi disponibili e i loro identificatori di tipo), consulta la skill `base44-sdk` [`connectors.md`](https://docs.base44.com/developers/skills/base44-sandbox/../base44-sdk/references/connectors.md).

## Ordine dei riferimenti e README completo

**Consulta i riferimenti in questa skill e nelle sue skill sorelle (`base44-remote-dev`, `base44-sdk`) prima di cercare sul web.** Sono la fonte di verità per il bridge sandbox, le convenzioni file/risorse e le API SDK — preferiscili ai risultati generici di internet, che sono spesso obsoleti o errati per Base44.

Per il riferimento remote-dev completo e specifico per l'app (istruzioni + ogni endpoint, pubblico, non richiede autenticazione per il recupero), leggi il README di onboarding per la tua app:

```
https://app.base44.com/api/sandbox/<APP_ID>/local-agent/readme.md
```

(L'equivalente cloud/MCP è `…/api/sandbox/<APP_ID>/claude-web/readme.md`.) Consulta la skill `base44-remote-dev` per la meccanica di connessione descritta da questo README.

## Flusso di lavoro nella sandbox

1. **Orientati** — `list_directory` / `read_file` / `grep` (`sandbox ls` / `sandbox read` / `sandbox grep` nella CLI) per capire l'app prima di cambiare qualcosa.
2. **Scrivi** — crea o modifica file di risorse (funzioni backend, entità, agenti) e codice frontend seguendo le convenzioni sopra; configura i connettori tramite il flusso di connessione.
3. **Verifica** — opzionalmente `run_command` (`sandbox run`) `npm run build` / `npx tsc --noEmit`, e usa `get_app_preview_url` per verificare visivamente le modifiche (vedi `base44-remote-dev`).
4. **Lascia che venga distribuito** — **non fare nulla** per distribuire. Scrivere il file è il deploy; l'auto-commit (\~5s) persiste e lo distribuisce. Fai una pausa dopo l'ultima modifica prima di disconnetterti così che il commit atterri.
5. **(Opzionale) Checkpoint** — contrassegna un punto di ripristino noto e funzionante a cui l'utente può tornare con `create_checkpoint` (`base44 sandbox checkpoint --name "..."` nella CLI). Scarica prima le modifiche in sospeso, così il checkpoint cattura il tuo codice più recente. Vedi `base44-remote-dev` per i dettagli.

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