From feada8877bf3d31c20c15bd91b30ab0105b62306 Mon Sep 17 00:00:00 2001 From: carmelc Date: Wed, 17 Jun 2026 15:20:59 +0300 Subject: [PATCH 01/15] feat(base44-sandbox): add cloud-sandbox remote-dev skill flavor MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a focused, separately-installable "sandbox flavor" for developing a Base44 app inside Base44's cloud sandbox (PR base44-dev/apper#11608), where the implementation is remote and writing a backend-function file is what ships it — no local checkout and no Base44 CLI. - skills/base44-sandbox: new hand-authored skill. Backend functions and frontend code are supported; entities, connectors, and agents are marked not-supported-yet; no automations. Concise inline guidance with a pointer to base44-cli's functions-create reference (no duplicated copies). - skills/base44-remote-dev: vendored connection skill (MCP / HTTP bridge, tools, edit→preview→verify loop) from the upstream PR. - New base44-sandbox plugin across channels: second entry in the Claude and Codex marketplaces + plugins/base44-sandbox/ bundle (its own .claude/.codex/ .cursor manifests + skills/assets symlinks). Bundles base44-remote-dev, base44-sandbox, base44-sdk, base44-troubleshooter; excludes deploy-oriented base44-cli. npx skills --skill documented in the README. - validate-template.mjs now discovers and validates all .cursor-plugin manifests (repo root + plugins/*/). - sync-cli-skill flags base44-sandbox for manual review when function authoring conventions change. Co-Authored-By: Claude Opus 4.8 (1M context) --- .agents/plugins/marketplace.json | 12 + .claude-plugin/marketplace.json | 12 + .claude/skills/sync-cli-skill/SKILL.md | 4 + README.md | 17 ++ .../base44-sandbox/.claude-plugin/plugin.json | 14 + .../base44-sandbox/.codex-plugin/plugin.json | 24 ++ .../base44-sandbox/.cursor-plugin/plugin.json | 16 + plugins/base44-sandbox/assets | 1 + plugins/base44-sandbox/skills | 1 + scripts/validate-template.mjs | 53 +++- skills/base44-remote-dev/SKILL.md | 286 ++++++++++++++++++ skills/base44-sandbox/SKILL.md | 74 +++++ 12 files changed, 506 insertions(+), 8 deletions(-) create mode 100644 plugins/base44-sandbox/.claude-plugin/plugin.json create mode 100644 plugins/base44-sandbox/.codex-plugin/plugin.json create mode 100644 plugins/base44-sandbox/.cursor-plugin/plugin.json create mode 120000 plugins/base44-sandbox/assets create mode 120000 plugins/base44-sandbox/skills create mode 100644 skills/base44-remote-dev/SKILL.md create mode 100644 skills/base44-sandbox/SKILL.md diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index 8e7aee7..04ba8c3 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -15,6 +15,18 @@ "authentication": "ON_INSTALL" }, "category": "Coding" + }, + { + "name": "base44-sandbox", + "source": { + "source": "local", + "path": "./plugins/base44-sandbox" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Coding" } ] } diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 4cbd15c..70feb6e 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -19,6 +19,18 @@ "license": "MIT", "keywords": ["base44", "full-stack", "sdk", "cli", "deployment"], "category": "development" + }, + { + "name": "base44-sandbox", + "source": "./plugins/base44-sandbox", + "description": "Develop a Base44 app remotely in Base44's cloud sandbox — no local files, no deploy/push. Resource conventions for entities, functions, agents, and connectors, plus SDK and troubleshooting.", + "version": "1.0.0-beta.1", + "author": { "name": "base44" }, + "homepage": "https://docs.base44.com", + "repository": "https://github.com/base44/skills", + "license": "MIT", + "keywords": ["base44", "sandbox", "remote-dev", "mcp", "entities", "backend-functions"], + "category": "development" } ] } diff --git a/.claude/skills/sync-cli-skill/SKILL.md b/.claude/skills/sync-cli-skill/SKILL.md index b91a602..d12fa2a 100644 --- a/.claude/skills/sync-cli-skill/SKILL.md +++ b/.claude/skills/sync-cli-skill/SKILL.md @@ -314,6 +314,10 @@ After processing all changed commands, update the SKILL.md of each affected skil - Keep the existing structure and formatting of each skill - Do NOT change the frontmatter description unless explicitly asked +### Step 6b: Flag base44-sandbox for review + +The `skills/base44-sandbox/` skill (the cloud-sandbox flavor) is **hand-authored** and self-contained — it carries its own concise guidelines and links out to `base44-cli`'s references rather than copying them, so this sync does not edit it automatically. If this sync changed the backend-function authoring conventions in `skills/base44-cli/references/functions-create.md` (directory layout, `function.jsonc` shape, Deno entry-point conventions, naming rules), **flag `skills/base44-sandbox/SKILL.md` for manual review** in the summary so its inline guidance can be updated to match. + ### Step 7: Update CLI_VERSION and Skill Frontmatter After successfully updating all changed commands: diff --git a/README.md b/README.md index 57dc03b..47e8e45 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,21 @@ npx skills add base44/skills npx skills add base44/skills -g ``` +### Sandbox flavor (remote dev — no local files) + +If you develop your app inside **Base44's cloud sandbox** (the platform auto-builds, auto-commits, and auto-syncs, so you never run deploy/push), install the focused `base44-sandbox` plugin instead of the full set. It bundles `base44-remote-dev`, `base44-sandbox`, `base44-sdk`, and `base44-troubleshooter` — and deliberately excludes the deploy-oriented `base44-cli`. + +```bash +# Claude Code +claude plugin install base44-sandbox@base44-skills + +# Codex CLI: register the marketplace, then /plugins → "Base44 Sandbox" → Install +codex plugin marketplace add base44/skills + +# Other agents (skills CLI) +npx skills add base44/skills --skill base44-remote-dev --skill base44-sandbox --skill base44-sdk --skill base44-troubleshooter +``` + ## Available Skills | Skill | Description | @@ -52,6 +67,8 @@ npx skills add base44/skills -g | [`base44-cli`](skills/base44-cli/SKILL.md) | Create and manage Base44 projects using the CLI. Handles resource configuration (entities, backend functions, AI agents), initialization, and deployment. | | [`base44-sdk`](skills/base44-sdk/SKILL.md) | Build apps using the Base44 JavaScript SDK. Communicate with remote resources like entities, backend functions, and AI agents. | | [`base44-troubleshooter`](skills/base44-troubleshooter/SKILL.md) | Troubleshoot production issues using backend function logs. Use when investigating app errors or diagnosing production problems. | +| [`base44-remote-dev`](skills/base44-remote-dev/SKILL.md) | Develop a Base44 app remotely from your own coding agent by connecting it to the Base44 sandbox over MCP or the HTTP bridge. | +| [`base44-sandbox`](skills/base44-sandbox/SKILL.md) | Author Base44 app code inside the cloud sandbox — no CLI; writing a backend-function file into the sandbox is what ships it. | ## About Agent Skills diff --git a/plugins/base44-sandbox/.claude-plugin/plugin.json b/plugins/base44-sandbox/.claude-plugin/plugin.json new file mode 100644 index 0000000..41d5c97 --- /dev/null +++ b/plugins/base44-sandbox/.claude-plugin/plugin.json @@ -0,0 +1,14 @@ +{ + "name": "base44-sandbox", + "version": "1.0.0-beta.1", + "description": "Develop a Base44 app remotely in Base44's cloud sandbox; conventions only, no deploy/push.", + "author": { + "name": "base44", + "url": "https://base44.com" + }, + "homepage": "https://docs.base44.com", + "repository": "https://github.com/base44/skills", + "license": "MIT", + "keywords": ["base44", "sandbox", "remote-dev", "mcp", "entities", "backend-functions"], + "skills": ["./skills/base44-remote-dev/", "./skills/base44-sandbox/", "./skills/base44-sdk/", "./skills/base44-troubleshooter/"] +} diff --git a/plugins/base44-sandbox/.codex-plugin/plugin.json b/plugins/base44-sandbox/.codex-plugin/plugin.json new file mode 100644 index 0000000..76d955f --- /dev/null +++ b/plugins/base44-sandbox/.codex-plugin/plugin.json @@ -0,0 +1,24 @@ +{ + "name": "base44-sandbox", + "version": "1.0.0-beta.1", + "description": "Develop a Base44 app remotely in Base44's cloud sandbox; conventions only, no deploy/push.", + "author": { + "name": "base44", + "url": "https://base44.com" + }, + "homepage": "https://docs.base44.com", + "repository": "https://github.com/base44/skills", + "license": "MIT", + "keywords": ["base44", "sandbox", "remote-dev", "mcp", "entities", "backend-functions"], + "skills": ["./skills/base44-remote-dev/", "./skills/base44-sandbox/", "./skills/base44-sdk/", "./skills/base44-troubleshooter/"], + "interface": { + "displayName": "Base44 Sandbox", + "shortDescription": "Develop Base44 apps remotely in the cloud sandbox from Codex", + "longDescription": "Develop a Base44 app inside Base44's cloud sandbox where the platform auto-builds, auto-commits, and auto-syncs. Includes conventions for entities, functions, agents, and connectors, SDK development, and production troubleshooting — without deploy/push commands.", + "developerName": "base44", + "category": "Coding", + "capabilities": ["Interactive", "Read", "Write"], + "websiteURL": "https://base44.com", + "logo": "./assets/base44-logo.png" + } +} diff --git a/plugins/base44-sandbox/.cursor-plugin/plugin.json b/plugins/base44-sandbox/.cursor-plugin/plugin.json new file mode 100644 index 0000000..060b8cf --- /dev/null +++ b/plugins/base44-sandbox/.cursor-plugin/plugin.json @@ -0,0 +1,16 @@ +{ + "name": "base44-sandbox", + "displayName": "Base44 Sandbox", + "version": "1.0.0-beta.1", + "description": "Develop a Base44 app remotely in Base44's cloud sandbox; conventions only, no deploy/push.", + "author": { + "name": "base44", + "url": "https://base44.com" + }, + "homepage": "https://docs.base44.com", + "repository": "https://github.com/base44/skills", + "license": "MIT", + "logo": "./assets/base44-logo.png", + "keywords": ["base44", "sandbox", "remote-dev", "mcp", "entities", "backend-functions"], + "skills": ["./skills/base44-remote-dev/", "./skills/base44-sandbox/", "./skills/base44-sdk/", "./skills/base44-troubleshooter/"] + } diff --git a/plugins/base44-sandbox/assets b/plugins/base44-sandbox/assets new file mode 120000 index 0000000..41aef43 --- /dev/null +++ b/plugins/base44-sandbox/assets @@ -0,0 +1 @@ +../../assets \ No newline at end of file diff --git a/plugins/base44-sandbox/skills b/plugins/base44-sandbox/skills new file mode 120000 index 0000000..5dcab58 --- /dev/null +++ b/plugins/base44-sandbox/skills @@ -0,0 +1 @@ +../../skills \ No newline at end of file diff --git a/scripts/validate-template.mjs b/scripts/validate-template.mjs index bf5118e..1661f17 100644 --- a/scripts/validate-template.mjs +++ b/scripts/validate-template.mjs @@ -217,12 +217,35 @@ async function validateComponentFrontmatter(pluginDir, pluginName) { } } -async function main() { - const pluginDir = repoRoot; +async function discoverPluginDirs() { + // Every directory containing a .cursor-plugin/plugin.json is a plugin to validate: + // the repo root plus any bundle under plugins/*/. + const dirs = []; + if (await pathExists(path.join(repoRoot, ".cursor-plugin", "plugin.json"))) { + dirs.push(repoRoot); + } + + const pluginsRoot = path.join(repoRoot, "plugins"); + if (await pathExists(pluginsRoot)) { + const entries = await fs.readdir(pluginsRoot, { withFileTypes: true }); + for (const entry of entries) { + if (!entry.isDirectory()) { + continue; + } + const candidate = path.join(pluginsRoot, entry.name); + if (await pathExists(path.join(candidate, ".cursor-plugin", "plugin.json"))) { + dirs.push(candidate); + } + } + } + + return dirs; +} + +async function validatePlugin(pluginDir) { const manifestPath = path.join(pluginDir, ".cursor-plugin", "plugin.json"); const pluginManifest = await readJsonFile(manifestPath, "Plugin manifest"); if (!pluginManifest) { - summarizeAndExit(); return; } @@ -230,7 +253,7 @@ async function main() { if (typeof pluginManifest.name !== "string" || !pluginNamePattern.test(pluginManifest.name)) { addError( - '"name" in plugin.json must be lowercase and use only alphanumerics, hyphens, and periods.' + `${pluginName}: "name" in plugin.json must be lowercase and use only alphanumerics, hyphens, and periods.` ); } @@ -243,15 +266,29 @@ async function main() { } await validateComponentFrontmatter(pluginDir, pluginName); +} + +async function main() { + const pluginDirs = await discoverPluginDirs(); + if (pluginDirs.length === 0) { + addError("No .cursor-plugin/plugin.json manifest found at the repo root or under plugins/*/."); + summarizeAndExit(); + return; + } + + for (const pluginDir of pluginDirs) { + await validatePlugin(pluginDir); + } - const hooksPath = path.join(pluginDir, "hooks", "hooks.json"); + // hooks/mcp checks apply to the repo root only (shared plugin assets). + const hooksPath = path.join(repoRoot, "hooks", "hooks.json"); if (!(await pathExists(hooksPath))) { - addWarning(`${pluginName}: no hooks/hooks.json file found (only needed when using hooks).`); + addWarning("no hooks/hooks.json file found (only needed when using hooks)."); } - const mcpPath = path.join(pluginDir, "mcp.json"); + const mcpPath = path.join(repoRoot, "mcp.json"); if (!(await pathExists(mcpPath))) { - addWarning(`${pluginName}: no mcp.json file found (only needed when using MCP servers).`); + addWarning("no mcp.json file found (only needed when using MCP servers)."); } summarizeAndExit(); diff --git a/skills/base44-remote-dev/SKILL.md b/skills/base44-remote-dev/SKILL.md new file mode 100644 index 0000000..007d026 --- /dev/null +++ b/skills/base44-remote-dev/SKILL.md @@ -0,0 +1,286 @@ +--- +name: base44-remote-dev +description: >- + Develop a Base44 app remotely from your own coding agent (Claude Code, + claude.ai, or any MCP client) by connecting it to the Base44 sandbox. Cloud + agents connect over MCP; local/filesystem agents can instead use the HTTP + REST surface with a Base44 CLI token (Section 10). Covers connecting/ + authenticating, the available sandbox tools (run_command, read_file, + write_file, edit_file, grep, list_directory, get_app_preview_url, + get_app_status, list_user_apps), the edit→preview→verify loop, how changes + persist, builder/external-agent concurrency, the in-editor "Send to Coding + Agent" button + onboarding README URLs, and tips like reading the Vite + dev-server logs. Triggers on "develop my Base44 app remotely", "connect + Claude Code to Base44", "bring my own agent", "edit a Base44 app over MCP", + "Base44 sandbox MCP", or "Send to Coding Agent". +--- + + + +# Remotely develop a Base44 app over MCP + +Connect your own coding agent to a Base44 app's sandbox and develop in it +directly — run commands, read and edit files, grep, list directories — while +Base44 supplies the sandbox and you supply the agent and the LLM. + +This works with any MCP-capable client. The examples use Claude Code. + +> **Easiest start:** in the Base44 app editor, click **Send to Coding Agent**. For a local agent +> it gives you a ready-to-paste prompt (which fetches a README and uses the HTTP API in Section 10); +> for the web it gives a prompt to paste into a **claude.ai** chat (with the Base44 MCP connector) +> plus an **Open Claude** button. The button is the discovery surface — the rest of this skill is +> the reference. + +> **Two transports:** web agents use **claude.ai** with the Base44 **MCP connector** (Sections +> 1–9) — note this is the regular claude.ai chat, *not* Claude Code on the web (`claude.ai/code`), +> which runs in its own repo-backed sandbox. A local agent with filesystem access can instead call +> the **HTTP REST surface** with a Base44 CLI token (Section 10) — same tools, same behavior, same +> error codes; only the transport and auth differ. + +--- + +## 1. Connect the MCP server + +The Base44 MCP endpoint is: + +``` +https://app.base44.com/mcp +``` + +Register it with Claude Code (run from any folder): + +```bash +claude mcp add --transport http base44 https://app.base44.com/mcp +``` + +Add `--scope user` if you want it available in every project rather than just +the current folder. + +`claude mcp add` only writes the config — it does not authenticate yet. + +## 2. Authenticate + +Start Claude Code and open the MCP menu: + +```bash +claude +``` + +then, inside Claude Code: + +``` +/mcp +``` + +Select **base44** → **Authenticate**. A browser opens for the Base44 OAuth +flow (PKCE) — log in and approve. When it succeeds, `/mcp` shows **base44** as +connected and lists its tools. + +**Pure-CLI / headless clients** that can't open a browser use the OAuth device +flow (`/oauth/device/code`) instead — request a code, approve it in a browser +on another device, and the client receives the token. + +### Scopes + +| Tools | Required scope | +|---|---| +| `read_file`, `grep`, `list_directory`, `get_app_preview_url`, `get_app_status`, `list_user_apps` | `apps:read` (granted by default) | +| `write_file`, `edit_file`, `run_command` | `sandbox:write` | + +`sandbox:write` is **not** granted by default — shell and file mutation +require it explicitly. If the read tools work but the mutating ones return +`NOT_AUTHORIZED`, your token is missing `sandbox:write`; reconnect and grant +sandbox access (the device flow can request it explicitly). + +--- + +## 3. Pick the app and orient yourself + +Every tool takes a required `appId`. Find your apps with `list_user_apps`, then +pin the id in your requests so the agent passes it on every call. + +Start **read-only** to build a mental model before changing anything: + +``` +Using the base44 tools on appId : +1. list_directory on the app root (recursive, depth 2) +2. read_file src/App.jsx and src/pages.config.js +3. grep for the component I want to change +Summarize the structure before editing. +``` + +> **Cold start:** if the app has no running sandbox, the first tool call +> transparently brings one up from your last commit — it just takes a bit +> longer. Subsequent calls are fast. + +--- + +## 4. Make changes + +- **`edit_file`** — preferred for changing existing files. Provide exact + `old_text`→`new_text` edits. Each `old_text` must be unique in the file + unless you set `replace_all`. All edits in a call apply atomically + (all-or-nothing) and you get a unified diff back. Pass `dry_run: true` to + preview the diff without writing. +- **`write_file`** — for creating new files. To overwrite an existing file you + must pass `overwrite: true` (it never silently clobbers). +- **`run_command`** — run any bash command in the sandbox (build, install, + scaffolding, codemods). The working directory defaults to the app root; `cd` + does not persist across calls, so use the `cwd` parameter or chain commands + (`cd sub && cmd`). Timeout defaults to 120s (max 600s); output is capped at + ~1 MB. + +Example: + +``` +On appId , use edit_file to change the homepage heading in +src/pages/Home.jsx from "Welcome" to "Welcome back". Show me the diff first +with dry_run, then apply it. +``` + +--- + +## 5. Preview and verify (the edit → check loop) + +There is no live log-streaming tool, but you can close the feedback loop: + +- **See it live:** `get_app_preview_url` brings up the dev server and returns + the preview URL. Vite HMR reflects your edits as you make them. +- **Build status:** `get_app_status` returns `ready` / `processing` / `error`. +- **Surface build/type/lint errors on demand** with `run_command`: + ```bash + npm run build # bundler/compile errors + npx tsc --noEmit # type errors + npm run lint # lint errors + ``` +- **Read the dev-server (Vite) logs** — the managed dev server writes to + `/tmp/vite.log`. Tail it via `run_command` to see HMR/compile errors: + ```bash + tail -c 32000 /tmp/vite.log + ``` + (This is outside the app tree, so it's only reachable through `run_command`, + not the file tools — and therefore needs `sandbox:write`.) + +A solid loop: `edit_file` → `npm run build` (or tail `/tmp/vite.log`) → fix any +errors → `get_app_preview_url` to eyeball it. + +> **Browser-runtime errors** (a component that compiles but throws on render, +> a failing client API call) appear in the browser console, not in +> `/tmp/vite.log`. Open the preview URL to catch those. + +--- + +## 6. How your changes persist + +You don't need to "save." Every mutating call schedules a **debounced +auto-commit** (~5 seconds): the change is committed and pushed to Base44's code +storage, so it: + +- survives sandbox death (the sandbox is recreated from the last commit), +- appears in the builder's Library/Data tabs, +- keeps backend-function deploys consistent, and +- is included when you publish the app. + +Practical implications: + +- There's a small loss window (~5s) — don't kill the session immediately after + the last edit; give it a moment to commit. +- Edits to entities, agents, workflows, backend functions, and page routing are + synced into Base44 automatically after the commit. Plain page/component/CSS + edits live in git and need nothing extra. + +--- + +## 7. Concurrency: you vs. the Base44 builder + +You and the in-app Base44 builder can't mutate the same app at once: + +- **While you're actively using the sandbox tools**, the Base44 builder chat is + blocked ("An external agent is currently working on this app"). Your session + is implicit — recent tool calls *are* the session; it ends after a short idle + period (~10 min). +- **If the Base44 builder is mid-build**, your mutating tools return + `BUILDER_BUSY`. Poll `get_app_status` and retry once it's `ready`. Read-only + tools still work during a build. + +--- + +## 8. Guardrails & limits + +- **Paths are confined to the app.** File tools operate only within the app + directory; traversal/absolute paths are rejected (`PATH_OUTSIDE_SANDBOX`). +- **`.agents/` is off-limits to file tools** (`PROTECTED_PATH`) — it holds + agent-managed config and secrets (`.agents/.env`). Don't try to read or edit + it through the file tools. +- **Rate limits** apply per app: reads ~120/min, mutations ~60/min, commands + ~30/min. If you hit `RATE_LIMITED`, slow down. +- **`delete_file` isn't a dedicated tool** — delete via `run_command rm`. + +### Error codes you may see + +`NOT_AUTHORIZED` (missing scope/flag) · `APP_NOT_FOUND` (wrong id or no access) +· `PATH_OUTSIDE_SANDBOX` · `PROTECTED_PATH` · `NOT_FOUND` · `BINARY_FILE` · +`EDIT_TEXT_NOT_FOUND` · `EDIT_TEXT_NOT_UNIQUE` (make `old_text` unique or use +`replace_all`) · `OVERWRITE_NOT_ALLOWED` (pass `overwrite: true`) · `TIMEOUT` · +`OUTPUT_TRUNCATED` · `BUILDER_BUSY` · `RATE_LIMITED` · `BACKEND_ERROR`. + +Messages are written so the agent can self-correct — read them and adjust. + +--- + +## 9. Tips & tricks + +- **Read before you write.** A quick `list_directory` + `read_file` (or `grep`) + pass costs little and dramatically improves edit accuracy. +- **Use `dry_run` on `edit_file`** to confirm the diff before committing to a + change, especially for multi-edit calls. +- **Prefer `edit_file` over `write_file`** for existing files — surgical edits + avoid clobbering and produce a reviewable diff. +- **Read line ranges** with `read_file`'s `offset`/`limit` on large files + instead of pulling the whole thing into context. +- **When something "looks broken," tail `/tmp/vite.log`** before guessing — + it usually names the exact file and line. +- **Let it commit.** Pause a few seconds after your final edit so the auto-commit + lands before you disconnect or publish. +- **One agent at a time.** The feature is designed for a single external agent + per app; don't run parallel sessions against the same app. + +--- + +## 10. Local agents over HTTP (no MCP) + +If your agent runs on your machine (filesystem access), you can skip MCP and call the sandbox +bridge over plain HTTP, authenticating with the Base44 CLI instead of OAuth. + +**Auth.** Log in with the Base44 CLI (`base44 login`) — the same credential used for +`base44 functions deploy` — and send it as a bearer header: `Authorization: Bearer `. + +**Endpoints.** `POST https://app.base44.com/api/apps//sandbox-bridge/`, where +`` is one of `read_file`, `grep`, `list_directory`, `write_file`, `edit_file`, +`run_command`, `release`. The JSON body is the same as the matching MCP tool minus `appId` (it's +in the path). Success returns the tool's structured result; errors return +`{"message", "extra_data": {"code": }}` with the same codes as Section 8. + +```bash +curl -X POST https://app.base44.com/api/apps//sandbox-bridge/read_file \ + -H "Authorization: Bearer $BASE44_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"paths": ["src/App.jsx"]}' +``` + +**Hand an agent the full reference** for a specific app (instructions + endpoints, public, no +auth needed to fetch): + +``` +https://app.base44.com/api/sandbox//local-agent/readme.md +``` + +(The cloud/MCP equivalent is `.../api/sandbox//claude-web/readme.md`.) + +Everything else in this skill — the edit→preview→verify loop (Section 5), persistence +(Section 6), concurrency (Section 7), and guardrails (Section 8) — applies identically; only the +transport and auth differ. diff --git a/skills/base44-sandbox/SKILL.md b/skills/base44-sandbox/SKILL.md new file mode 100644 index 0000000..6153d9b --- /dev/null +++ b/skills/base44-sandbox/SKILL.md @@ -0,0 +1,74 @@ +--- +name: base44-sandbox +description: "Develop a Base44 app remotely inside Base44's cloud sandbox using your own agent — no local checkout and no CLI. The implementation is remote: writing a file into the sandbox is what ships it (the platform builds and deploys from there). This skill is the place for learning what you can author in the sandbox today and how backend-function code is structured. Triggers on 'develop my Base44 app remotely', 'no local files', 'cloud sandbox', 'bring my own agent', or any work editing a Base44 app inside a sandbox." +--- + +# Base44 in the Cloud Sandbox + +Author Base44 app code **inside Base44's cloud sandbox** with your own coding agent. There is no local checkout: you read, write, and run files through the sandbox bridge, and the platform builds and deploys from what you write. + +For **how to connect** to the sandbox (MCP endpoint, the HTTP bridge, the `read_file` / `write_file` / `edit_file` / `run_command` / `grep` / `list_directory` tools, the edit→preview→verify loop, persistence, and concurrency), use the **`base44-remote-dev`** skill. This skill covers **what you can author and how** once you are connected. + +## ⚡ The mental model: writing the file *is* the deploy + +You are working on a **remote** app, not a local checkout. There is **no Base44 CLI in this workflow** — `base44 deploy`, `base44 functions deploy`, `base44 ... push`, `base44 create`, etc. are local-project commands that do not apply and should not be run here. + +Instead: **as soon as you write a backend-function file into the sandbox, the platform deploys it from there.** Your write is auto-committed (~5s debounce) and the function goes live. You do not run, and must not wait for, any deploy command. + +You *may* still use `run_command` for ordinary checks (e.g. `npm run build`, `npx tsc --noEmit`, `npm run lint`) and preview — that is verification, not deployment. See the edit→preview→verify loop in `base44-remote-dev`. + +## What you can author today + +| Resource | Status in the sandbox | +|----------|-----------------------| +| **Backend functions** (`base44/functions/`) | ✅ Supported — write the files; they deploy from the sandbox. | +| **Frontend code** (`src/…`) | ✅ Supported — edit normally; HMR/preview reflects it. Use the **`base44-sdk`** skill for SDK API usage. | +| **Entities** (`base44/entities/`) | 🚫 Not supported at the moment. | +| **Connectors** (`base44/connectors/`) | 🚫 Not supported at the moment. | +| **Agents** (`base44/agents/`) | 🚫 Not supported at the moment. | + +For entities, connectors, and agents, do not author or modify them through the sandbox for now. + +## Backend functions + +Backend functions live in `base44/functions/`, one directory per function (kebab-case name), each with a `function.jsonc` config and an entry file: + +``` +base44/functions/ + process-order/ + function.jsonc + index.ts +``` + +`function.jsonc`: +```jsonc +{ "name": "process-order", "entry": "index.ts" } +``` +- `name` — required, must match `/^[^.]+$/` (no dots). Match the directory name. +- `entry` — required, the entry file relative to the function directory (e.g. `index.ts`). + +Entry file — functions run on **Deno** (not Node.js), export with `Deno.serve()`, and use the `npm:` prefix for npm packages: +```typescript +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 }); +}); +``` +Conventions: +- **Kebab-case** directory and function name; entry typically `index.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. + +That's enough to author functions correctly. For deeper detail and more examples (service role, secrets, common mistakes), see the `base44-cli` skill's reference: [`functions-create.md`](../base44-cli/references/functions-create.md) — but **ignore its "Deploying Functions" / CLI sections**, which assume a local project and do not apply in the sandbox. + +## Workflow in the sandbox + +1. **Orient** — `list_directory` / `read_file` / `grep` to understand the app before changing anything. +2. **Author** — create or edit backend-function files (and frontend code) following the conventions above. +3. **Verify** — optionally `run_command` `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. From fd6aa91e8589b1cd3e69ef5c109a2468968f1076 Mon Sep 17 00:00:00 2001 From: carmelc Date: Wed, 17 Jun 2026 17:01:48 +0300 Subject: [PATCH 02/15] feat(base44-sandbox): support connectors via MCP tools and projectless CLI Connectors are now usable in remote-dev (apper#11608 MCP connector tools + cli#547 projectless connectors), so flip them from "not supported" to a documented connect flow: - list_connectors (apps:read) / initiate_connector_connection (apps:write) over MCP, and base44 connectors list-available/initiate/pull over the CLI with --app-id (no local project / config.jsonc). - Document the declarative/replace scope semantics (read current scopes first, pass the complete set) and the human-consent authorization-URL step. - Note the connector CLI is the one allowed CLI use in remote-dev; it targets a remote app by id with no deploy step (not a contradiction of the no-CLI rule, which is about local-project/deploy commands). Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/base44-sandbox/SKILL.md | 56 +++++++++++++++++++++++++++++++--- 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/skills/base44-sandbox/SKILL.md b/skills/base44-sandbox/SKILL.md index 6153d9b..50751f9 100644 --- a/skills/base44-sandbox/SKILL.md +++ b/skills/base44-sandbox/SKILL.md @@ -1,6 +1,6 @@ --- name: base44-sandbox -description: "Develop a Base44 app remotely inside Base44's cloud sandbox using your own agent — no local checkout and no CLI. The implementation is remote: writing a file into the sandbox is what ships it (the platform builds and deploys from there). This skill is the place for learning what you can author in the sandbox today and how backend-function code is structured. Triggers on 'develop my Base44 app remotely', 'no local files', 'cloud sandbox', 'bring my own agent', or any work editing a Base44 app inside a sandbox." +description: "Develop a Base44 app remotely inside Base44's cloud sandbox using your own agent — no local checkout. The implementation is remote: writing a backend-function file into the sandbox is what ships it (the platform builds and deploys from there), and OAuth connectors are set up against the remote app via MCP tools or the projectless `base44 connectors` CLI. This skill is the place for learning what you can author in the sandbox today, how backend-function code is structured, and how to connect a connector without a local filesystem. Triggers on 'develop my Base44 app remotely', 'no local files', 'cloud sandbox', 'connect a connector remotely', 'bring my own agent', or any work editing a Base44 app inside a sandbox." --- # Base44 in the Cloud Sandbox @@ -11,10 +11,12 @@ For **how to connect** to the sandbox (MCP endpoint, the HTTP bridge, the `read_ ## ⚡ The mental model: writing the file *is* the deploy -You are working on a **remote** app, not a local checkout. There is **no Base44 CLI in this workflow** — `base44 deploy`, `base44 functions deploy`, `base44 ... push`, `base44 create`, etc. are local-project commands that do not apply and should not be run here. +You are working on a **remote** app, not a local checkout. The project-level CLI workflow does **not** apply — never run `base44 deploy`, `base44 functions deploy`, `base44 ... push`, `base44 create`, or `base44 scaffold`. They assume a local project and a manual deploy step that does not exist here. Instead: **as soon as you write a backend-function file into the sandbox, the platform deploys it from there.** Your write is auto-committed (~5s debounce) and the function goes live. You do not run, and must not wait for, any deploy command. +**One exception — connectors.** OAuth connectors aren't authored as files; they're set up against the remote app by its id, either with the MCP connector tools or with the dedicated, projectless `base44 connectors` commands (which take `--app-id` and need no local project). See [Connectors](#connectors-oauth-integrations) below. + You *may* still use `run_command` for ordinary checks (e.g. `npm run build`, `npx tsc --noEmit`, `npm run lint`) and preview — that is verification, not deployment. See the edit→preview→verify loop in `base44-remote-dev`. ## What you can author today @@ -23,11 +25,11 @@ You *may* still use `run_command` for ordinary checks (e.g. `npm run build`, `np |----------|-----------------------| | **Backend functions** (`base44/functions/`) | ✅ Supported — write the files; they deploy from the sandbox. | | **Frontend code** (`src/…`) | ✅ Supported — edit normally; HMR/preview reflects it. Use the **`base44-sdk`** skill for SDK API usage. | +| **Connectors** (OAuth integrations) | ✅ Supported — set up via the connect flow below (MCP tools or `base44 connectors`), **not** by writing files. | | **Entities** (`base44/entities/`) | 🚫 Not supported at the moment. | -| **Connectors** (`base44/connectors/`) | 🚫 Not supported at the moment. | | **Agents** (`base44/agents/`) | 🚫 Not supported at the moment. | -For entities, connectors, and agents, do not author or modify them through the sandbox for now. +For entities and agents, do not author or modify them through the sandbox for now. ## Backend functions @@ -66,9 +68,53 @@ Conventions: That's enough to author functions correctly. For deeper detail and more examples (service role, secrets, common mistakes), see the `base44-cli` skill's reference: [`functions-create.md`](../base44-cli/references/functions-create.md) — but **ignore its "Deploying Functions" / CLI sections**, which assume a local project and do not apply in the sandbox. +## Connectors (OAuth integrations) + +Connectors (Google Calendar, Gmail, Slack, …) give your backend functions tokens to call third-party APIs. In remote-dev there are **no connector files to write** — you operate on the connector directly against the app by its id. Two surfaces, same backend and same behavior: + +> **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) + +Two tools, both taking `appId`. Scopes: `list_connectors` needs `apps:read`; `initiate_connector_connection` needs `apps:write` (note: **not** `sandbox:write`). + +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 : 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`) + +These `base44 connectors` subcommands work **without a local project** — they resolve the app id from `--app-id`, then `BASE44_APP_ID`, then a local `.app.jsonc`. No `config.jsonc` is required. + +```bash +# 1. See available integration types for the app +npx base44 connectors list-available --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 \ + --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 --dir ./connectors +``` + +`--scopes` accepts a space- or comma-separated list. As with MCP, the user must open the printed authorization URL to finish consent; afterwards `list-available` / `pull` reflects the connected state and granted scopes. + +> 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. + ## Workflow in the sandbox 1. **Orient** — `list_directory` / `read_file` / `grep` to understand the app before changing anything. -2. **Author** — create or edit backend-function files (and frontend code) following the conventions above. +2. **Author** — create or edit backend-function files (and frontend code) following the conventions above; set up connectors via the connect flow. 3. **Verify** — optionally `run_command` `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. From f6f179a7c892f280ebcee560bd9f51de0c81859d Mon Sep 17 00:00:00 2001 From: carmelc Date: Wed, 17 Jun 2026 17:23:05 +0300 Subject: [PATCH 03/15] docs(base44-remote-dev): document the connector MCP tools MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Upstream's base44-remote-dev SKILL.md doesn't yet list the connector tools shipped in apper#11608, so add a "Connectors (OAuth integrations)" section covering list_connectors (apps:read) and initiate_connector_connection (apps:write) — declarative/replace scope semantics and the human-consent redirect-URL step — plus the projectless base44 connectors CLI equivalent. Marked as a local addition (HTML comment) to reconcile when upstream documents these tools. Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/base44-remote-dev/SKILL.md | 38 ++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/skills/base44-remote-dev/SKILL.md b/skills/base44-remote-dev/SKILL.md index 007d026..a81b920 100644 --- a/skills/base44-remote-dev/SKILL.md +++ b/skills/base44-remote-dev/SKILL.md @@ -7,7 +7,8 @@ description: >- REST surface with a Base44 CLI token (Section 10). Covers connecting/ authenticating, the available sandbox tools (run_command, read_file, write_file, edit_file, grep, list_directory, get_app_preview_url, - get_app_status, list_user_apps), the edit→preview→verify loop, how changes + get_app_status, list_user_apps, and the connector tools list_connectors / + initiate_connector_connection), the edit→preview→verify loop, how changes persist, builder/external-agent concurrency, the in-editor "Send to Coding Agent" button + onboarding README URLs, and tips like reading the Vite dev-server logs. Triggers on "develop my Base44 app remotely", "connect @@ -284,3 +285,38 @@ https://app.base44.com/api/sandbox//local-agent/readme.md Everything else in this skill — the edit→preview→verify loop (Section 5), persistence (Section 6), concurrency (Section 7), and guardrails (Section 8) — applies identically; only the transport and auth differ. + +--- + +## 11. Connectors (OAuth integrations) + + + +Beyond the sandbox file/shell tools, the Base44 MCP server exposes two tools for managing a +third-party OAuth connector (Google Calendar, Gmail, Slack, …) on an app. They don't touch the +sandbox filesystem — they operate on the app's connector state directly. Both take `appId`. + +| Tool | Scope | Purpose | +|---|---|---| +| `list_connectors` | `apps:read` | List the app's connectors. With no `integrationTypes`, returns the full catalog (name, description, connected?, and — if connected — status and granted scopes). Pass `integrationTypes` for detail on specific ones. | +| `initiate_connector_connection` | `apps:write` | Connect (or re-scope) a connector. Inputs: `appId`, `integrationType`, `scopes`, optional `connectionConfig`. | + +Two semantics to get right: + +- **Declarative scopes (replace, not merge).** `initiate_connector_connection` sets the connector + to **exactly** the `scopes` you pass. Omitted scopes are removed and the user is re-prompted to + consent. **Always call `list_connectors` first**, then pass the complete desired set (existing + scopes you want to keep **plus** any new ones). +- **OAuth needs a human.** The tool returns either `already_authorized: true` (nothing to do) or a + `redirect_url` the **user** must open in a browser to sign in and consent — you can't complete it + yourself. After they finish, call `list_connectors` again to verify and read the **granted** + scopes (a provider may grant fewer than requested). + +These need only `apps:read` / `apps:write` — **not** `sandbox:write`. Over the HTTP/CLI surface +(Section 10), the equivalent is the projectless `base44 connectors` commands +(`list-available`, `initiate --integration-type --scopes --app-id `, `pull`), which +print the same authorization URL. From 90ceb7e29d71c1075c14cb53f58aa6a2ff83dae8 Mon Sep 17 00:00:00 2001 From: carmelc Date: Wed, 17 Jun 2026 17:24:10 +0300 Subject: [PATCH 04/15] docs(base44-remote-dev): drop local-addition note from connectors section The connectors section will align with upstream by merge time. Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/base44-remote-dev/SKILL.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/skills/base44-remote-dev/SKILL.md b/skills/base44-remote-dev/SKILL.md index a81b920..dfb13db 100644 --- a/skills/base44-remote-dev/SKILL.md +++ b/skills/base44-remote-dev/SKILL.md @@ -290,12 +290,6 @@ transport and auth differ. ## 11. Connectors (OAuth integrations) - - Beyond the sandbox file/shell tools, the Base44 MCP server exposes two tools for managing a third-party OAuth connector (Google Calendar, Gmail, Slack, …) on an app. They don't touch the sandbox filesystem — they operate on the app's connector state directly. Both take `appId`. From a9abbf24d58e24f1652add576c27cf6cd44981b0 Mon Sep 17 00:00:00 2001 From: carmelc Date: Thu, 18 Jun 2026 09:08:52 +0300 Subject: [PATCH 05/15] fix(docs): use entry.ts as the backend-function entry file The function entry file (and the function.jsonc "entry" value) is entry.ts, not index.ts. Update all function examples across base44-sandbox, base44-sdk, and base44-cli docs (functions-create, automations, project-structure trees). Invocation already uses base44.functions.invoke('name', data) everywhere; no change needed there. Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/base44-sandbox/SKILL.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/skills/base44-sandbox/SKILL.md b/skills/base44-sandbox/SKILL.md index 50751f9..4f38eb5 100644 --- a/skills/base44-sandbox/SKILL.md +++ b/skills/base44-sandbox/SKILL.md @@ -39,15 +39,15 @@ Backend functions live in `base44/functions/`, one directory per function (kebab base44/functions/ process-order/ function.jsonc - index.ts + entry.ts ``` `function.jsonc`: ```jsonc -{ "name": "process-order", "entry": "index.ts" } +{ "name": "process-order", "entry": "entry.ts" } ``` - `name` — required, must match `/^[^.]+$/` (no dots). Match the directory name. -- `entry` — required, the entry file relative to the function directory (e.g. `index.ts`). +- `entry` — required, the entry file relative to the function directory (e.g. `entry.ts`). Entry file — functions run on **Deno** (not Node.js), export with `Deno.serve()`, and use the `npm:` prefix for npm packages: ```typescript @@ -61,7 +61,7 @@ Deno.serve(async (req) => { }); ``` Conventions: -- **Kebab-case** directory and function name; entry typically `index.ts`. +- **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. From aa64aaf60744041746d14834a06fc92c33ee9b21 Mon Sep 17 00:00:00 2001 From: carmelc Date: Thu, 18 Jun 2026 10:26:05 +0300 Subject: [PATCH 06/15] docs(base44-sandbox): connector token usage, complete README, reference-first - Add "Using a connected connector in code": fetch the OAuth token via base44.asServiceRole.connectors.getConnection(type) inside a backend function, with a link to base44-sdk's connectors reference. - Add a "Reference order & the complete README" section: prefer this skill and its siblings over web search, and point to the public app-specific onboarding README endpoint. - Surface the reference-first note near the top too. Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/base44-sandbox/SKILL.md | 39 ++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/skills/base44-sandbox/SKILL.md b/skills/base44-sandbox/SKILL.md index 4f38eb5..bc5cfec 100644 --- a/skills/base44-sandbox/SKILL.md +++ b/skills/base44-sandbox/SKILL.md @@ -9,6 +9,8 @@ Author Base44 app code **inside Base44's cloud sandbox** with your own coding ag For **how to connect** to the sandbox (MCP endpoint, the HTTP bridge, the `read_file` / `write_file` / `edit_file` / `run_command` / `grep` / `list_directory` tools, the edit→preview→verify loop, persistence, and concurrency), use the **`base44-remote-dev`** skill. This skill covers **what you can author and how** once you are connected. +> **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](#reference-order--the-complete-readme). + ## ⚡ The mental model: writing the file *is* the deploy You are working on a **remote** app, not a local checkout. The project-level CLI workflow does **not** apply — never run `base44 deploy`, `base44 functions deploy`, `base44 ... push`, `base44 create`, or `base44 scaffold`. They assume a local project and a manual deploy step that does not exist here. @@ -112,6 +114,43 @@ npx base44 connectors pull --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 + +Connecting only authorizes the connector. To actually call the third-party API, fetch its OAuth access token **inside a backend function** with the service-role connectors module — `base44.asServiceRole.connectors.getConnection(integrationType)` — and use the returned `accessToken` (and optional `connectionConfig`) in your own `fetch`: + +```typescript +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 }); +}); +``` + +Notes: the connector is **app-scoped** (one connected account shared by all users); Base44 refreshes the token for you; you make the API calls. `getConnection()` replaces the deprecated `getAccessToken()`. For the full module reference (signatures, `connectionConfig`, the list of available services and their type identifiers), see the `base44-sdk` skill's [`connectors.md`](../base44-sdk/references/connectors.md). + +## Reference order & the complete README + +**Consult the references in this skill and its sibling skills (`base44-remote-dev`, `base44-sdk`) before searching the web.** They are the source of truth for the sandbox bridge, file/resource conventions, and SDK APIs — prefer them over general internet results, which are often stale or wrong for Base44. + +For the complete, app-specific remote-dev reference (instructions + every endpoint, public, no auth needed to fetch), read the onboarding README for your app: + +``` +https://app.base44.com/api/sandbox//local-agent/readme.md +``` + +(The cloud/MCP equivalent is `…/api/sandbox//claude-web/readme.md`.) See the `base44-remote-dev` skill for the connection mechanics this README describes. + ## Workflow in the sandbox 1. **Orient** — `list_directory` / `read_file` / `grep` to understand the app before changing anything. From f279f12e744cc7817e2c1a12cd2a564bdf5aa0b3 Mon Sep 17 00:00:00 2001 From: carmelc Date: Thu, 18 Jun 2026 14:42:11 +0300 Subject: [PATCH 07/15] docs(base44-sdk): clarify functions.invoke() returns the raw axios response invoke() resolves to the raw axios response, so the function's JSON is on .data (not the top-level object), and it throws on non-2xx with the error body at err.response.data. Update the invoke method doc and every frontend example to read res.data, and add the warning in SKILL.md + QUICK_REFERENCE. Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/base44-sdk/SKILL.md | 5 +++- .../base44-sdk/references/QUICK_REFERENCE.md | 2 +- skills/base44-sdk/references/functions.md | 28 +++++++++++++++---- 3 files changed, 28 insertions(+), 7 deletions(-) diff --git a/skills/base44-sdk/SKILL.md b/skills/base44-sdk/SKILL.md index c4cfbac..a249695 100644 --- a/skills/base44-sdk/SKILL.md +++ b/skills/base44-sdk/SKILL.md @@ -255,10 +255,13 @@ if (!user) { ```javascript // Frontend -const result = await base44.functions.invoke("processOrder", { +// ⚠️ invoke() returns the RAW axios response — your function's JSON is on `.data`, +// NOT the top-level object. It also THROWS on non-2xx (error body at err.response.data). +const res = await base44.functions.invoke("processOrder", { orderId: "123", action: "ship" }); +const result = res.data; // ✅ e.g. res.data.success (res itself is { data, status, headers, … }) // Backend function (Deno) import { createClientFromRequest } from "npm:@base44/sdk"; diff --git a/skills/base44-sdk/references/QUICK_REFERENCE.md b/skills/base44-sdk/references/QUICK_REFERENCE.md index 0d2271a..cbac096 100644 --- a/skills/base44-sdk/references/QUICK_REFERENCE.md +++ b/skills/base44-sdk/references/QUICK_REFERENCE.md @@ -50,7 +50,7 @@ subscribe(callback) → () => void // returns unsu ## Functions (`base44.functions.*`) ``` -invoke(functionName, data?) → Promise +invoke(functionName, data?) → Promise // your JSON is on .data; throws on non-2xx (err.response.data) fetch(path, init?) → Promise // low-level, for streaming/custom methods ``` diff --git a/skills/base44-sdk/references/functions.md b/skills/base44-sdk/references/functions.md index 4432a45..f34af80 100644 --- a/skills/base44-sdk/references/functions.md +++ b/skills/base44-sdk/references/functions.md @@ -14,12 +14,26 @@ Invoke custom backend functions via `base44.functions`. ### `invoke` ```javascript -base44.functions.invoke(functionName, data?): Promise +base44.functions.invoke(functionName, data?): Promise ``` - `functionName`: Name of the backend function - `data`: Optional object of parameters (sent as JSON, or multipart if contains File objects) -- Returns: Whatever the function returns +- **Returns the RAW axios response** — the JSON your function returned lives on **`.data`**, not on the top-level object. The resolved value is `{ data, status, headers, … }`. +- **Throws on a non-2xx response.** The error body is at `err.response.data`. + +```javascript +try { + // ⚠️ invoke() returns the RAW axios response, so the JSON your function + // returned lives on `.data` — NOT on the top-level object. + const res = await base44.functions.invoke("process-order", { orderId }); + const result = res.data; // ✅ e.g. res.data.success + // const result = res; // ❌ this is { data, status, headers, … } +} catch (err) { + // invoke() THROWS on a non-2xx response; the error body is at err.response.data. + console.error(err.response?.data); +} +``` ### `fetch` @@ -38,11 +52,13 @@ Low-level method that performs a direct HTTP request to a backend function path ### From Frontend ```javascript -const result = await base44.functions.invoke("processOrder", { +const res = await base44.functions.invoke("processOrder", { orderId: "order-123", action: "ship" }); +// invoke() resolves to the raw axios response — read your function's JSON off .data +const result = res.data; console.log(result); ``` @@ -83,19 +99,21 @@ const fileInput = document.querySelector('input[type="file"]'); const file = fileInput.files[0]; // Automatically uses multipart/form-data when File objects present -const result = await base44.functions.invoke("uploadDocument", { +const res = await base44.functions.invoke("uploadDocument", { file: file, category: "invoices" }); +const result = res.data; // function's JSON is on .data ``` ### With Service Role (Backend) ```javascript // Inside another backend function -const result = await base44.asServiceRole.functions.invoke("adminTask", { +const res = await base44.asServiceRole.functions.invoke("adminTask", { userId: "user-123" }); +const result = res.data; // function's JSON is on .data ``` ### Via REST API (curl) From e979071b71daa8c1ed017edc6ccd4c7a3d0ab822 Mon Sep 17 00:00:00 2001 From: carmelc Date: Thu, 18 Jun 2026 14:50:22 +0300 Subject: [PATCH 08/15] docs(base44-sandbox): note invoke() returns raw axios response (.data) Add a small frontend-calling clarification so agents read the function's JSON off res.data and handle the non-2xx throw; link to base44-sdk for detail. Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/base44-sandbox/SKILL.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/skills/base44-sandbox/SKILL.md b/skills/base44-sandbox/SKILL.md index bc5cfec..ea0b396 100644 --- a/skills/base44-sandbox/SKILL.md +++ b/skills/base44-sandbox/SKILL.md @@ -70,6 +70,8 @@ Conventions: That's enough to author functions correctly. For deeper detail and more examples (service role, secrets, common mistakes), see the `base44-cli` skill's reference: [`functions-create.md`](../base44-cli/references/functions-create.md) — but **ignore its "Deploying Functions" / CLI sections**, which assume a local project and do not apply in the sandbox. +> **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`](../base44-sdk/references/functions.md) for details. + ## Connectors (OAuth integrations) Connectors (Google Calendar, Gmail, Slack, …) give your backend functions tokens to call third-party APIs. In remote-dev there are **no connector files to write** — you operate on the connector directly against the app by its id. Two surfaces, same backend and same behavior: From feeee724ffcd04d6b890b7e97d1b924b5c1ddf97 Mon Sep 17 00:00:00 2001 From: carmelc Date: Sun, 21 Jun 2026 11:14:52 +0300 Subject: [PATCH 09/15] feat(base44-sandbox): support entities and agents (filesystem-only) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Entities and agents are now authorable in the sandbox — writing the .jsonc file auto-syncs, no entities/agents push or deploy. Flip both from "not supported" to supported, broaden the mental model to "writing a resource file is the deploy", and add Entities and Agents authoring sections (file naming, schema, links to base44-cli references with their push/deploy sections flagged as not applicable). Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 2 +- skills/base44-sandbox/SKILL.md | 60 ++++++++++++++++++++++++++++++---- 2 files changed, 54 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 47e8e45..32e8d51 100644 --- a/README.md +++ b/README.md @@ -68,7 +68,7 @@ npx skills add base44/skills --skill base44-remote-dev --skill base44-sandbox -- | [`base44-sdk`](skills/base44-sdk/SKILL.md) | Build apps using the Base44 JavaScript SDK. Communicate with remote resources like entities, backend functions, and AI agents. | | [`base44-troubleshooter`](skills/base44-troubleshooter/SKILL.md) | Troubleshoot production issues using backend function logs. Use when investigating app errors or diagnosing production problems. | | [`base44-remote-dev`](skills/base44-remote-dev/SKILL.md) | Develop a Base44 app remotely from your own coding agent by connecting it to the Base44 sandbox over MCP or the HTTP bridge. | -| [`base44-sandbox`](skills/base44-sandbox/SKILL.md) | Author Base44 app code inside the cloud sandbox — no CLI; writing a backend-function file into the sandbox is what ships it. | +| [`base44-sandbox`](skills/base44-sandbox/SKILL.md) | Author Base44 app code inside the cloud sandbox — no deploy/push; writing a resource file (function, entity, agent) into the sandbox is what ships it. | ## About Agent Skills diff --git a/skills/base44-sandbox/SKILL.md b/skills/base44-sandbox/SKILL.md index ea0b396..3199b94 100644 --- a/skills/base44-sandbox/SKILL.md +++ b/skills/base44-sandbox/SKILL.md @@ -1,6 +1,6 @@ --- name: base44-sandbox -description: "Develop a Base44 app remotely inside Base44's cloud sandbox using your own agent — no local checkout. The implementation is remote: writing a backend-function file into the sandbox is what ships it (the platform builds and deploys from there), and OAuth connectors are set up against the remote app via MCP tools or the projectless `base44 connectors` CLI. This skill is the place for learning what you can author in the sandbox today, how backend-function code is structured, and how to connect a connector without a local filesystem. Triggers on 'develop my Base44 app remotely', 'no local files', 'cloud sandbox', 'connect a connector remotely', 'bring my own agent', or any work editing a Base44 app inside a sandbox." +description: "Develop a Base44 app remotely inside Base44's cloud sandbox using your own agent — no local checkout and no deploy/push commands. The implementation is remote: writing a resource file into the sandbox is what ships it (backend functions, entities, and agents all auto-sync from the file you write), and OAuth connectors are set up against the remote app via MCP tools or the projectless `base44 connectors` CLI. This skill is the place for learning what you can author in the sandbox, how backend functions, entities, and agents are structured, and how to connect a connector without a local filesystem. Triggers on 'develop my Base44 app remotely', 'no local files', 'cloud sandbox', 'create an entity/agent remotely', 'connect a connector remotely', 'bring my own agent', or any work editing a Base44 app inside a sandbox." --- # Base44 in the Cloud Sandbox @@ -15,7 +15,7 @@ For **how to connect** to the sandbox (MCP endpoint, the HTTP bridge, the `read_ You are working on a **remote** app, not a local checkout. The project-level CLI workflow does **not** apply — never run `base44 deploy`, `base44 functions deploy`, `base44 ... push`, `base44 create`, or `base44 scaffold`. They assume a local project and a manual deploy step that does not exist here. -Instead: **as soon as you write a backend-function file into the sandbox, the platform deploys it from there.** Your write is auto-committed (~5s debounce) and the function goes live. You do not run, and must not wait for, any deploy command. +Instead: **as soon as you write a resource file into the sandbox — a backend function, an entity, or an agent — the platform deploys/syncs it from there.** Your write is auto-committed (~5s debounce) and goes live. You do not run, and must not wait for, any `deploy` / `push` command. **One exception — connectors.** OAuth connectors aren't authored as files; they're set up against the remote app by its id, either with the MCP connector tools or with the dedicated, projectless `base44 connectors` commands (which take `--app-id` and need no local project). See [Connectors](#connectors-oauth-integrations) below. @@ -26,12 +26,10 @@ You *may* still use `run_command` for ordinary checks (e.g. `npm run build`, `np | Resource | Status in the sandbox | |----------|-----------------------| | **Backend functions** (`base44/functions/`) | ✅ Supported — write the files; they deploy from the sandbox. | +| **Entities** (`base44/entities/`) | ✅ Supported — write the `.jsonc` schema file; it auto-syncs. No `entities push`. | +| **Agents** (`base44/agents/`) | ✅ Supported — write the `.jsonc` config file; it auto-syncs. No `agents push`. | | **Frontend code** (`src/…`) | ✅ Supported — edit normally; HMR/preview reflects it. Use the **`base44-sdk`** skill for SDK API usage. | | **Connectors** (OAuth integrations) | ✅ Supported — set up via the connect flow below (MCP tools or `base44 connectors`), **not** by writing files. | -| **Entities** (`base44/entities/`) | 🚫 Not supported at the moment. | -| **Agents** (`base44/agents/`) | 🚫 Not supported at the moment. | - -For entities and agents, do not author or modify them through the sandbox for now. ## Backend functions @@ -72,6 +70,54 @@ That's enough to author functions correctly. For deeper detail and more examples > **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`](../base44-sdk/references/functions.md) for details. +## Entities + +One `.jsonc` file per entity in `base44/entities/`. Just write the file — it auto-syncs; **don't run `base44 entities push` or `deploy`.** + +- **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`. + +```jsonc +// 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"] +} +``` + +Field types: `string`, `number`, `integer`, `boolean`, `array`, `object`, `binary`. String formats include `date`, `date-time`, `email`, `uri`, `uuid`, `file`, `richtext`. For full schema detail and row-level security (RLS), see the `base44-cli` references [`entities-create.md`](../base44-cli/references/entities-create.md) and [`rls-examples.md`](../base44-cli/references/rls-examples.md) — but **ignore their `entities push` / deploy sections**; the sandbox syncs the file for you. + +## Agents + +One `.jsonc` file per agent in `base44/agents/`. Just write the file — it auto-syncs; **don't run `base44 agents push` or `deploy`.** + +- **File name:** `{agent_name}.jsonc` — e.g. `support_agent.jsonc`. +- **Agent `name`:** `/^[a-z0-9_]+$/` (lowercase, underscores, 1–100 chars). + +```jsonc +// 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?" +} +``` + +Required: `name`, `description`, `instructions`. Optional: `tool_configs` (default `[]`), `whatsapp_greeting`. Tool configs are either an **entity tool** (`entity_name` + `allowed_operations`: any of `read`/`create`/`update`/`delete`) or a **backend-function tool** (`function_name` + `description`). See the `base44-cli` skill's Agent Schema for full detail. + ## Connectors (OAuth integrations) Connectors (Google Calendar, Gmail, Slack, …) give your backend functions tokens to call third-party APIs. In remote-dev there are **no connector files to write** — you operate on the connector directly against the app by its id. Two surfaces, same backend and same behavior: @@ -156,6 +202,6 @@ https://app.base44.com/api/sandbox//local-agent/readme.md ## Workflow in the sandbox 1. **Orient** — `list_directory` / `read_file` / `grep` to understand the app before changing anything. -2. **Author** — create or edit backend-function files (and frontend code) following the conventions above; set up connectors via the connect flow. +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` `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. From 48f6c3fb75b82e59e130cc0467de02dbce16137b Mon Sep 17 00:00:00 2001 From: carmelc Date: Sun, 21 Jun 2026 11:24:53 +0300 Subject: [PATCH 10/15] docs(base44-sandbox): add base44-cli reference to the Agents section Match the functions/entities pattern: link the Agents section to the base44-cli Agent Schema and make clear to ignore agents push/pull/deploy commands (sandbox auto-syncs the file). Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/base44-sandbox/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/base44-sandbox/SKILL.md b/skills/base44-sandbox/SKILL.md index 3199b94..3c9d68c 100644 --- a/skills/base44-sandbox/SKILL.md +++ b/skills/base44-sandbox/SKILL.md @@ -116,7 +116,7 @@ One `.jsonc` file per agent in `base44/agents/`. Just write the file — it auto } ``` -Required: `name`, `description`, `instructions`. Optional: `tool_configs` (default `[]`), `whatsapp_greeting`. Tool configs are either an **entity tool** (`entity_name` + `allowed_operations`: any of `read`/`create`/`update`/`delete`) or a **backend-function tool** (`function_name` + `description`). See the `base44-cli` skill's Agent Schema for full detail. +Required: `name`, `description`, `instructions`. Optional: `tool_configs` (default `[]`), `whatsapp_greeting`. Tool configs are either an **entity tool** (`entity_name` + `allowed_operations`: any of `read`/`create`/`update`/`delete`) or a **backend-function tool** (`function_name` + `description`). For the full agent schema, see the **Agent Schema** section of the `base44-cli` skill's [`SKILL.md`](../base44-cli/SKILL.md) — but **ignore its `agents push` / `agents pull` / deploy commands**, which assume a local project; in the sandbox the file auto-syncs. ## Connectors (OAuth integrations) From 4c15c152fd2c771a26a649e63eb2ce3dcb8aa1d5 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 23 Jun 2026 12:25:14 +0000 Subject: [PATCH 11/15] docs(sandbox): drop HTTP bridge surface, document base44 sandbox CLI names Remove the HTTP REST sandbox-bridge option (POST /api/apps//sandbox-bridge/) from base44-remote-dev and base44-sandbox; local agents use MCP or the `base44 sandbox` CLI instead. Clarify CLI naming throughout: add the MCP-tool -> CLI-command mapping (list_directory->sandbox ls, read_file->sandbox read, write_file->sandbox write, edit_file->sandbox edit, run_command->sandbox run; grep/release unchanged) and annotate inline tool references with their CLI command names. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01842h6eP9hLWHnoRrERmbLo --- README.md | 2 +- skills/base44-remote-dev/SKILL.md | 64 +++++++++++++++++++------------ skills/base44-sandbox/SKILL.md | 10 ++--- 3 files changed, 45 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 32e8d51..00c218a 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ npx skills add base44/skills --skill base44-remote-dev --skill base44-sandbox -- | [`base44-cli`](skills/base44-cli/SKILL.md) | Create and manage Base44 projects using the CLI. Handles resource configuration (entities, backend functions, AI agents), initialization, and deployment. | | [`base44-sdk`](skills/base44-sdk/SKILL.md) | Build apps using the Base44 JavaScript SDK. Communicate with remote resources like entities, backend functions, and AI agents. | | [`base44-troubleshooter`](skills/base44-troubleshooter/SKILL.md) | Troubleshoot production issues using backend function logs. Use when investigating app errors or diagnosing production problems. | -| [`base44-remote-dev`](skills/base44-remote-dev/SKILL.md) | Develop a Base44 app remotely from your own coding agent by connecting it to the Base44 sandbox over MCP or the HTTP bridge. | +| [`base44-remote-dev`](skills/base44-remote-dev/SKILL.md) | Develop a Base44 app remotely from your own coding agent by connecting it to the Base44 sandbox over MCP or the `base44 sandbox` CLI. | | [`base44-sandbox`](skills/base44-sandbox/SKILL.md) | Author Base44 app code inside the cloud sandbox — no deploy/push; writing a resource file (function, entity, agent) into the sandbox is what ships it. | ## About Agent Skills diff --git a/skills/base44-remote-dev/SKILL.md b/skills/base44-remote-dev/SKILL.md index dfb13db..26a8ed1 100644 --- a/skills/base44-remote-dev/SKILL.md +++ b/skills/base44-remote-dev/SKILL.md @@ -3,8 +3,10 @@ name: base44-remote-dev description: >- Develop a Base44 app remotely from your own coding agent (Claude Code, claude.ai, or any MCP client) by connecting it to the Base44 sandbox. Cloud - agents connect over MCP; local/filesystem agents can instead use the HTTP - REST surface with a Base44 CLI token (Section 10). Covers connecting/ + agents connect over MCP; local agents can connect over MCP or drive the same + sandbox with the `base44 sandbox` CLI subcommands (the CLI uses shorter + names — e.g. read_file is `sandbox read`, list_directory is `sandbox ls`, + run_command is `sandbox run`). Covers connecting/ authenticating, the available sandbox tools (run_command, read_file, write_file, edit_file, grep, list_directory, get_app_preview_url, get_app_status, list_user_apps, and the connector tools list_connectors / @@ -31,16 +33,18 @@ Base44 supplies the sandbox and you supply the agent and the LLM. This works with any MCP-capable client. The examples use Claude Code. > **Easiest start:** in the Base44 app editor, click **Send to Coding Agent**. For a local agent -> it gives you a ready-to-paste prompt (which fetches a README and uses the HTTP API in Section 10); +> it gives you a ready-to-paste prompt (which fetches a README and drives the sandbox over MCP or +> the `base44 sandbox` CLI — Section 10); > for the web it gives a prompt to paste into a **claude.ai** chat (with the Base44 MCP connector) > plus an **Open Claude** button. The button is the discovery surface — the rest of this skill is > the reference. > **Two transports:** web agents use **claude.ai** with the Base44 **MCP connector** (Sections > 1–9) — note this is the regular claude.ai chat, *not* Claude Code on the web (`claude.ai/code`), -> which runs in its own repo-backed sandbox. A local agent with filesystem access can instead call -> the **HTTP REST surface** with a Base44 CLI token (Section 10) — same tools, same behavior, same -> error codes; only the transport and auth differ. +> which runs in its own repo-backed sandbox. A local agent can connect that same MCP server, or +> drive the sandbox with the **`base44 sandbox` CLI** (a Base44 CLI token, Section 10) — same tools, +> same behavior, same error codes; the CLI just exposes them under shorter command names +> (`sandbox read`, `sandbox ls`, …). --- @@ -118,18 +122,22 @@ Summarize the structure before editing. > transparently brings one up from your last commit — it just takes a bit > longer. Subsequent calls are fast. +> **CLI names:** over the `base44 sandbox` CLI (Section 10) these read tools are +> `list_directory` → `sandbox ls`, `read_file` → `sandbox read`, and +> `grep` → `sandbox grep`. + --- ## 4. Make changes -- **`edit_file`** — preferred for changing existing files. Provide exact +- **`edit_file`** (`sandbox edit` in the CLI) — preferred for changing existing files. Provide exact `old_text`→`new_text` edits. Each `old_text` must be unique in the file unless you set `replace_all`. All edits in a call apply atomically (all-or-nothing) and you get a unified diff back. Pass `dry_run: true` to preview the diff without writing. -- **`write_file`** — for creating new files. To overwrite an existing file you +- **`write_file`** (`sandbox write` in the CLI) — for creating new files. To overwrite an existing file you must pass `overwrite: true` (it never silently clobbers). -- **`run_command`** — run any bash command in the sandbox (build, install, +- **`run_command`** (`sandbox run` in the CLI) — run any bash command in the sandbox (build, install, scaffolding, codemods). The working directory defaults to the app root; `cd` does not persist across calls, so use the `cwd` parameter or chain commands (`cd sub && cmd`). Timeout defaults to 120s (max 600s); output is capped at @@ -252,28 +260,34 @@ Messages are written so the agent can self-correct — read them and adjust. --- -## 10. Local agents over HTTP (no MCP) +## 10. Local agents via the `base44 sandbox` CLI -If your agent runs on your machine (filesystem access), you can skip MCP and call the sandbox -bridge over plain HTTP, authenticating with the Base44 CLI instead of OAuth. +If your agent runs on your machine, it can drive the same sandbox through the Base44 CLI instead of +MCP, authenticating with the Base44 CLI instead of OAuth. Same tools, same behavior, same error +codes (Section 8) — only the surface and auth differ. **Auth.** Log in with the Base44 CLI (`base44 login`) — the same credential used for -`base44 functions deploy` — and send it as a bearer header: `Authorization: Bearer `. +`base44 functions deploy`. Like the projectless `base44 connectors` commands, the sandbox +subcommands resolve the app id from `--app-id`, then `BASE44_APP_ID`, then a local `.app.jsonc`; +no `config.jsonc` is required. + +**Command names.** The CLI exposes each sandbox tool under a shorter name: -**Endpoints.** `POST https://app.base44.com/api/apps//sandbox-bridge/`, where -`` is one of `read_file`, `grep`, `list_directory`, `write_file`, `edit_file`, -`run_command`, `release`. The JSON body is the same as the matching MCP tool minus `appId` (it's -in the path). Success returns the tool's structured result; errors return -`{"message", "extra_data": {"code": }}` with the same codes as Section 8. +| MCP tool | CLI command | +|---|---| +| `list_directory` | `base44 sandbox ls` | +| `read_file` | `base44 sandbox read` | +| `write_file` | `base44 sandbox write` | +| `edit_file` | `base44 sandbox edit` | +| `run_command` | `base44 sandbox run` | +| `grep` | `base44 sandbox grep` | +| `release` | `base44 sandbox release` | ```bash -curl -X POST https://app.base44.com/api/apps//sandbox-bridge/read_file \ - -H "Authorization: Bearer $BASE44_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"paths": ["src/App.jsx"]}' +npx base44 sandbox read --app-id src/App.jsx ``` -**Hand an agent the full reference** for a specific app (instructions + endpoints, public, no +**Hand an agent the full reference** for a specific app (instructions, public, no auth needed to fetch): ``` @@ -284,7 +298,7 @@ https://app.base44.com/api/sandbox//local-agent/readme.md Everything else in this skill — the edit→preview→verify loop (Section 5), persistence (Section 6), concurrency (Section 7), and guardrails (Section 8) — applies identically; only the -transport and auth differ. +surface and auth differ. --- @@ -310,7 +324,7 @@ Two semantics to get right: yourself. After they finish, call `list_connectors` again to verify and read the **granted** scopes (a provider may grant fewer than requested). -These need only `apps:read` / `apps:write` — **not** `sandbox:write`. Over the HTTP/CLI surface +These need only `apps:read` / `apps:write` — **not** `sandbox:write`. Over the CLI surface (Section 10), the equivalent is the projectless `base44 connectors` commands (`list-available`, `initiate --integration-type --scopes --app-id `, `pull`), which print the same authorization URL. diff --git a/skills/base44-sandbox/SKILL.md b/skills/base44-sandbox/SKILL.md index 3c9d68c..79e750c 100644 --- a/skills/base44-sandbox/SKILL.md +++ b/skills/base44-sandbox/SKILL.md @@ -5,9 +5,9 @@ description: "Develop a Base44 app remotely inside Base44's cloud sandbox using # Base44 in the Cloud Sandbox -Author Base44 app code **inside Base44's cloud sandbox** with your own coding agent. There is no local checkout: you read, write, and run files through the sandbox bridge, and the platform builds and deploys from what you write. +Author Base44 app code **inside Base44's cloud sandbox** with your own coding agent. There is no local checkout: you read, write, and run files through the sandbox tools (over MCP or the `base44 sandbox` CLI), and the platform builds and deploys from what you write. -For **how to connect** to the sandbox (MCP endpoint, the HTTP bridge, the `read_file` / `write_file` / `edit_file` / `run_command` / `grep` / `list_directory` tools, the edit→preview→verify loop, persistence, and concurrency), use the **`base44-remote-dev`** skill. This skill covers **what you can author and how** once you are connected. +For **how to connect** to the sandbox (MCP endpoint or the `base44 sandbox` CLI, the `read_file` / `write_file` / `edit_file` / `run_command` / `grep` / `list_directory` tools — which the CLI exposes under shorter names (`sandbox read` / `sandbox write` / `sandbox edit` / `sandbox run` / `sandbox grep` / `sandbox ls`), the edit→preview→verify loop, persistence, and concurrency), use the **`base44-remote-dev`** skill. This skill covers **what you can author and how** once you are connected. > **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](#reference-order--the-complete-readme). @@ -19,7 +19,7 @@ Instead: **as soon as you write a resource file into the sandbox — a backend f **One exception — connectors.** OAuth connectors aren't authored as files; they're set up against the remote app by its id, either with the MCP connector tools or with the dedicated, projectless `base44 connectors` commands (which take `--app-id` and need no local project). See [Connectors](#connectors-oauth-integrations) below. -You *may* still use `run_command` for ordinary checks (e.g. `npm run build`, `npx tsc --noEmit`, `npm run lint`) and preview — that is verification, not deployment. See the edit→preview→verify loop in `base44-remote-dev`. +You *may* still use `run_command` (`sandbox run` in the CLI) for ordinary checks (e.g. `npm run build`, `npx tsc --noEmit`, `npm run lint`) and preview — that is verification, not deployment. See the edit→preview→verify loop in `base44-remote-dev`. ## What you can author today @@ -201,7 +201,7 @@ https://app.base44.com/api/sandbox//local-agent/readme.md ## Workflow in the sandbox -1. **Orient** — `list_directory` / `read_file` / `grep` to understand the app before changing anything. +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` `npm run build` / `npx tsc --noEmit`, and use `get_app_preview_url` to eyeball changes (see `base44-remote-dev`). +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. From d0871ee0eda05f1464e00bf8732b8ddf9abfe409 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 25 Jun 2026 07:49:40 +0000 Subject: [PATCH 12/15] docs(sandbox): drop the sandbox release command/tool The release command is no longer supported, so remove it from the base44 sandbox CLI mapping table. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01842h6eP9hLWHnoRrERmbLo --- skills/base44-remote-dev/SKILL.md | 1 - 1 file changed, 1 deletion(-) diff --git a/skills/base44-remote-dev/SKILL.md b/skills/base44-remote-dev/SKILL.md index 26a8ed1..1f003e0 100644 --- a/skills/base44-remote-dev/SKILL.md +++ b/skills/base44-remote-dev/SKILL.md @@ -281,7 +281,6 @@ no `config.jsonc` is required. | `edit_file` | `base44 sandbox edit` | | `run_command` | `base44 sandbox run` | | `grep` | `base44 sandbox grep` | -| `release` | `base44 sandbox release` | ```bash npx base44 sandbox read --app-id src/App.jsx From c696d19da97e3215d0b7158d35677d26761f8759 Mon Sep 17 00:00:00 2001 From: carmelc Date: Thu, 25 Jun 2026 13:20:32 +0300 Subject: [PATCH 13/15] docs(sandbox): document checkpoint command and create_checkpoint tool Add the `base44 sandbox checkpoint` CLI command (base44/cli#547) and the `create_checkpoint` MCP tool (base44-dev/apper#11608) to the base44-remote-dev and base44-sandbox skills, including the sandbox:write scope, the CLI/MCP name mapping, and the COMMIT_FLUSH_PENDING error code. Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/base44-remote-dev/SKILL.md | 30 +++++++++++++++++++++++++----- skills/base44-sandbox/SKILL.md | 3 ++- 2 files changed, 27 insertions(+), 6 deletions(-) diff --git a/skills/base44-remote-dev/SKILL.md b/skills/base44-remote-dev/SKILL.md index 1f003e0..e1a8296 100644 --- a/skills/base44-remote-dev/SKILL.md +++ b/skills/base44-remote-dev/SKILL.md @@ -8,9 +8,9 @@ description: >- names — e.g. read_file is `sandbox read`, list_directory is `sandbox ls`, run_command is `sandbox run`). Covers connecting/ authenticating, the available sandbox tools (run_command, read_file, - write_file, edit_file, grep, list_directory, get_app_preview_url, - get_app_status, list_user_apps, and the connector tools list_connectors / - initiate_connector_connection), the edit→preview→verify loop, how changes + write_file, edit_file, grep, list_directory, create_checkpoint, + get_app_preview_url, get_app_status, list_user_apps, and the connector tools + list_connectors / initiate_connector_connection), the edit→preview→verify loop, how changes persist, builder/external-agent concurrency, the in-editor "Send to Coding Agent" button + onboarding README URLs, and tips like reading the Vite dev-server logs. Triggers on "develop my Base44 app remotely", "connect @@ -94,7 +94,7 @@ on another device, and the client receives the token. | Tools | Required scope | |---|---| | `read_file`, `grep`, `list_directory`, `get_app_preview_url`, `get_app_status`, `list_user_apps` | `apps:read` (granted by default) | -| `write_file`, `edit_file`, `run_command` | `sandbox:write` | +| `write_file`, `edit_file`, `run_command`, `create_checkpoint` | `sandbox:write` | `sandbox:write` is **not** granted by default — shell and file mutation require it explicitly. If the read tools work but the mutating ones return @@ -142,6 +142,14 @@ Summarize the structure before editing. does not persist across calls, so use the `cwd` parameter or chain commands (`cd sub && cmd`). Timeout defaults to 120s (max 600s); output is capped at ~1 MB. +- **`create_checkpoint`** (`sandbox checkpoint` in the CLI) — save a named + restore point the user can later roll back to. Takes an optional `name` + (message/title; auto-generated if omitted). Any pending changes are **flushed + and committed first** so the checkpoint anchors to your latest code; it then + returns the checkpoint id, name, and git commit hash. Use it to mark a + known-good state before or after a chunk of edits. (If a recent auto-commit + can't be confirmed durable yet, it refuses with the retryable + `COMMIT_FLUSH_PENDING` rather than checkpoint stale state — retry shortly.) Example: @@ -235,7 +243,9 @@ You and the in-app Base44 builder can't mutate the same app at once: · `PATH_OUTSIDE_SANDBOX` · `PROTECTED_PATH` · `NOT_FOUND` · `BINARY_FILE` · `EDIT_TEXT_NOT_FOUND` · `EDIT_TEXT_NOT_UNIQUE` (make `old_text` unique or use `replace_all`) · `OVERWRITE_NOT_ALLOWED` (pass `overwrite: true`) · `TIMEOUT` · -`OUTPUT_TRUNCATED` · `BUILDER_BUSY` · `RATE_LIMITED` · `BACKEND_ERROR`. +`OUTPUT_TRUNCATED` · `BUILDER_BUSY` · +`COMMIT_FLUSH_PENDING` (a pending auto-commit isn't durable yet; retry shortly — +e.g. on `create_checkpoint`) · `RATE_LIMITED` · `BACKEND_ERROR`. Messages are written so the agent can self-correct — read them and adjust. @@ -255,6 +265,9 @@ Messages are written so the agent can self-correct — read them and adjust. it usually names the exact file and line. - **Let it commit.** Pause a few seconds after your final edit so the auto-commit lands before you disconnect or publish. +- **Checkpoint known-good states.** Use `create_checkpoint` (`sandbox checkpoint`) + to mark a restore point before or after a risky chunk of edits — it flushes + pending changes first, so the user can always roll back to that point. - **One agent at a time.** The feature is designed for a single external agent per app; don't run parallel sessions against the same app. @@ -281,11 +294,18 @@ no `config.jsonc` is required. | `edit_file` | `base44 sandbox edit` | | `run_command` | `base44 sandbox run` | | `grep` | `base44 sandbox grep` | +| `create_checkpoint` | `base44 sandbox checkpoint` | ```bash npx base44 sandbox read --app-id src/App.jsx ``` +`base44 sandbox checkpoint` takes an optional `--name` (message/title) and saves a restore point: + +```bash +npx base44 sandbox checkpoint --app-id --name "before refactor" +``` + **Hand an agent the full reference** for a specific app (instructions, public, no auth needed to fetch): diff --git a/skills/base44-sandbox/SKILL.md b/skills/base44-sandbox/SKILL.md index 79e750c..864e772 100644 --- a/skills/base44-sandbox/SKILL.md +++ b/skills/base44-sandbox/SKILL.md @@ -7,7 +7,7 @@ description: "Develop a Base44 app remotely inside Base44's cloud sandbox using Author Base44 app code **inside Base44's cloud sandbox** with your own coding agent. There is no local checkout: you read, write, and run files through the sandbox tools (over MCP or the `base44 sandbox` CLI), and the platform builds and deploys from what you write. -For **how to connect** to the sandbox (MCP endpoint or the `base44 sandbox` CLI, the `read_file` / `write_file` / `edit_file` / `run_command` / `grep` / `list_directory` tools — which the CLI exposes under shorter names (`sandbox read` / `sandbox write` / `sandbox edit` / `sandbox run` / `sandbox grep` / `sandbox ls`), the edit→preview→verify loop, persistence, and concurrency), use the **`base44-remote-dev`** skill. This skill covers **what you can author and how** once you are connected. +For **how to connect** to the sandbox (MCP endpoint or the `base44 sandbox` CLI, the `read_file` / `write_file` / `edit_file` / `run_command` / `grep` / `list_directory` / `create_checkpoint` tools — which the CLI exposes under shorter names (`sandbox read` / `sandbox write` / `sandbox edit` / `sandbox run` / `sandbox grep` / `sandbox ls` / `sandbox checkpoint`), the edit→preview→verify loop, persistence, and concurrency), use the **`base44-remote-dev`** skill. This skill covers **what you can author and how** once you are connected. > **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](#reference-order--the-complete-readme). @@ -205,3 +205,4 @@ https://app.base44.com/api/sandbox//local-agent/readme.md 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. From 89047704d6883ab8068b64d6d41c3e8314329c8e Mon Sep 17 00:00:00 2001 From: carmelc Date: Thu, 25 Jun 2026 18:51:52 +0300 Subject: [PATCH 14/15] docs(sandbox): functions need only entry.ts, no function.jsonc In the sandbox the function is inferred from the directory, so authors only create entry.ts under base44/functions//; the function.jsonc config is not required and is ignored in this mode. Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/base44-sandbox/SKILL.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/skills/base44-sandbox/SKILL.md b/skills/base44-sandbox/SKILL.md index 864e772..32cf81d 100644 --- a/skills/base44-sandbox/SKILL.md +++ b/skills/base44-sandbox/SKILL.md @@ -33,22 +33,14 @@ You *may* still use `run_command` (`sandbox run` in the CLI) for ordinary checks ## Backend functions -Backend functions live in `base44/functions/`, one directory per function (kebab-case name), each with a `function.jsonc` config and an entry file: +Backend functions live in `base44/functions/`, one directory per function (kebab-case name). In the sandbox you only need to create the **`entry.ts`** file directly under `base44/functions//` — **no `function.jsonc` is required** (the sandbox infers the function from the directory; the config file is ignored in this mode): ``` base44/functions/ process-order/ - function.jsonc entry.ts ``` -`function.jsonc`: -```jsonc -{ "name": "process-order", "entry": "entry.ts" } -``` -- `name` — required, must match `/^[^.]+$/` (no dots). Match the directory name. -- `entry` — required, the entry file relative to the function directory (e.g. `entry.ts`). - Entry file — functions run on **Deno** (not Node.js), export with `Deno.serve()`, and use the `npm:` prefix for npm packages: ```typescript import { createClientFromRequest } from "npm:@base44/sdk"; From 627f787a61255f6c4efb266e1c9e02d9f984d26d Mon Sep 17 00:00:00 2001 From: carmelc Date: Thu, 25 Jun 2026 18:54:14 +0300 Subject: [PATCH 15/15] docs(sandbox): note function.jsonc guidance in cli ref doesn't apply Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/base44-sandbox/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/base44-sandbox/SKILL.md b/skills/base44-sandbox/SKILL.md index 32cf81d..f528738 100644 --- a/skills/base44-sandbox/SKILL.md +++ b/skills/base44-sandbox/SKILL.md @@ -58,7 +58,7 @@ Conventions: - Read secrets with `Deno.env.get("KEY")` (configured in app settings). - Return with `Response.json(body, { status })`; handle errors and set appropriate status codes. -That's enough to author functions correctly. For deeper detail and more examples (service role, secrets, common mistakes), see the `base44-cli` skill's reference: [`functions-create.md`](../base44-cli/references/functions-create.md) — but **ignore its "Deploying Functions" / CLI sections**, which assume a local project and do not apply in the sandbox. +That's enough to author functions correctly. For deeper detail and more examples (service role, secrets, common mistakes), see the `base44-cli` skill's reference: [`functions-create.md`](../base44-cli/references/functions-create.md) — but **ignore its "Deploying Functions" / CLI sections** and its **`function.jsonc`** guidance, which assume a local project and do not apply in the sandbox (here you only write `entry.ts`). > **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`](../base44-sdk/references/functions.md) for details.