# Bolt.new File Limits: WebContainer Storage, Asset Caps, and Workarounds

Bolt.new enforces strict boundaries on file sizes, chat attachments, and overall project scale. While the platform allows up to 10 MB uploads on free plans and 100 MB on paid tiers, projects must stay under a combined 100 MB to publish. Understanding the distinction between LLM context limits and browser WebContainer memory constraints allows developers to build larger applications by decoupling media and databases from the local repository.

Source: https://fast.io/resources/bolt-new-file-limit/
Author: [Derek Labian](https://fast.io/authors/derek-labian/)
Last reviewed: 2026-10-27

## What Is the Bolt.new File Limit Across Different Tiers?

Bolt.new enforces two separate hard boundaries on project files: chat uploads max out at `10 MB` per file on free accounts (`100 MB` on paid plans), and projects fail to publish if the total repository size exceeds `100 MB`. Beneath those documented numbers lies a third, physical constraint: the browser WebContainer memory ceiling.

The Bolt.new file limit encompasses the browser WebContainer memory ceiling (typically a `1-2 GB` heap limit) and project asset size caps, which cause in-browser development environments to crash or reject large repositories and media assets.

Developers transitioning from traditional cloud IDEs often assume in-browser development tools run on dedicated remote virtual machines with abundant resources. On conventional platforms, a backend container might run on dedicated cloud hardware with `8 GB` or `16 GB` of memory and generous disk storage. Bolt.new operates differently: the development server, virtual filesystem, and Node.js process execute directly inside the user's browser tab. Every package installed, file written, and compiler pass initiated shares the browser tab's allocated memory pool.

When building full-stack web applications, importing existing codebases, or adding binary assets, developers encounter several distinct operational boundaries:

* **Chat upload attachment caps.** When attaching files to guide prompt generation or supply design specifications, Bolt.new restricts attachments by subscription tier. Free accounts permit up to `5` files per message with a maximum size of `10 MB` each. Paid tiers, including Pro, Teams, and Enterprise, raise this threshold to `20` files per message at up to `100 MB` per file.
* **Project publishing cap.** To publish successfully, Bolt projects must be under 100MB in combined total size. If the combined repository footprint exceeds `100 MB`, the deployment process halts and throws an error stating that the project is too large to deploy.
* **WebContainer browser tab memory limits.** StackBlitz WebContainers run inside client browser tabs via WebAssembly. JavaScript heap allocations in modern desktop browsers generally max out between `1 GB` and `2 GB` per tab. Complex bundling routines, expansive dependency trees, or memory leaks cause browser tabs to run out of memory before reaching any disk threshold.
* **Active LLM context window limits.** The language model powering the AI assistant has an attention budget measured in tokens. Adding large codebases or large reference files to chat prompts fills this context window, leading to forgotten requirements, lower-quality code, and slow response generation.

| Constraint Layer | Documented Limit | Enforcement Mechanism | Common Failure Symptom |
| --- | --- | --- | --- |
| Chat Attachments (Free) | 5 files per message, 10 MB per file | Upload parser rejects file | Upload error banner in chat interface |
| Chat Attachments (Paid) | 20 files per message, 100 MB per file | Upload parser rejects file | Upload error banner in chat interface |
| Project Deployment | 100 MB total combined repository size | Build and publish packaging gate | Error: Project is too large to deploy |
| WebContainer Runtime | 1 GB to 2 GB V8 browser tab heap | Browser process memory manager | RangeError: Out of memory: wasm memory |
| LLM Context Window | Dynamic token budget per model | Attention window token truncation | Slower generation, forgotten instructions |

Understanding which barrier you have hit is the first step toward resolving development blocks. An upload error requires changing how you attach files, a publishing failure requires pruning repository assets, and a browser crash requires restructuring dependencies and build tasks.

## Why WebContainers Crash: Virtual Filesystems and Memory Ceilings

To diagnose instability in large Bolt.new applications, developers must understand how StackBlitz WebContainers function. A WebContainer is a WebAssembly-based operating system layer executing Node.js inside the browser tab. It relies on modern web standards, specifically SharedArrayBuffer for thread synchronization and cross-origin isolation headers (COOP and COEP) to maintain secure memory boundaries.

Because WebContainers run client-side, they do not interact with a local operating system block device or virtual hard disk. Instead, WebContainers maintain an in-memory virtual filesystem mapped directly into the browser tab's RAM. Every file created by the AI agent, every dependency in the node_modules folder, and every asset in the public directory consumes a portion of the tab's available memory.

Desktop browsers like Chrome, Edge, and Firefox allocate a variable memory envelope to each tab process, typically topping out around `1.4 GB` to `2 GB` on 64-bit systems. Mobile browsers face tighter limits: large projects may run into memory limitations because the memory usage for a web page on a mobile device is more constrained. On iOS Safari and Android Chrome, the mobile operating system enforces strict memory quotas, frequently terminating tabs that consume more than a few hundred megabytes.

When a Bolt.new application grows beyond browser tab memory thresholds, developers see specific crash signatures:

* **RangeError: WebAssembly.instantiate(): Out of memory: wasm memory.** This error occurs when the browser cannot allocate a contiguous memory block for a WebAssembly instance. It commonly appears during package installation or when spawning background dev server processes.
* **JavaScript heap out of memory.** Build tools such as Vite, Next.js, or Webpack encounter heap exhaustion when compiling large bundles, parsing large CSS libraries, or running extensive TypeScript checks.
* **This browser tab is running out of memory.** StackBlitz displays this alert when overall resource consumption approaches the tab process termination limit.

Beyond total byte size, file count introduces a distinct operational bottleneck. WebContainers track file system events using an in-memory event bus. When a project contains thousands of individual files, such as when installing heavy packages with deep nested trees, the virtual file watcher increases CPU load and memory pressure. The development server may drop connections, hot-module replacement (HMR) can stop functioning, and synchronization between the editor and the preview pane experiences timeouts.

Native binary addons introduce another hard technical boundary. WebContainers execute only JavaScript and WebAssembly code. Standard Node.js packages compiled with native C++ bindings, such as legacy image processors or database drivers, are disabled by default via the `--no-addons` flag. If an AI agent attempts to install a library requiring precompiled C++ binaries without a WebAssembly fallback, package installation or runtime execution fails immediately.

## Distinguishing Repository Size from the LLM Context Window

A frequent point of confusion among developers is the distinction between repository file size and the language model's active context window. While both issues degrade performance, they stem from different architectures and require different solutions.

The context window is the active working memory of the AI model. When you submit a prompt, Bolt.new packages your instructions, recent conversation history, and relevant project source files into the model's token payload. Uploading a `5 MB` data file or an extensive documentation folder through the chat box converts that content into tokens. A single large CSV or JSON file can consume `50,000` to `100,000` tokens in one request. When the context window fills up, the model begins dropping older instructions, repeats earlier bugs, and generates lower-quality code.

By contrast, adding a file directly through Code view stores it in the project's virtual filesystem without sending it through the chat prompt. Dragging an image or document into the public folder in Code view consumes zero prompt tokens. However, that file still counts toward the `100 MB` deployment limit and consumes browser memory inside the WebContainer.

To keep your project responsive and maintain high code quality, apply these operational practices:

* **Reset active context with the clear command.** Typing `/clear` in the chat box clears conversational history while keeping your application source code untouched. The agent evaluates the codebase with a fresh context window, saving tokens and eliminating stale debugging loops.
* **Maintain persistent guidelines in an agents.md file.** Instead of pasting design standards, architectural constraints, or tech stack requirements into every chat prompt, place them in an `agents.md` file in the project root. Bolt.new automatically detects this file and references its instructions, eliminating repetitive prompt text.
* **Prune unreferenced files and dead dependencies.** During iterative development, AI agents frequently generate unused helper functions, obsolete components, or abandoned test files. Opening the terminal in Code view and running a cleanup tool removes dead code without consuming tokens:
```bash
npx knip --production --fix --allow-remove-files
```
* **Split monolithic source files.** Files containing more than `700` lines of code burden the context window whenever the agent inspects or edits them. Prompt the agent to refactor large files into focused sub-components and modular route handlers. Smaller files keep the model focused on the exact code block requiring modification.

## Architectural Workarounds: Decoupling Media, Data, and Blobs

The primary architectural rule for scaling Bolt.new projects is separating application logic from static assets and large corpora. The in-browser WebContainer should contain only application code, configuration files, and lightweight UI components. Static assets, media files, and document collections should live in external cloud storage.

Treating the WebContainer as an ephemeral compilation environment rather than a permanent storage bucket prevents deployment failures and avoids browser memory crashes.

### Offload Media and Binary Assets to Cloud Storage
High-resolution graphics, video backgrounds, audio clips, and PDF downloads should never live in the repository's public directory. Storing three `25 MB` demo videos immediately triggers the `100 MB` publish error. Instead, upload media assets to cloud storage or an external object store. Once uploaded, instruct Bolt.new to reference the files by their public HTTPS URLs rather than relative local paths. For example, replace local asset paths with absolute CDN endpoints in your image tags and style sheets.

### Connect Managed Databases for Structured Data
Developers often prompt Bolt to create local mock datasets, checking `15 MB` JSON files into the source tree. This practice bogs down the virtual filesystem and inflates build times. Instead, connect your Bolt app to a managed database like Supabase or Neon. Storing records in an external PostgreSQL database keeps the frontend repository lightweight while persisting data across project rebuilds and browser sessions.

### External Workspaces and MCP for Agent Teams
When building applications that interact with large document libraries, product documentation, or reference manuals, storing those documents in the Bolt project repository quickly breaks both the WebContainer and the AI context window. A thick operational manual or a collection of technical whitepapers will cause WebContainer sync timeouts and exhaust token limits within minutes.

This is where dedicated agent workspaces provide a scalable architecture. Fast.io functions as an intelligent workspace platform designed for agentic workflows. Instead of checking heavy reference materials into the Bolt repository, teams place their document corpora into a shared Fast.io workspace, either by direct upload or synced from existing cloud storage. Cloud Sync connects Google Drive, Dropbox, Box and OneDrive folders to a workspace, one-way or two-way, on a schedule or on demand. When Intelligence is enabled on the workspace, files are automatically indexed for hybrid search, combining full-text search, semantic search, and metadata filtering.

Coding agents connect directly to Fast.io using the remote Model Context Protocol (MCP) server over Streamable HTTP at:
`https://mcp.fast.io/mcp/code`

General MCP clients and assistant integrations connect at:
`https://mcp.fast.io/mcp/tools`

Through these endpoints, agents use MCP actions such as search, execute, and upload to query indexed documents on demand. The agent searches the workspace, retrieves only the relevant paragraphs with precise citations, and incorporates the facts into its code generation without ever loading megabytes of raw files into the browser WebContainer. Fast.io leaves Bolt's native upload limits where they are while providing a searchable home for large corpora that exceed in-browser constraints.

Fast.io provides full per-file version history and a detailed activity log of changes, enabling human developers and autonomous agents to collaborate safely. Files remain organized in workspaces with role-based permissions set per organization, workspace, and share. Monthly plans start with a 14-day free trial that requires a credit card. Plans include Starter at `$9.99` per month (`3` seats, `250 GB` storage, `5` workspaces, `100,000` credits), Business at `$49.99` per month (`10` seats, `5 TB` storage, `50` workspaces, `600,000` credits), and Enterprise at `$199.99` per month (`30` seats included, `25 TB` storage, `200` workspaces, `3,000,000` credits). Extra credits are available at `$10` per `100,000` credits for predictable budgeting as agent workloads expand.

Learn more about setting up agent storage at [Fast.io Storage for Agents](/storage-for-agents/) and explore [Fast.io Pricing](/pricing/). For detailed tool configuration, review the [Fast.io MCP Documentation](https://mcp.fast.io/docs) and [Fast.io Agent Onboarding](https://fast.io/llms.txt).

## Steps to Shrink Bloated Bolt.new Repositories

If your Bolt.new project throws the Project is too large to deploy error or lags inside the browser, follow this practical five-step recovery procedure to bring the codebase back under the limits.

### Step 1: Download and Measure Your Repository Footprint
Before altering code or deleting assets, export a complete backup. In the Bolt interface, click the project menu and select Download Project. Unzip the downloaded archive on your local workstation and inspect directory sizes using your terminal:
```bash
du -sh * | sort -h
```
Identify the specific subdirectories consuming the most space. In most cases, the public directory, build artifacts in dist, or root-level mock data directories account for the majority of total storage bloat.

### Step 2: Purge Unused Media and Cached Build Outputs
Delete any unreferenced images, obsolete video clips, and accidentally committed build artifacts. If you have generated multiple design variations or test files, remove them. You can prompt Bolt directly in the chat:
`Find all images and media files in the public directory that are not imported or referenced in the codebase, list them, and delete them.`
Alternatively, open Code view, expand the public directory, and manually delete unneeded files.

### Step 3: Establish a .bolt/ignore Configuration
Create a `.bolt` directory in your project root if it does not already exist, and add an ignore file inside it (`.bolt/ignore`). Similar to `.gitignore`, this file instructs Bolt's AI agent to bypass scanning specific directories when constructing context. Add paths such as:
```text
dist/
build/
coverage/
*.log
docs/
assets/archive/
```
By ignoring non-essential documentation and build outputs, you keep the agent's context window focused strictly on operational code.

### Step 4: Migrate Local Assets to External Cloud URLs
Move required images, audio, or video files to an external cloud storage provider or CDN. Once uploaded, update your application code to reference the remote HTTPS URLs. You can instruct Bolt with a prompt:
`Replace local references to public/hero-banner.png with https://storage.example.com/assets/hero-banner.webp and then delete the local file from public/.`
Verify that your components render the remote assets properly in the preview pane.

### Step 5: Verify Build Size and Publish
Open the terminal in Code view and execute a production build to confirm compilation completes cleanly without memory warnings:
```bash
npm run build
```
Once the build passes, trigger the publish action. With media assets decoupled and dead files pruned, your repository will comfortably clear the `100 MB` publishing threshold, and your WebContainer environment will remain stable and fast.

## Frequently asked questions

### What is the file upload limit on Bolt.new?

Bolt.new limits chat attachments based on account tier. Free accounts can upload up to `5` files per message with a maximum size of `10 MB` per file. Paid plans allow up to `20` attachments per message with a maximum size of `100 MB` per file. Supported formats include images, documents, code files, configuration files, and shell scripts.

### What is the maximum project size allowed to publish a Bolt.new app?

Bolt Cloud hosting enforces a strict combined project size limit of `100 MB`. If your repository exceeds `100 MB`, the deployment process fails with an error stating that the project is too large to deploy. To resolve this, download your project, remove unreferenced media or build artifacts, and host large assets on external cloud storage.

### Why does Bolt.new crash with an out of memory error during builds?

Bolt.new runs on StackBlitz WebContainers, which execute Node.js inside the browser tab via WebAssembly. Desktop browsers allocate a maximum heap of approximately `1 GB` to `2 GB` per tab, while mobile browsers enforce much tighter limits. When dependencies, build tools, or large file trees exceed this browser tab memory ceiling, the WebContainer crashes with a WebAssembly or JavaScript heap out-of-memory error.

### How does the Bolt.new context window differ from the WebContainer project size?

The context window is the active working memory used by the AI model during chat interactions, measured in tokens. Adding large files or extensive conversation histories to the chat fills the context window, causing sluggish responses and reduced code quality. The WebContainer project size is the physical byte footprint of your files in the browser's virtual filesystem, bounded by the `100 MB` publishing cap and tab RAM limits.

### Can I use native C++ Node.js packages in Bolt.new?

No. WebContainers execute only JavaScript and WebAssembly within the browser sandbox. Standard Node.js packages that rely on native C++ addons compiled for specific operating systems are disabled by default via the `--no-addons` flag. Any package requiring binary compilation must have a pure JavaScript or WebAssembly alternative to function inside Bolt.new.

### How should I store large assets like videos, datasets, and PDFs for a Bolt.new app?

Large assets should be stored outside the Bolt.new repository. Host images, videos, and PDFs in cloud object storage or intelligent workspaces like Fast.io, and reference them in your frontend components via public HTTPS URLs. For datasets and document collections that AI agents need to search, connect your workflow to Fast.io workspaces over MCP to query files semantically without loading raw documents into the WebContainer.

## Sources

- [Bolt Support: Publishing issues](https://support.bolt.new/troubleshooting/publish-issues): Bolt projects must stay under a combined total size of 100MB to publish to Bolt hosting.
- [StackBlitz Docs: WebContainers Browser Support](https://developer.stackblitz.com/platform/webcontainers/browser-support): WebContainers experience memory limitations on mobile devices due to browser page memory constraints.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli. MCP setup is at https://mcp.fast.io/docs: Claude and most MCP clients connect to https://mcp.fast.io/mcp/tools, ChatGPT to https://mcp.fast.io/mcp/operations, and coding agents to https://mcp.fast.io/mcp/code.