Skip to content

Commit 5e9cf3a

Browse files
filipelima18danilowozCompuIveschristianalfoninecoline
authored
add SDK docs (#273)
* Create sdk page * basic structure * updates * lots of context * update * add download support * Updates from Christian * small fixes * small url fix * update links * fix faq --------- Co-authored-by: Danilo Woznica <danilowoz@gmail.com> Co-authored-by: Ives van Hoorne <Ives.v.h@gmail.com> Co-authored-by: Christian Alfoni <christianalfoni@gmail.com> Co-authored-by: Necoline <necoline@codesandbox.io>
1 parent 04f1cf2 commit 5e9cf3a

31 files changed

+1726
-30
lines changed

‎packages/projects-docs/next-env.d.ts

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
/// <reference types="next" />
2+
/// <reference types="next/image-types/global" />
3+
4+
// NOTE: This file should not be edited
5+
// see https://nextjs.org/docs/basic-features/typescript for more information.

‎packages/projects-docs/package.json

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,10 @@
2424
},
2525
"devDependencies": {
2626
"autoprefixer": "^10.4.16",
27+
"markdown-table": "^3.0.4",
2728
"postcss": "^8.4.31",
28-
"tailwindcss": "^3.3.5"
29+
"tailwindcss": "^3.3.5",
30+
"typescript": "5.7.2"
2931
},
3032
"prettier": {
3133
"embeddedLanguageFormatting": "off",

‎packages/projects-docs/pages/_meta.json

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,20 @@
11
{
22
"learn": {
3-
"title": "Documentation",
3+
"title": "Editor",
4+
"type": "page"
5+
},
6+
"sdk": {
7+
"title": "SDK",
48
"type": "page"
59
},
610
"tutorial": {
711
"title": "Tutorial",
8-
"type": "page"
12+
"type": "page",
13+
"display": "hidden"
914
},
1015
"faq": {
1116
"title": "FAQ",
12-
"type": "page"
17+
"type": "page",
18+
"display": "hidden"
1319
}
1420
}

‎packages/projects-docs/pages/learn/_meta.json

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@
22
"index": "Introduction",
33
"guides": "Getting Started",
44
"editors": "Editors",
5+
"sdk": {
6+
"title": "SDK",
7+
"href": "/sdk/"
8+
},
59
"-- cloud-development": {
610
"type": "separator",
711
"title": "Cloud Development"
@@ -29,5 +33,13 @@
2933
"title": "More"
3034
},
3135
"ci": "CodeSandbox CI",
32-
"explore": "Discover Page"
36+
"explore": "Discover Page",
37+
"tutorials": {
38+
"title": "Tutorials",
39+
"href": "/tutorial/getting-started-with-dev-containers"
40+
},
41+
"faq": {
42+
"title": "FAQ",
43+
"href": "/faq"
44+
}
3345
}

‎packages/projects-docs/pages/learn/access/organizations.mdx

Lines changed: 9 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -17,48 +17,42 @@ Additionally, organizations make it possible to connect all the employees at a c
1717

1818
## Creating an organization
1919

