Skip to content

Commit 4a6a64a

Browse files
jayhackjayhack
authored
docs: sandbox docs 1.0 (#1091)
Co-authored-by: jayhack <2548876+jayhack@users.noreply.github.com>
1 parent 5e32ac0 commit 4a6a64a

File tree

11 files changed

+230
-5
lines changed

11 files changed

+230
-5
lines changed

‎docs/docs.json‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"$schema": "https://mintlify.com/docs.json",
3-
"theme": "mint",
3+
"theme": "maple",
44
"name": "Codegen",
55
"colors": {
66
"primary": "#a277ff",
@@ -32,9 +32,18 @@
3232
"integrations/linear",
3333
"integrations/github",
3434
"integrations/web-search",
35-
"integrations/sandboxes",
3635
"integrations/postgres"
3736
]
37+
},
38+
{
39+
"group": "Sandboxes",
40+
"pages": [
41+
"sandboxes/overview",
42+
"sandboxes/setup-commands",
43+
"sandboxes/editor",
44+
"sandboxes/environment-variables",
45+
"sandboxes/web-preview"
46+
]
3847
}
3948
]
4049
},

‎docs/images/sandbox-buttons.png‎

17.3 KB
Loading

‎docs/images/setup-commands-ui.png‎

411 KB
Loading

‎docs/images/slack.png‎

171 KB
Loading

‎docs/integrations/linear.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "Linear Integration"
33
sidebarTitle: "Linear"
4-
icon: "pencil"
4+
icon: "book"
55
---
66

77
Integrate Codegen with your Linear workspace to allow agents to interact with issues, manage projects, and keep your team updated.

‎docs/integrations/slack.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ sidebarTitle: "Slack"
44
icon: "slack"
55
---
66

7+
<img src="/images/slack.png" />
8+
79
Connect Codegen to your Slack workspace to enable seamless communication between agents and your team.
810

911
## Capabilities & Functions

‎docs/sandboxes/editor.mdx‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
title: "Remote Editor (VSCode)"
3+
sidebarTitle: "Editor"
4+
icon: "pencil"
5+
---
6+
7+
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.
8+
9+
## Accessing the Editor
10+
11+
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.
12+
13+
<Frame caption="Access the Remote Editor from the Codegen UI (example)">
14+
<img src="/images/sandbox-buttons.png" alt="Remote VSCode Editor" />
15+
</Frame>
16+
17+
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.
18+
19+
## Capabilities
20+
21+
The Remote Editor offers several key benefits:
22+
23+
- **Run Arbitrary Commands:** Open a terminal directly within VSCode to execute any shell commands in the sandbox. This is useful for:
24+
- Manually running tests.
25+
- Inspecting file contents.
26+
- Trying out different commands or scripts.
27+
- Installing additional temporary tools or dependencies.
28+
- **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.
29+
- **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.
30+
- **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.
31+
32+
## How it Works
33+
34+
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).
35+
36+
<Tip>
37+
The Remote Editor is an excellent tool for gaining deeper insights into an
38+
agent's operations and for situations where you need to interact more directly
39+
with the sandbox environment than through standard agent commands.
40+
</Tip>
41+
42+
<Note>
43+
Like other sandbox features, the editor session is tied to the lifecycle of
44+
the sandbox. Changes made might be ephemeral if the sandbox is reset or a new
45+
snapshot is used for subsequent runs, unless those changes are committed back
46+
through the agent or other means.
47+
</Note>{" "}

