v2.0.1

🚀 Features

• The template builder now outputs more help to understand template ids and aliases. It also generates a Sandbox from the generated template with a link to the CSB editor for verification

🐛 Bug fixes

• The keepActiveWhileConnected method now properly sets its state based on the boolean passed. It also handles explicit and implicit reconnects, keeping the behavior of last set state (Thanks @wylieconlon for identifying and PR)

v2.0.0

🏗️ Infra

• The Sandbox Agent now detects nested repos and properly persists them when archiving the Sandbox (Requires restart of Sandbox for latest Sandbox Agent)
• Fixed a race condition where Sandbox Agent was throwing a false error. Typically happened during template building
• We should now send a proper error response from the API, so no more Internal Server Error
• We have a new internal debug dashboard which allows to more easily debug VM ids across the stack
• We have a new status page https://status2.codesandbox.io/. Currently it only displays health of API, but we are adding clusters and other infra related health checks ASAP
• Fixed an issue with scheduling from our Universal Template

🚨 Breaking

• The git namespace has been removed from the Sandbox Client. The reason is that it makes an assumption being used at the root workspace, but you might have a nested git folder. Additionally we have discovered conflicts with the legacy CodeSandbox product git persistence. That means we can not officially support workspace root cloning of repos yet. This will later be supported, but until then please clone repos into nested folders of the workspace
• You now have to pass expireAt when creating host tokens. Since tokens does not expire by default, this can result in a lot of unintentional active tokens. We wanted to make sure you make a conscious choice about the behavior you want here
• The server side SDK and the browser side SDK is now decoupled. Now Node has a much smaller dependency graph and will by default be compatible with edge environments. This did result in certain methods, like commands.getAll and terminals.getAll to become async
• The concept of "sources" is removed. To clone a repository you now create a Sandbox as normal and then use commands to clone a repository. This is partially related to the complexity of managing git credentials, but also setting a path to give your more lower level programmatic tools as opposed to high level declarative and constrained options

Finding the correct terminology is always difficult, but we will keep iterating until we get it right:

// This is still considered a Sandbox and represents methods for interacting
// with the Sandbox VM. (type: Sandbox)
const sandbox = await sdk.sandboxes.resume('some-id')

// A session is explicitly creating a session (type: SandboxSession)
const session = await sandbox.createSession()

// There are now 3 ways of creating a CLIENT (type: SandboxClient):

// 1. Browser
import { connectToSandbox } from '@codesandbox/sdk/browser'
const client = await connectToSandbox(...)

// 2. Other Node environment
import { connectToSandbox } from '@codesandbox/sdk/node'
const client = await connectToSandbox(...)

// 3. Or connect in the same environment as the SDK
const sandbox = await sdk.sandboxes.resume('some-id')
// "Connect" creates both session and client for convenience
const client = await sandbox.connect(...)

⚠️ Deprecations

• createBrowserSession is renamed to createSession as you can now connect to the Sandbox from both browser and node clients separate from your server and the SDK
• sdk.sandboxes.fork is deprecated because it introduces yet another term to creating Sandboxes. Use create with an id to create a Sandbox

🚀 Features

• The template builder now uses a new API endpoint which selects 3 clusters to schedule the template to. This removes some logic from the SDK and gets us closer to better scheduling management
• The SDK now gives sentry error reports to help us debug any issues related to API calls. We'll extend this soon to interactions with the Sandbox as well
• The CLI now has --vm-tier to indicate the tier to use when creating Sandboxes from the template and --vm-build-tier for the tier to use for building the template
• The CLI will now dump logs if errors occurs during setup. Use --log-path parameter to configure where to dump the logs
• You can now import connectToSandbox from @codesandbox/sdk/node to connect to a Sandbox from other Node environment separate from your server where SDK is used, like react-native
• @codesandbox/pitcher-protocol is now removed as dependency and the types are moved to the SDK. Removing license dependency as well. @codesandbox/pitcher-client is still bundled into the browser client, but this will shortly be removed as well
• When using an env option in the session we now write a ~/.private/.env file which is sourced on all terminals and commands created. This ensures we do not pass any private data from your server to clients connecting to the Sandbox
• We are now passing the SDK version on the UserAgent of API requests, improving our ability to debug any issues
• You can now pass --alias when building your template to point an alias to the generated template id. The alias is in the format of namespace@tag , where it will by default use the template folder as namespace or you can explicitly pass the full alias

npx @codesandbox/sdk build ./my-template --alias latest
my-template@latest now points to the generated template id

