The sandbox

Your app is not a mock-up or a preview rendering. It is a real Next.js application running a real development server, in its own isolated environment. That environment is the sandbox.

One project, one sandbox. They are created together and destroyed together.

What is inside it

Every sandbox starts as a copy of the same starter app:

• Next.js 14.2.35 with the App Router
• React 18
• Tailwind CSS 3.4, with PostCSS and Autoprefixer
• JavaScript, not TypeScript — files are .jsx
• The @/ path alias, pointing at the project root

The files it starts with are package.json, next.config.mjs, jsconfig.json, postcss.config.js, tailwind.config.js, app/layout.jsx, app/page.jsx and app/globals.css. That is the whole template. Its app/page.jsx is a placeholder reading "Your app is being built", which the builder replaces the moment it writes your first screen.

Everything else in your project — every component, every page, every package — was put there by the builder because you asked for it.

The two kinds of sandbox

Which kind your project gets is chosen by a platform administrator under Admin → Settings, and it is decided when the project is created. A project never moves between the two.

Local. The sandbox is a folder on the machine running Bookbag, with its own development server on its own port. Ports are handed out from a configured range, 4100 to 4199 by default. The preview address is http://localhost:<port>, which means the preview only works from that machine. This is the right choice for development and small installations, and it needs no external service.

Daytona. The sandbox is an isolated cloud container running a node:20 image, with the development server on port 3000 and a public preview link supplied by Daytona. This is the production setting.

You can tell which one you have from the preview address: a localhost address means local.

When it starts

The sandbox is created during the first build run, not when you create the project. The sequence, on a local sandbox, is:

1. The project folder is created.
2. The starter template is copied in — step Copying the app template….
3. npm install runs, with an 8-minute limit — step Installing dependencies (first build only — this takes a minute)….
4. The development server starts and is polled once a second for up to 60 seconds until it answers.
5. The preview address is published and the preview pane comes alive.

On a cloud sandbox the same sequence takes a few minutes longer: the container has to be created and the template uploaded file by file, npm install gets 10 minutes, and the readiness wait is 90 seconds.

All of this happens before the builder writes a line of your app, which is why a first build feels much slower than every build after it. Every later run reuses the same sandbox and skips straight to the work.

The five sandbox states

Your project records one of these at all times:

State	Meaning
none	No sandbox yet. This is a project created without a prompt, or one whose first build has not started.
creating	Being set up.
running	The development server is up and the preview works.
stopped	The server is not running. Archiving a project puts it here, and so does a server restart that found the server gone. The next build starts it again.
error	Something went wrong. The reason is shown in the preview pane.

Does it ever shut down on its own?

No. There is no idle timeout, no automatic sleep and no cleanup job. A sandbox runs until one of three things happens:

• You archive the project. The development server is stopped, the state becomes stopped, and every file is kept.
• You delete the project. The sandbox is destroyed and the folder or container removed entirely.
• The server restarts. On start-up Bookbag checks every project that thought it was running. Servers that survived the restart are kept — they run detached, in their own process group, so they usually do. Dead ones are marked stopped and revived on the project's next build.

A sandbox that is stopped costs you nothing and loses nothing. Send a message and it comes back.

What the builder can and cannot reach

The sandbox is the boundary. Everything the builder does happens inside your project folder.

• Every file path is resolved against the project root. A path that would climb out of it is refused with Path escapes the project: <path>.
• Commands that would start a competing development server, or a background or long-lived process, are refused.
• node_modules, .next and .git are hidden from file listings.

The limits you can actually hit

Limit	Value	What happens at it
Files listed	500	The list is cut off silently. Affects the Code tab, the download and the security check.
File read length	60,000 characters	The rest is replaced with …[truncated: file is N chars]. This applies to the builder's own reads, the Code tab and the downloaded zip.
Shell command	3 minutes	The command is killed and its last 2,000 characters of output returned.
npm install	8 minutes local, 10 minutes cloud	The build fails with the install output attached.
Shell output kept	20,000 characters	Truncated.
Development server log	last 6,000 characters	Only the tail is readable.

The 60,000-character limit is the one most worth knowing. A generated file that long is unusual, but if you hit it, the copy in your download is truncated too.

Two quirks to be aware of

Publishing leaves files behind. Publishing builds a static export into a .next-export folder inside your project and does not remove it afterwards. That folder is not hidden the way node_modules is, so after your first publish you will see it in the Code tab, in your downloaded zip, and in the files the security check reads. It is harmless, but it is noise.

Binary files are not handled. Everything is read as text. An image the builder placed under public/ will look like nonsense in the Code tab and will be corrupted in the downloaded zip. Ask the builder to reference images by URL rather than adding binary files.

Next

• The preview — the window onto the running sandbox.
• When a build fails — including every sandbox error message.