‎docs/sandboxes/environment-variables.mdx‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: "Environment Variables"
3+
sidebarTitle: "Env Variables"
4+
icon: "code"
5+
---
6+
7+
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.
8+
9+
## Standard Environment Variables
10+
11+
The following environment variables are typically available within Codegen sandboxes:
12+
13+
| Variable | Default Value | Description |
14+
| --------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
15+
| `NVM_DIR` | _Dynamic_ | Specifies the directory where Node Version Manager (NVM) is installed. The exact path is set during sandbox initialization. |
16+
| `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). |
17+
| `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. |
18+
| `NODE_VERSION` | _Dynamic (current NVM Node version)_ | Indicates the version of Node.js that is currently active in the sandbox, as managed by NVM. |
19+
| `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. |
20+
| `DEBIAN_FRONTEND` | `"noninteractive"` | Instructs Debian-based package managers (like `apt`) to run without interactive prompts. |
21+
| `PYTHONUNBUFFERED` | `"1"` | Forces `stdout` and `stderr` for Python to be unbuffered, meaning output is written immediately. |
22+
| `COREPACK_ENABLE_DOWNLOAD_PROMPT` | `"0"` | Disables the Corepack prompt when it needs to download a package manager (like Yarn or pnpm). |
23+
| `PYTHONPATH` | `"/usr/local/lib/python3.13/site-packages"` | Adds the specified directory to Python's module search path. (Python version may vary). |
24+
| `IS_SANDBOX` | `"true"` | A boolean flag indicating the environment is a Codegen sandbox. |
25+
| `NPM_CONFIG_YES` | `"true"` | Configures npm to automatically answer "yes" to prompts. |
26+
| `PIP_NO_INPUT` | `"1"` | Instructs pip (Python's package installer) to operate in non-interactive mode. |
27+
| `YARN_ENABLE_IMMUTABLE_INSTALLS` | `"false"` | Disables Yarn's "immutable installs" feature, allowing `yarn install` to modify the lockfile. |
28+
29+
<Note>
30+
The values for variables like `NVM_DIR`, `PATH`, `NVM_BIN`, and `NODE_VERSION`
31+
are typically set dynamically during the sandbox setup process, depending on
32+
the specific NVM and Node.js versions being used. The `PYTHONPATH` may also
33+
vary based on the Python installation within the sandbox.
34+
</Note>

docs/integrations/sandboxes.mdx renamed to docs/sandboxes/overview.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: "Code Execution Sandboxes"
3-
sidebarTitle: "Sandboxes"
3+
sidebarTitle: "Overview"
44
icon: "box"
55
---
66

@@ -31,4 +31,4 @@ Sandboxes are typically configured per-agent run or defined within your Codegen
3131
<Note>
3232
Sandboxes are ephemeral; their state is not typically persisted between agent
3333
runs unless specifically configured for caching or stateful operations.
34-
</Note>
34+
</Note>{" "}

‎docs/sandboxes/setup-commands.mdx‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
title: "Setup Commands"
3+
sidebarTitle: "Setup Commands"
4+
icon: "terminal"
5+
---
6+
7+
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.
8+
9+
<Tip>
10+
The most common use cases for setup commands is installing dependencies, e.g.
11+
`npm install`
12+
</Tip>
13+
14+
## Accessing Setup Commands
15+
16+
To configure setup commands for a repository:
17+
18+
1. Navigate to [codegen.com/repos](https://codegen.com/repos).
19+
2. Click on the desired repository from the list.
20+
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).
21+
22+
<Frame caption="Set setup commands at codegen.com/repos">
23+
<img src="/images/setup-commands-ui.png" alt="Setup Commands UI" />
24+
</Frame>
25+
26+
## How it Works
27+
28+
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.
29+
30+
For example, you might want to:
31+
32+
- Switch to a specific Node.js version.
33+
- Install project dependencies.
34+
- Run any necessary build steps or pre-compilation tasks.
35+
36+
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.
37+
38+
## Common Examples
39+
40+
Here are a few common use cases for setup commands:
41+
42+
```bash
43+
# Switch to Node.js version 20
44+
nvm use 20
45+
46+
# Install npm dependencies
47+
npm install
48+
```
49+
50+
```bash
51+
# Install Python dependencies
52+
pip install -r requirements.txt
53+
```
54+
55+
```bash
56+
# Or a combination of commands
57+
nvm use 18
58+
npm ci
59+
npm run build
60+
```
61+
62+
<Note>
63+
Ensure your setup commands are non-interactive and can run to completion
64+
without user input.
65+
</Note>
66+
<Tip>
67+
The environment variables listed in the "Env Variables" section are available
68+
during the execution of these setup commands.
69+
</Tip>

0 commit comments

Comments
 (0)