docs: sandbox docs 1.0

docs/docs.json

@@ -1,6 +1,6 @@
 {
 	"$schema": "https://mintlify.com/docs.json",
-	"theme": "mint",
+	"theme": "maple",
 	"name": "Codegen",
 	"colors": {
 		"primary": "#a277ff",
@@ -32,9 +32,18 @@
 							"integrations/linear",
 							"integrations/github",
 							"integrations/web-search",
-							"integrations/sandboxes",
 							"integrations/postgres"
 						]
+					},
+					{
+						"group": "Sandboxes",
+						"pages": [
+							"sandboxes/overview",
+							"sandboxes/setup-commands",
+							"sandboxes/editor",
+							"sandboxes/environment-variables",
+							"sandboxes/web-preview"
+						]
 					}
 				]
 			},

docs/integrations/linear.mdx

@@ -1,7 +1,7 @@
 ---
 title: "Linear Integration"
 sidebarTitle: "Linear"
-icon: "pencil"
+icon: "book"
 ---
 
 Integrate Codegen with your Linear workspace to allow agents to interact with issues, manage projects, and keep your team updated.

docs/integrations/slack.mdx

@@ -4,6 +4,8 @@ sidebarTitle: "Slack"
 icon: "slack"
 ---
 
+<img src="/images/slack.png" />
+
 Connect Codegen to your Slack workspace to enable seamless communication between agents and your team.
 
 ## Capabilities & Functions

docs/sandboxes/editor.mdx

@@ -0,0 +1,47 @@
+---
+title: "Remote Editor (VSCode)"
+sidebarTitle: "Editor"
+icon: "pencil"
+---
+
+Codegen provides access to a remote VSCode editor instance that is directly connected to your active sandbox environment. This powerful feature allows for real-time interaction with the agent's workspace, offering capabilities for live debugging, manual intervention, and detailed progress monitoring.
+
+## Accessing the Editor
+
+When an agent is active and utilizing a sandbox, a link or button to access the Remote Editor will typically be available on the agent's trace page or within the Codegen UI.
+
+<Frame caption="Access the Remote Editor from the Codegen UI (example)">
+  <img src="/images/sandbox-buttons.png" alt="Remote VSCode Editor" />
+</Frame>
+
+Access to the editor is password-protected. A unique password will be dynamically generated at runtime for each session and provided to you, ensuring secure access to the sandbox environment.
+
+## Capabilities
+
+The Remote Editor offers several key benefits:
+
+- **Run Arbitrary Commands:** Open a terminal directly within VSCode to execute any shell commands in the sandbox. This is useful for:
+  - Manually running tests.
+  - Inspecting file contents.
+  - Trying out different commands or scripts.
+  - Installing additional temporary tools or dependencies.
+- **View Agent's Progress:** See the files the agent is creating or modifying in real-time. This provides a transparent view into the agent's operations and can help in understanding its decision-making process.
+- **Live Debugging:** If the agent is running a service or script, you can use VSCode's debugging tools (if applicable to the language/runtime) to step through code, inspect variables, and diagnose issues.
+- **Manual Edits:** While generally agents manage the codebase, you can make manual edits to files directly if needed for quick fixes or experiments. Be mindful that agent actions might overwrite manual changes if not coordinated.
+
+## How it Works
+
+The remote editor essentially provides a fully functional VSCode interface tunneled into the agent's sandbox. This means you are working directly within the same environment as the agent, with access to the same file system, installed tools, and [Environment Variables](./environment-variables).
+
+<Tip>
+  The Remote Editor is an excellent tool for gaining deeper insights into an
+  agent's operations and for situations where you need to interact more directly
+  with the sandbox environment than through standard agent commands.
+</Tip>
+
+<Note>
+  Like other sandbox features, the editor session is tied to the lifecycle of
+  the sandbox. Changes made might be ephemeral if the sandbox is reset or a new
+  snapshot is used for subsequent runs, unless those changes are committed back
+  through the agent or other means.
+</Note>{" "}

docs/sandboxes/environment-variables.mdx

