​

Base44 in the Cloud Sandbox

Check these references first. This skill and its siblings (base44-remote-dev, base44-sdk) are the source of truth — consult them before searching the web. See Reference order & the complete README.

​

⚡ The mental model: writing the file is the deploy

​

What you can author today

​

Backend functions

base44/functions/
  process-order/
    entry.ts

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 });
});

• Kebab-case directory and function name; entry typically entry.ts.
• createClientFromRequest(req) for a client in the caller’s auth context; base44.asServiceRole.… for admin-level operations.
• Read secrets with Deno.env.get("KEY") (configured in app settings).
• Return with Response.json(body, { status }); handle errors and set appropriate status codes.

Calling the function from the frontend: base44.functions.invoke(name, data) returns the raw axios response — your function’s JSON is on .data (const result = res.data), not the top-level object, and it throws on non-2xx (error body at err.response.data). See the base44-sdk skill’s functions.md for details.

​

Entities

• File name: {kebab-case}.jsonc — e.g. team-member.jsonc for an entity named TeamMember.
• Entity name: PascalCase, alphanumeric only (/^[a-zA-Z0-9]+$/).
• Field names: snake_case.

// 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"]
}

​

Agents

• File name: {agent_name}.jsonc — e.g. support_agent.jsonc.
• Agent name: /^[a-z0-9_]+$/ (lowercase, underscores, 1–100 chars).

// 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?"
}

​

Connectors (OAuth integrations)

Declarative scopes — read before you set. Connecting a connector replaces its scope set with exactly the scopes you pass (it does not merge). Any scope you omit is removed and the user is re-prompted to consent. Always list the connector’s current scopes first and pass the complete desired set (the ones you want to keep plus any new ones).

OAuth needs a human. Connecting returns an authorization URL the user must open in a browser to sign in and consent — you cannot complete it yourself. After they finish, re-list to confirm it’s connected and to read the granted scopes (a provider may grant fewer than you requested).

​

Over MCP (base44-remote-dev transport)

1. list_connectors — { appId, integrationTypes? }. With no integrationTypes, returns the full catalog; each entry has the connector’s name, description, whether it’s connected, and (if connected) its status and granted scopes. Pass integrationTypes for full detail on specific connectors.
2. initiate_connector_connection — { appId, integrationType, scopes, connectionConfig? }. scopes is the complete desired set (see the declarative-scopes note). Returns either already_authorized: true (nothing to do) or a redirect_url for the user to open. After they sign in, call list_connectors again to verify.

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.

​

Over the CLI (projectless, --app-id)

# 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

This is the only Base44 CLI use that belongs in remote-dev — it targets a remote app by id with no local project and no deploy step. It is not a contradiction of the “no CLI” rule above, which is about local-project/deploy commands.

​

Using a connected connector in code

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 });
});

​

Reference order & the complete README

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

​

Workflow in the sandbox

1. Orient — list_directory / read_file / grep (sandbox ls / sandbox read / sandbox grep in the CLI) to understand the app before changing anything.
2. Author — create or edit resource files (backend functions, entities, agents) and frontend code following the conventions above; set up connectors via the connect flow.
3. Verify — optionally run_command (sandbox run) npm run build / npx tsc --noEmit, and use get_app_preview_url to eyeball changes (see base44-remote-dev).
4. Let it ship — do nothing to deploy. Writing the file is the deploy; the auto-commit (~5s) persists and ships it. Pause a moment after your last edit before disconnecting so the commit lands.
5. (Optional) Checkpoint — mark a known-good restore point the user can roll back to with create_checkpoint (base44 sandbox checkpoint --name "..." in the CLI). It flushes pending changes first, so the checkpoint captures your latest code. See base44-remote-dev for details.