Importing Sandboxes

Edit this page

There are many ways to create a sandbox on CodeSandbox, either programatically or with a UI.

Create Wizard

The most popular way of creating a new sandbox is the Create Wizard.

Create Wizard

The Create Wizard shows you all public templates that are currently available, and takes you to the sandbox that corresponds to the template. You can edit and fork this sandbox to continue with the template.

Import from GitHub

You can import a GitHub repository in CodeSandbox by going to the import wizard and giving the URL to your GitHub repository. Note that we just take the last part of the url (everything after and paste it after We support custom branches and subdirectories as well. Here is an example URL:

The imported repository will always stay up to date with your latest commits. This means that any change to the GitHub repository will be reflected immediately to the sandbox.

Setting inference

We infer sandbox settings based on several files in a repository.

Sandbox Setting Inferred from
Title name field in package.json
Description description field in package.json
Tags keywords field in package.json
Dependencies dependencies and devDependencies fields in package.json
Entry file main field in package.json . Otherwise defaults to default template setting
Template - Vue If there are .vue files.
Template - Preact If package.json dependencies contains preact-cli .
Template - React If package.json dependencies contains react-scripts .
Template - React-Typescript If package.json dependencies contains react-scripts-ts .
Template - Svelte If package.json dependencies contains svelte .


You can find the source of our git extractor here.

Export with CLI

You can export a local project to CodeSandbox by using our CLI.

You can install our CLI by running npm install -g codesandbox. Then you can export a project by running codesandbox {directory}.

Note: Our CLI is not updated yet and only supports create-react-app projects at this moment

Example usage

$ npm install -g codesandbox
$ codesandbox ./

Define API

We offer an API that allows you to programatically create a sandbox. This is most often useful in documentation: code examples can generate a sandbox on the fly. You can call the endpoint both with a a GET and with a POST request.

How it works

The API only needs one argument: files. This argument contains the files that will be in the sandbox, an example body would be:

  "files": {
    "index.js": {
      "content": "console.log('hello!')",
      "isBinary": false
    "package.json": {
      "content": {
        "dependencies": {}

Every request requires a package.json. This file can either be a string or an object. We determine all information of the sandbox from the files, like we do with the GitHub import.

GET Request

It's very hard to send the JSON parameters with a GET request, there is a chance of unescaped characters and the URL hits its limit of ~2000 characters quickly. That's why we first compress the files to a compressed lz-string. We offer a utility function in the codesandbox dependency for this. The implementation looks like this:

import { getParameters } from 'codesandbox/lib/api/define';

const parameters = getParameters({
  files: {
    'index.js': {
      content: "console.log('hello')",
    'package.json': {
      content: { dependencies: {} },

const url = `${parameters}`;

Example Sandbox


You can do the exact same steps for a POST request, but instead of a URL you'd show a form. With a POST request you can create bigger sandboxes.

Example Sandbox

Define without render

If you want to define a new sandbox without getting it rendered, you can add ?json=1 to the request. For instance Instead of the render, the result will be json data providing you with the id of the new sandbox.

This is useful, for instance, if you need to create a new sandbox programatically, so you can then embed it on your site (See Embed documentation).

Both get and post requests are supported.