@@ -0,0 +1,34 @@
+---
+title: "Environment Variables"
+sidebarTitle: "Env Variables"
+icon: "code"
+---
+
+Codegen sandboxes come pre-configured with a set of environment variables to facilitate common development tasks and ensure smooth operation of tools and package managers. Understanding these variables can be helpful when debugging or customizing setup scripts.
+
+## Standard Environment Variables
+
+The following environment variables are typically available within Codegen sandboxes:
+
+| Variable                          | Default Value                                 | Description                                                                                                                                 |
+| --------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `NVM_DIR`                         | _Dynamic_                                     | Specifies the directory where Node Version Manager (NVM) is installed. The exact path is set during sandbox initialization.                 |
+| `PATH`                            | _Dynamic (includes NVM Node version)_         | The system's execution search path. It's augmented to include the `bin` directory of the currently active Node.js version (managed by NVM). |
+| `NVM_BIN`                         | _Dynamic (points to active Node version bin)_ | Points to the `bin` directory of the currently active Node.js version. This is also set dynamically by NVM.                                 |
+| `NODE_VERSION`                    | _Dynamic (current NVM Node version)_          | Indicates the version of Node.js that is currently active in the sandbox, as managed by NVM.                                                |
+| `NODE_OPTIONS`                    | `"--max-old-space-size=8192"`                 | Configures V8 to allow a max old space size of 8192MB. Useful for memory-intensive Node.js apps.                                            |
+| `DEBIAN_FRONTEND`                 | `"noninteractive"`                            | Instructs Debian-based package managers (like `apt`) to run without interactive prompts.                                                    |
+| `PYTHONUNBUFFERED`                | `"1"`                                         | Forces `stdout` and `stderr` for Python to be unbuffered, meaning output is written immediately.                                            |
+| `COREPACK_ENABLE_DOWNLOAD_PROMPT` | `"0"`                                         | Disables the Corepack prompt when it needs to download a package manager (like Yarn or pnpm).                                               |
+| `PYTHONPATH`                      | `"/usr/local/lib/python3.13/site-packages"`   | Adds the specified directory to Python's module search path. (Python version may vary).                                                     |
+| `IS_SANDBOX`                      | `"true"`                                      | A boolean flag indicating the environment is a Codegen sandbox.                                                                             |
+| `NPM_CONFIG_YES`                  | `"true"`                                      | Configures npm to automatically answer "yes" to prompts.                                                                                    |
+| `PIP_NO_INPUT`                    | `"1"`                                         | Instructs pip (Python's package installer) to operate in non-interactive mode.                                                              |
+| `YARN_ENABLE_IMMUTABLE_INSTALLS`  | `"false"`                                     | Disables Yarn's "immutable installs" feature, allowing `yarn install` to modify the lockfile.                                               |
+
+<Note>
+  The values for variables like `NVM_DIR`, `PATH`, `NVM_BIN`, and `NODE_VERSION`
+  are typically set dynamically during the sandbox setup process, depending on
+  the specific NVM and Node.js versions being used. The `PYTHONPATH` may also
+  vary based on the Python installation within the sandbox.
+</Note>

docs/integrations/sandboxes.mdx → docs/sandboxes/overview.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Code Execution Sandboxes"
-sidebarTitle: "Sandboxes"
+sidebarTitle: "Overview"
 icon: "box"
 ---
 
@@ -31,4 +31,4 @@ Sandboxes are typically configured per-agent run or defined within your Codegen
 <Note>
   Sandboxes are ephemeral; their state is not typically persisted between agent
   runs unless specifically configured for caching or stateful operations.
-</Note>
+</Note>{" "}

docs/sandboxes/setup-commands.mdx

@@ -0,0 +1,69 @@
+---
+title: "Setup Commands"
+sidebarTitle: "Setup Commands"
+icon: "terminal"
+---
+
+Codegen lets you configure custom setup commands that run once when initializing a repository's sandbox environment. The resulting file system snapshot serves as the starting point for all future agent runs, ensuring consistency.
+
+<Tip>
+  The most common use cases for setup commands is installing dependencies, e.g.
+  `npm install`
+</Tip>
+
+## Accessing Setup Commands
+
+To configure setup commands for a repository:
+
+1.  Navigate to [codegen.com/repos](https://codegen.com/repos).
+2.  Click on the desired repository from the list.
+3.  You will be taken to the repository's settings page. The setup commands can be found at a URL similar to `https://codegen.com/{your_org}/{repo_name}/settings/setup-commands` (the exact URL structure might vary slightly, look for a "Setup Commands" or "Sandbox Configuration" section).
+
+<Frame caption="Set setup commands at codegen.com/repos">
+  <img src="/images/setup-commands-ui.png" alt="Setup Commands UI" />
+</Frame>
+
+## How it Works
+
+Enter your desired setup commands in the provided text area, with one command per line. These commands will be executed in sequence within the sandbox environment.
+
+For example, you might want to:
+
+- Switch to a specific Node.js version.
+- Install project dependencies.
+- Run any necessary build steps or pre-compilation tasks.
+
+After the commands are executed successfully, Codegen takes a snapshot of the sandbox's file system. This snapshot then serves as the base environment for future agent interactions with this repository, meaning your setup commands don't need to be re-run every time, saving time and ensuring consistency.
+
+## Common Examples
+
+Here are a few common use cases for setup commands:
+
+```bash
+# Switch to Node.js version 20
+nvm use 20
+
+# Install npm dependencies
+npm install
+```
+
+```bash
+# Install Python dependencies
+pip install -r requirements.txt
+```
+
+```bash
+# Or a combination of commands
+nvm use 18
+npm ci
+npm run build
+```
+
+<Note>
+  Ensure your setup commands are non-interactive and can run to completion
+  without user input.
+</Note>
+<Tip>
+  The environment variables listed in the "Env Variables" section are available
+  during the execution of these setup commands.
+</Tip>

docs/sandboxes/web-preview.mdx

@@ -0,0 +1,64 @@
+---
+title: "Web Preview"
+sidebarTitle: "Web Preview"
+icon: "browser"
+---
+
+Codegen's Web Preview feature lets you start a development server in your sandbox and view your running application directly in the Codegen interface.
+
+## How it Works
+
+Define your web server startup commands just like [Setup Commands](./setup-commands). Instead of taking a snapshot, Codegen keeps the server running as a long-lived process.
+
+A "View Web Preview" button appears on the agent trace page once the server starts. Click it to open your running application in a new tab through Codegen's secure proxy.
+
+<Frame caption="Access the Web Preview from the agent trace page">
+  <img
+    src="/images/sandbox-buttons.png"
+    alt="Web Preview button on Trace Page"
+  />
+</Frame>
+
+## Configuration
+
+You configure Web Preview commands in a manner similar to Setup Commands, likely within the same repository settings area (e.g., `https://codegen.com/{your_org}/{repo_name}/settings/web-preview`).
+
+You'll provide the command(s) necessary to start your development server. Ensure that your server is configured to listen on an appropriate host (often `0.0.0.0`) and a predictable port that Codegen can then expose.
+
+<Warning>
+  The web server started for Web Preview **MUST** listen on port 3000. Codegen
+  is specifically configured to look for and expose applications running on this
+  port within the sandbox.
+</Warning>
+
+## Common Examples
+
+The primary use case is starting a development web server:
+
+```bash
+# For a Node.js/npm project
+npm run dev
+```
+
+```bash
+# For a Python/Django project
+python manage.py runserver 0.0.0.0:8000
+```
+
+```bash
+# For a Ruby on Rails project
+bundle exec rails server -b 0.0.0.0
+```
+
+<Tip>
+  The Web Preview server runs within the same sandbox environment as your other
+  agent tasks, meaning it has access to the same file system (including any
+  changes made by the agent) and the [Environment
+  Variables](./environment-variables).
+</Tip>
+
+<Note>
+  The web preview is intended for development and debugging purposes. The server
+  is typically only accessible while the agent run is active or for a short
+  period afterward, and it's not designed for public hosting.
+</Note>