Skip to content

updates #306

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions packages/projects-docs/pages/sdk/clients.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,10 @@ There are three different ways to connect to a Sandbox:
- **Node**: When you want to connect to a Sandbox from a Node client environment, for example React Native
- **Browser**: When you want to connect to a Sandbox from a browser client environment

<Callout>
The browser and node clients use the same unified implementation, providing consistent behavior across both environments.
</Callout>

## SDK

On your server, where you use the SDK, you can connect directly to a Sandbox:
Expand Down
25 changes: 23 additions & 2 deletions packages/projects-docs/pages/sdk/create-resume.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ const sandbox = await sdk.sandboxes.create();
```

<Callout>
By default Sandboxes are `unlisted` and can be accessed and forked by anyone with a url. If you want to create a private sandbox you can pass `privacy: 'private'`, which requires host tokens to access the exposed ports.
By default Sandboxes are `public` and can be accessed and forked by anyone with a url on CodeSandbox. Available privacy options are `private`, `public-hosts`, or `public`. Private sandboxes require host tokens to access exposed ports.
</Callout>

If no `id` option is provided to `sandbox.create()`, we'll create a sandbox forked from our [Universal](https://codesandbox.io/p/devbox/universal-pcz35m) template on CodeSandbox. You can also pass in a specific template id from [our collection of templates](/sdk/snapshot-library) or by creating your own template using our [Template Builder](/sdk/templates).
Expand All @@ -37,7 +37,7 @@ const sandbox = await sdk.sandboxes.create({
description: 'My sandbox',
tags: ['my-tag'],

// Public, unlisted or private
// Privacy options: 'private', 'public-hosts', or 'public'
privacy: 'private',

// Collection folder on Dashboard
Expand Down Expand Up @@ -67,6 +67,27 @@ const sandbox = await sdk.sandboxes.create({
The `automaticWakeupConfig` only wakes up the Sandbox, it does not extend its hibernation timeout.
</Callout>

## Get an Existing Sandbox

To get information about an existing sandbox without resuming it, use `sdk.sandboxes.get(id)`:

```ts
const sandbox = await sdk.sandboxes.get('sandbox-id');
```

This method retrieves sandbox metadata and status without waking up a hibernated sandbox.

## List Running Sandboxes

To get a list of all currently running sandboxes, use `sdk.sandboxes.listRunning()`:

```ts
const runningSandboxes = await sdk.sandboxes.listRunning();
console.log(runningSandboxes); // Array of sandbox objects
```

This method returns an array of sandbox objects that are currently active and running.

## Resume an Existing Sandbox

To resume an existing sandbox from hibernation and connect to it call: `sdk.sandboxes.resume(id)`:
Expand Down
2 changes: 1 addition & 1 deletion packages/projects-docs/pages/sdk/hosts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -22,5 +22,5 @@ console.log(url)
```

<Callout>
By default all Sandboxes are unlisted, but you need to use host tokens to access private Sandboxes. With public or unlisted Sandboxes the host tokens are not necessary, but you can still `getUrl` to generate a url for the relevant port.
By default all Sandboxes are public, but you need to use host tokens to access private Sandboxes. With public or public-hosts Sandboxes the host tokens are not necessary, but you can still `getUrl` to generate a url for the relevant port.
</Callout>
16 changes: 16 additions & 0 deletions packages/projects-docs/pages/sdk/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,22 @@ const output = await client.commands.run("echo 'Hello World'");
console.log(output) // Hello World
```

### OpenTelemetry Support

You can pass an OpenTelemetry tracer to the CodeSandbox constructor to enable tracing for all SDK operations:

```js
import { CodeSandbox } from "@codesandbox/sdk";
import { trace } from "@opentelemetry/api";

const tracer = trace.getTracer('my-app');
const sdk = new CodeSandbox(process.env.CSB_API_KEY, {
tracer
});
```

This will automatically trace all Sandboxes, Sandbox, and SandboxClient methods, including modules.

## How it works

The SDK can spin up a sandbox by cloning a template in under 3 seconds. Inside this VM you have a full development environment.
Expand Down
2 changes: 1 addition & 1 deletion packages/projects-docs/pages/sdk/templates.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ $ CSB_API_KEY=your-api-key npx @codesandbox/sdk build ./my-template --privacy pr
```

<Callout>
The template defaults to a `Micro` VM Tier for both building the template and when creating Sandboxes from it. You can not "downsize" Sandboxes when creating them from a template, so make sure you set the minimum tier you want here. It is recommended to make templates private, but they default to "unlisted". Use `build --help` for documentation on all parameters.
The template defaults to a `Micro` VM Tier for both building the template and when creating Sandboxes from it. You can not "downsize" Sandboxes when creating them from a template, so make sure you set the minimum tier you want here. It is recommended to make templates private, but they default to "public". Use `build --help` for documentation on all parameters.
</Callout>

This will start the process of creating Sandboxes for each of our clusters, write files, restart, wait for port 5173 to be available and then hibernate. This generates the snapshot that allows you to quickly create Sandboxes already running a dev server from the template.
Expand Down