The generation lifecycle
Sandbox is provisioned
When you send your first message in a project, ForgeAI checks whether a sandbox already exists for that project. If one does, it reconnects to the existing sandbox. If not, it creates a new one using the
forgeai-v1 template, which has Next.js and all dependencies pre-installed. The sandboxId is stored in the database so the sandbox survives across sessions.Agent runs and installs packages
The code agent starts its generation loop. When it calls the
terminal tool — typically to run npm install for a new dependency — the status message “Installing packages…” appears in the chat input area.Files are written to the sandbox
Each time the agent calls
createOrUpdateFiles, the files are written directly into the sandbox filesystem and the status updates to “Generating project files…”. The dev server’s hot reload picks up the changes automatically.Agent reads existing files
When the agent inspects the current project state before making edits, the status shows “Reading project files…”.
Images are downloaded
If the agent fetches a photo from Unsplash, the status shows “Downloading images…” while the image is written to
/public/assets/unsplash/ inside the sandbox.Preview URL is generated
After the agent loop completes, ForgeAI calls
sandbox.getHost(3000) to retrieve the public hostname for port 3000. The status shows “Generating sandbox url…” briefly while this resolves.Project is named and saved
A lightweight naming agent generates a short title from your original prompt. The status shows “Generating project name…” then “Saving to db…” as the result, sandbox URL, and generated files are written to the database.
Sandbox persistence
The E2B sandbox is tied to your project. Each project stores itssandboxId in the database, so reconnecting to an existing project re-uses the same sandbox rather than starting from scratch. Previous file state is restored from the last code fragment, and the agent continues from where it left off.
Sandboxes have a session timeout. If your project has been idle for an extended period, ForgeAI will automatically create a fresh sandbox and restore your files before the next generation run.
Viewing the preview
In the project view, the Preview tab (globe icon) renders your app in a full-height iframe pointed at the sandbox URL. Switch to the Code tab to browse and edit the generated files. Both tabs share the same underlying sandbox — edits made in the code editor update the same running app you see in the preview.Real-time status updates
Status messages are delivered through Inngest Realtime using a per-project channel (Project:<projectId>). The chat input subscribes to this channel and displays the latest message as the agent works. No page reload is required to see progress.