20-
You can create an organization from any active workspace that is not already part of an organzation.
21-
In the _Workspace settings_, open the [Organization tab](https://codesandbox.io/t/org) and enter a name for the organization.
22-
20+
You can create an organization from any active workspace that is not already part of an organzation.
21+
In the _Workspace settings_, open the [Organization tab](https://codesandbox.io/t/org) and enter a name for the organization.
2322

2423
![create org](../images/org-create.png)
2524

2625
To prevent confusion, we recommend that you name your organization so it directly relates to your business’ name.
2726

28-
29-
![name org](../images/org-name.png)
27+
![name organization](../images/org-name.png)
3028

3129
Once you have created an organization, it will automatically be linked to the workspace you created it from. However, you can choose to add additional existing workspaces to that organization.
32-
You can also manage the organization admins.
30+
You can also manage the organization admins.
3331

34-
35-
![edit org](../images/org-edit.png)
32+
![edit org](../images/org-edit.png)
3633

3734
The [Organization settings](https://codesandbox.io/t/org) will always be discoverable through the _Workspace settings_.
3835

3936
## Setting an email domain
4037

41-
In the _Organizations settings_, open the `Domain` tab and add your email domain.
42-
The domain must be verified before being approved. This is an automated process that requires no action from you.
43-
38+
In the _Organizations settings_, open the `Domain` tab and add your email domain.
39+
The domain must be verified before being approved. This is an automated process that requires no action from you.
4440

4541
![add domain](../images/org-domain-add.png)
4642

4743
Once the domain is approved, users who have CodeSandbox accounts connected to emails with a matching domain will be given the option to join the workspace.
48-
Users may encounter the suggestion to join an eligible workspace when they are attempting to access projects in the workspace or when they log into CodeSandbox for the first time after the email domain has been approved.
44+
Users may encounter the suggestion to join an eligible workspace when they are attempting to access projects in the workspace or when they log into CodeSandbox for the first time after the email domain has been approved.
4945

5046
Below is an example of the message a user with a matching email domain will see when opening a private Sandbox from a workspace they are not yet part of.
5147

52-
5348
![join ws](../images/org-domain-join-ws.png)
5449

55-
5650
## Accounts and domains
51+
5752
CodeSandbox accounts are tied to individual users. They grant access to shared workspaces and organizations, enabling collaboration with other CodeSandbox users.
5853

5954
With a single CodeSandbox account, users can create or join multiple workspaces and organizations to collaborate with various groups of CodeSandbox users; these workspaces and organizations are separate entities, each with a unique set of members and projects.
6055

6156
Since each workspace and organization are their own separate entities, members cannot see the other workspaces or organizations a user belongs to.
6257

63-
6458
![graph](../images/org-account-graph.png)

‎packages/projects-docs/pages/learn/devboxes/upload.mdx

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,7 @@ You can check your current Sandbox storage usage from your [Dashboard](https://c
3232

3333
For Devboxes and repositories, the limits are:
3434

35-
- 20 GB total storage per Devbox or repository branch for workspaces on a Free plan.
36-
- 50 GB total storage per Devbox or repository branch for workspaces on a Pro plan.
35+
- 20 GB total storage per Devbox or repository branch for all workspaces.
3736

3837
You can check your Devbox storage usage by clicking the CodeSandbox icon at the top left of the editor and then "Virtual machine". This will open a new DevTool displaying the current VM usage, including storage.
3938

‎packages/projects-docs/pages/learn/environment/vm.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ VM resources consist of vCPU, RAM and storage. The vCPU and RAM specs are groupe
2222
| Subscription | Storage |
2323
| ------------ | ------- |
2424
| Free | 20 GB |
25-
| Pro | 50 GB |
25+
| Pro | 20 GB |
2626

2727
If you require storage that goes beyond our Pro plan defaults, please select 'Pro Subscriptions' on our support form and [get in touch](https://codesandbox.io/support). Our team can adjust your limits to suit your project.
2828

‎packages/projects-docs/pages/sdk/_meta.json

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
{
2+
"index": "Introduction",
3+
"use-cases": "Use Cases",
4+
"pricing": "Pricing",
5+
"contact": {
6+
"title": "Contact Us",
7+
"href": "https://codesandbox.io/support#form",
8+
"newWindow": true
9+
},
10+
11+
"-- api-reference": {
12+
"type": "separator",
13+
"title": "API Reference"
14+
},
15+
"sandboxes": "Sandboxes",
16+
"filesystem": "File System",
17+
"shells": "Shells",
18+
"ports": "Ports & Previews",
19+
"tasks": "Tasks & Setup",
20+
"specs": "VM Specs",
21+
22+
"-- resources": {
23+
"type": "separator",
24+
"title": "Resources"
25+
},
26+
"snapshot-library": "Snapshot Library",
27+
"snapshot-builder": "Snapshot Builder",
28+
"environment": "Environment",
29+
"docker": "Docker & Docker Compose",
30+
"persistence": "Persistence",
31+
"fork": "Fork",
32+
"faq": "FAQ"
33+
}

‎packages/projects-docs/pages/sdk/docker.mdx

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
---
2+
title: Docker & Dev Containers
3+
description: Learn how to configure your sandbox environment using Dev Containers.
4+
---
5+
6+
import { Callout } from 'nextra-theme-docs'
7+
8+
# Dev Containers
9+
10+
CodeSandbox natively supports the [Dev Containers specification](https://containers.dev/), allowing you to customize your sandbox, install system-level dependencies, and run additional services.
11+
12+
## Configuration
13+
14+
To configure your sandbox environment, create a `.devcontainer/devcontainer.json` file inside the root of the sandbox:
15+
16+
```json
17+
{
18+
"name": "Node.js",
19+
"image": "mcr.microsoft.com/devcontainers/javascript-node:18",
20+
"features": {
21+
"ghcr.io/devcontainers/features/python:1": {}
22+
}
23+
}
24+
```
25+
26+
In this example, we're installing Node v18 as base, with Python on top using Dev Container Features.
27+
28+
Alternatively, you can use a `Dockerfile` to build the Docker image when the sandbox boots:
29+
30+
```json
31+
{
32+
"name": "Node.js",
33+
"build": {
34+
"dockerfile": "./Dockerfile"
35+
}
36+
}
37+
```
38+
39+
### Using Dev Containers in the SDK
40+
41+
When creating a sandbox, all shells will automatically run inside the Docker container specified in the Dev Container configuration.
42+
43+
```ts
44+
const sandbox = await sdk.sandbox.create({
45+
template: "node" // Template with Dev Container configuration
46+
});
47+
48+
await sandbox.shells.run("node --version");
49+
```
50+
51+
Since we use memory snapshots, the Docker container will already be running when you run your shell.
52+
53+
## Docker Compose
54+
55+
You can run additional services using Docker Compose by adding a `docker-compose.yml` configuration to your Dev Container:
56+
57+
```json
58+
{
59+
"name": "Full Stack App",
60+
"dockerComposeFile": "docker-compose.yml",
61+
"service": "app",
62+
"workspaceFolder": "/workspace"
63+
}
64+
```
65+
66+
With a corresponding `docker-compose.yml`:
67+
68+
```yaml
69+
services:
70+
app:
71+
image: mcr.microsoft.com/devcontainers/javascript-node:18
72+
command: sleep infinity
73+
74+
db:
75+
image: postgres:14
76+
ports:
77+
- 5432:5432
78+
environment:
79+
POSTGRES_PASSWORD: password
80+
```
81+
82+
### Using Docker Compose in the SDK
83+
84+
The SDK will automatically start all services defined in your Docker Compose configuration:
85+
86+
```ts
87+
const sandbox = await sdk.sandbox.create({
88+
template: "fullstack" // Template with Dev Container configuration
89+
});
90+
91+
// Wait for all services to be ready
92+
await sandbox.setup.waitForFinish();
93+
94+
// You can now connect to the services
95+
const portInfo = await sandbox.ports.waitForPort(5432);
96+
console.log(`Database available at: ${portInfo.hostname}:${portInfo.port}`);
97+
```
98+
99+
## Examples
100+
101+
### Full-Stack Development Environment
102+
103+
Here's an example of setting up a full-stack development environment with Node.js and PostgreSQL:
104+
105+
```ts
106+
const sandbox = await sdk.sandbox.create({
107+
template: "fullstack"
108+
});
109+
110+
// Wait for environment setup
111+
const progress = await sandbox.setup.waitForFinish();
112+
if (progress.state !== "FINISHED") {
113+
throw new Error("Environment setup failed");
114+
}
115+
116+
// Start the development server
117+
const devTask = await sandbox.tasks.runTask("dev");
118+
119+
// Wait for both the app and database to be ready
120+
const [appPort, dbPort] = await Promise.all([
121+
sandbox.ports.waitForPort(3000),
122+
sandbox.ports.waitForPort(5432)
123+
]);
124+
125+
console.log(`
126+
App running at: ${appPort.getPreviewUrl()}
127+
Database available at: ${dbPort.hostname}:${dbPort.port}
128+
`);
129+
```
130+
131+
### Custom Environment with System Dependencies
132+
133+
Example of a sandbox that needs specific system packages:
134+
135+
```ts
136+
const sandbox = await sdk.sandbox.create({
137+
template: "custom-env"
138+
});
139+
140+
// The Dev Container will install required packages during setup
141+
await sandbox.setup.waitForFinish();
142+
143+
// Run a command that uses the installed packages
144+
const result = await sandbox.shells.run("ffmpeg -version");
145+
console.log(result.output);
146+
```
147+
148+
For more information about Dev Container configuration options and features, visit the [Dev Container specification](https://containers.dev/). Also, take a look at our [snapshot builder](/sdk/snapshot-builder.mdx) to learn how to create efficient snapshots with preloaded Docker images.

‎packages/projects-docs/pages/sdk/environment.mdx

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
title: Environment
3+
description: Learn how the CodeSandbox SDK's environment works.
4+
---
5+
6+
import { Callout } from 'nextra-theme-docs'
7+
8+
# Environment
9+
10+
Sandboxes on CodeSandbox are backed by a [Firecracker](https://firecracker-microvm.github.io/) microVM, within the VM we run a rootless Docker container based on a [Dev Container](https://containers.dev/) configuration (specified in the `.devcontainer/devcontainer.json` file).
11+
12+
## Booting a Sandbox
13+
14+
Whenever we boot a sandbox from scratch, we'll:
15+
16+
1. Start the Firecracker VM
17+
2. Create a default user (called `pitcher-host`)
18+
3. (optional) Build the Docker image specified in the `.devcontainer/devcontainer.json` file
19+
4. Start the Docker container
20+
5. Mount the `/project/sandbox` directory as a volume inside the Docker container
21+
22+
We run an agent inside the VM that the SDK connects to. Via an RPC protocol you can then interact with the sandbox.

‎packages/projects-docs/pages/sdk/faq.mdx

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: FAQs
3+
description: Find answers to common questions about the CodeSandbox SDK.
4+
---
5+
6+
import { Callout } from 'nextra-theme-docs'
7+
8+
# FAQ
9+
10+
## Do I need a CodeSandbox workspace to be able to use the SDK?
11+
12+
Yes. You need a CodeSandbox API key to use CodeSandbox SDK, which you can get by [creating a CodeSandbox account](https://codesandbox.io/signin).
13+
14+
## How can I revoke my API key?
15+
16+
To revoke an API key, go to the "Permissions" tab of your [Workspace Settings](https://codesandbox.io/t/permissions) and click the respective token under "API Access". Then, click "Remove Token" from the bottom of that modal.
17+
18+
## I have hit a rate limit - what should I do?
19+
20+
Please subscribe to a CodeSandbox plan that includes the most suitable rate limit for you. In case you're on our Builder plan already, please [contact us](https://webforms.pipedrive.com/f/72gS7iXoP8qjL8Ku9HZQcN5UKpUpZkgKRCjhbqREjCOYyBgzrCKCr7Mys5AyczOHBN) to discuss an Enterprise plan.
21+
22+
## Can I change the specs of the VMs?
23+
24+
Currently, we only allow changing the default specs for all VMs created with the SDK. You can change
25+
26+
We are also SOC 2 Type II compliant.
27+
28+
## Is it possible to self-host CodeSandbox SDK?
29+
30+
No, for now we don't provide a self-host option.
31+
32+
## Are there any SDK rate limits?
33+
34+
Yes. The SDK has rate limits on concurrent VMs, number of requests per hour, and number of sandboxes created per hour. These limits vary depending on the CodeSandbox plan, as explained on our [Pricing page](https://codesandbox.io/pricing).
35+
36+
## Can I use the same CodeSandbox plan for SDK and non-SDK usage?
37+
38+
Yes. Your CodeSandbox plan will allow you to use both, so you can leverage the SDK for programmatic sandbox creation, while still allowing your team to use CodeSandbox for their development.
39+
40+
## Does the CodeSandbox SDK use CodeSandbox Sandboxes or Devboxes?
41+
42+
While the SDK code only mentions "sandbox", the actual environments that it uses are officially called "Devboxes" (which use VMs). So, if you need more details about these VMs, please always refer to "[Devbox](/learn/devboxes/overview)" section of the CodeSandbox documentation and pricing.

0 commit comments

Comments
 (0)