• You can now use git with credentials. You still assign these credentials to sandbox.connect({ id, git }) or sandbox.createSession({ id, git ), but there are some additional options. ⚠️ You have to use the latest version of our Sandbox Agent for this to work. Make sure to update your templates etc.
• When building a template where one Sandbox fails you can now manually verify the Sandbox before continuing to create snapshots and template id
  
• A new CLI flag called --ci can be sent to prevent the interactive fallback from firing and exit as an error
• The CLI can now run without a command, which opens up a starting point for our interactive CLI. Currently it allows you to open a Sandbox, see its running status and change it (See image below)

🐛 Fixes

• Fixed issues with special characters in environment variables
• Fixed issues with running commands with special characters
• Now throwing errors on unsupported characters in session ids
• Now command errors does not include podman specific entries
• Browser connection now works properly
• Fixed issue with writing git credentials
• Our Dashboard search now properly searches ids etc. If you have a lot of Sandboxes it will still be slow, but there will be a new Dashboard coming in the future
• There was a race condition with commands where we try to name it after it has been discarded
• The --alias param in the CLI had an issue with parsing
• Due to a typo there was a misunderstanding on the special private folder for user sessions. The folder name is ~/.private, NOT ~/private. This is now properly used for handling git and env variables
• All requests from SDK now has 2min timeout, like the rest of our request flow in the API and infra
• When using a Together.ai Api Key it is now properly handled by the CLI
• Restarting a Sandbox now has a retry mechanism in case of race conditions
• When building templates we now have a 2 min timeout, instead of 30 sec, on starting Sandboxes. This is what the rest of the flow in our infra is configured to. There are edge cases where starting a Sandbox can take more than 30 sec
• Certain processes exposing ports are not assigned to the related task. This has been fixed, given that you configure the port on your task in tasks.json

v2.0.0-rc.11

📝 DOCS

You can find the 2.0.0 RC docs at: https://projects-docs-3ubl8mut7-codesandbox1.vercel.app/docs/sdk

⚠️ These changes are additional to the previous rc.10 release!

🏗️ Infra

• The Sandbox Agent now detects nested repos and properly persists them when archiving the Sandbox (Requires restart of Sandbox for latest Sandbox Agent)

🚨 Breaking

• The git namespace has been removed from the Sandbox Client. The reason is that it makes an assumption being used at the root workspace, but you might have a nested git folder. Additionally we have discovered conflicts with the legacy CodeSandbox product git persistence. That means we can not officially support workspace root cloning of repos yet. This will later be supported, but until then please clone repos into nested folders of the workspace.

🐛 Fixes

• Fixed issues with special characters in environment variables
• Fixed issues with running commands with special characters
• Now throwing errors on unsupported characters in session ids
• Now command errors does not include podman specific entries
• Browser connection now works properly
• Sentry is now only used in the CLI, as the dependency causes too many challenges with building for different runtime environments in user world
• Fixed issue with writing git credentials

v2.0.0-rc.10

📝 DOCS

You can find the 2.0.0 RC docs at: https://fsnpxp-3000.csb.app/sdk

⚠️ These changes are additional to the previous rc.9 release!

🔥 Hot resizing incident

So we identified an issue with what we call "hot resizing sandboxes". This was experienced as VMs not hibernating and also not being able to get them back up. The reason this happened is because Sandboxes where being hot resized below their parent Sandbox tier. Basically the Sandbox goes out of memory.

We have measures in place for both the SDK and our API. The SDK now has:

csb build . --vm-tier=Micro --vm-build-tier=Medium

• The vm-tier represents the tier given to Sandboxes created from the template
• The vm-build-tier represents the tier used when building the template
• There is no risk of "hot downsizing" the Universal Template to a bad state anymore

Shortly the API will also give an error if you try to create a Sandbox with a Tier that causes a "hot downsize" from its parent.

💰 Compensation 💰 We are running a job to identify customers affected by this for automatic compensation, but please reach out to us if this compensation has not been applied by end of next week 🙏

🏗️ Infra

• Fixed a race condition where Sandbox Agent was throwing a false error. Typically happened during template building
• We should now send a proper error response from the API, so no more Internal Server Error
• We have a new debug dashboard which allows to more easily debug VM ids across the stack
• We have a new status page https://status2.codesandbox.io/. Currently it only displays health of API, but we are adding clusters and other infra related health checks ASAP

🚨 Breaking

• You now have to pass expireAt when creating host tokens. We noticed nobody really persists host tokens, but rather creates new ones for every session. Since tokens does not expire by default, this results in a lot of active tokens. We wanted to make sure you make a conscious choice about the behavior you want here

⚠️ Deprecations

• git.checkout now has a deprecated isBranch second argument in favor of the new git.createBranch method

🚀 Features

• git.createBranch to create a branch. git.checkout is explicitly used for checking out any reference
• The template builder now uses a new API endpoint which selects 3 clusters to schedule the template to. This removes some logic from the SDK and gets us closer to better scheduling management
• The SDK now gives sentry error reports to help us debug any issues related to API calls. We'll extend this soon to interactions with the Sandbox as well
• The CLI now has --vm-tier to indicate the tier to use when creating Sandboxes from the template and --vm-build-tier for the tier to use for building the template
• The CLI will now dump logs if errors occurs during setup. Use --log-path parameter to configure where to dump the logs

🐛 Fixes

• Our Dashboard search now properly searches ids etc. If you have a lot of Sandboxes it will still be slow, but there will be a new Dashboard coming in the future
• There was a race condition with commands where we try to name it after it has been discarded
• The --alias param in the CLI had an issue with parsing

v2.0.0-rc.9

📝 DOCS

You can find the 2.0.0 RC docs at: https://fsnpxp-3000.csb.app/sdk

⚠️ These changes are additional to the previous rc.8 release!

🏗️ Infra

• Fixed an issue with scheduling from our Universal Template

🚨 Breaking (typing)

Finding the correct terminology is always difficult, but we will keep iterating until we get it right:

// This is still considered a Sandbox and represents methods for interacting
// with the Sandbox VM. (type: Sandbox)
const sandbox = await sdk.sandboxes.resume('some-id')

// A session is explicitly creating a session (type: SandboxSession)
const session = await sandbox.createSession()

// There are now 3 ways of creating a CLIENT (type: SandboxClient):

// 1. Browser
import { connectToSandbox } from '@codesandbox/sdk/browser'
const client = await connectToSandbox(...)

// 2. Other Node environment
import { connectToSandbox } from '@codesandbox/sdk/node'
const client = await connectToSandbox(...)

// 3. Or connect in the same environment as the SDK
const sandbox = await sdk.sandboxes.resume('some-id')
// "Connect" creates both session and client for convenience
const client = await sandbox.connect(...)

⚠️ Deprecations

• createBrowserSession is renamed to createSession as you can now connect to the Sandbox from both browser and node clients separate from your server and the SDK
• sdk.sandboxes.fork is deprecated because it introduces yet another term to creating Sandboxes. Use create with an id to create a Sandbox

🚀 Features

• You can now import connectToSandbox from @codesandbox/sdk/node to connect to a Sandbox from other Node environment separate from your server where SDK is used, like react-native
• @codesandbox/pitcher-protocol is now removed as dependency and the types are moved to the SDK. Removing license dependency as well. @codesandbox/pitcher-client is still bundled into the browser client, but this will shortly be removed as well
• When using an env option in the session we now write a ~/.private/.env file which is sourced on all terminals and commands created. This ensures we do not pass any private data from your server to clients connecting to the Sandbox
• We are now passing the SDK version on the UserAgent of API requests, improving our ability to debug any issues

🐛 Fixes

• ws dependency is now replaced with isomorphic-ws to support Node-ish environments
• Due to a typo there was a misunderstanding on the special private folder for user sessions. The folder name is ~/.private, NOT ~/private. This is now properly used for handling git and env variables
• All requests from SDK now has 2min timeout, like the rest of our request flow in the API and infra
• When using a Together.ai Api Key it is now properly handled by the CLI

v2.0.0-rc.8

📝 DOCS

You can find the 2.0.0 RC docs at: https://fsnpxp-3000.csb.app/sdk

🚨 Breaking

• The server side SDK and the browser side SDK is now decoupled. Now Node has a much smaller dependency graph and will by default be compatible with edge environments. This did result in certain methods, like commands.getAll and terminals.getAll to become async
• The concept of "sources" is removed. To clone a repository you now create a Sandbox as normal and then use session.git.clone to clone a repository. This is partially related to the complexity of managing git credentials, but also setting a path to give your more lower level programmatic tools as opposed to high level declarative and constrained options

🚀 Features

• You can now pass --alias when building your template to point an alias to the generated template id. The alias is in the format of namespace@tag , where it will by default use the template folder as namespace or you can explicitly pass the full alias

npx @codesandbox/sdk build ./my-template --alias latest
my-template@latest now points to the generated template id

• You can now use git with credentials. You still assign these credentials to sandbox.connect({ id, git }) or sandbox.createBrowserSession({ id, git ), but there are some additional options. ⚠️ You have to use the latest version of our Sandbox Agent for this to work. Make sure to update your templates etc.
• When building a template where one Sandbox fails you can now manually verify the Sandbox before continuing to create snapshots and template id
  
• A new CLI flag called --ci can be sent to prevent the interactive fallback from firing and rather give you a template id, but showing the Sandbox that errored
• The CLI can now run without a command, which opens up a starting point for our interactive CLI. Currently it allows you to open a Sandbox, see its running status and change it (See image below)

🐛 Fixes

• Restarting a Sandbox now has a retry mechanism in case of race conditions
• When building templates we now have a 2 min timeout, instead of 30 sec, on starting Sandboxes. This is what the rest of the flow in our infra is configured to. There are edge cases where starting a Sandbox can take more than 30 sec and the "Bad Gateway" error should be gone
• Certain processes exposing ports are not assigned to the related task. This has been fixed, given that you configure the port on your task in tasks.json

v0.12.0

0.12.0 (2025-04-24)

Features

• add property to check if VM is up to date (a44c842)
• Rest client (ec8f5eb)

v0.11.2

0.11.2 (2025-04-15)

Bug Fixes

• build: consider port opened for faulty status codes (#84) (c5a2469)

v0.11.1

0.11.1 (2025-03-13)

Bug Fixes

• support keepActiveWhileConnected for browser sessions (#81) (ca1f825)

v0.11.0

0.11.0 (2025-03-11)

Features

• add support for configuring auto-wake behaviour (#79) (8c2ef89)