SDK
Host Privacy

Host Privacy

CodeSandbox SDK supports different privacy levels for sandboxes and their hosts. Understanding these privacy levels helps you control access to your sandbox environments.

Privacy Levels

  • public - Sandbox and its hosts are publicly accessible to anyone
  • unlisted ⚠️ (deprecated) - Use public or public-hosts instead
  • private - Sandbox is private and hosts require authentication via host tokens
  • public-hosts - Sandbox is private but hosts are publicly accessible without tokens

Private Sandboxes with Host Tokens

If a sandbox has private privacy, its hosts won't be accessible unless a host token is provided.

You can obtain a host token by calling sdk.hosts.createToken. This token will by default never expire. It is recommended to persist this token and provide it in dedicated Sandbox sessions.

Public Hosts for Private Sandboxes

The new public-hosts privacy setting allows you to create private sandboxes where the hosts (preview URLs) remain publicly accessible. This is useful when you want:

  • Private sandbox content and source code
  • Public preview URLs for sharing demos or prototypes
  • No authentication required for accessing the running application
const sandbox = await sdk.sandboxes.create({
  privacy: 'public-hosts', // Private sandbox with public hosts
  // ... other options
});
 
// Hosts are accessible without tokens
const previewUrl = `https://${sandbox.id}-3000.csb.app`;

You create signed urls to your Sandboxes using the hosts API on the server:

const hostToken = await sdk.hosts.createToken('sandbox-id')

This gives you low level management of your Sandboxes hosts. But you can also pass the host token to a session. This is especially useful if you want to generate urls based on the state of the Sandbox, generating them in browser sessions etc.

const sandbox = await sdk.sandboxes.create()
const hostToken = await sdk.hosts.createToken(sandbox.id)
const session = await sandbox.createSession({
  id: 'some-user-reference',
  hostToken
})
💡

When you open a signed URL in the browser, we will automatically put the preview token in a cookie so subsequent requests from the same browser don't require the token.

Token expiration

You can set an expiration on the preview token when creating it:

const hostToken = await sdk.hosts.createToken('sandbox-id', {
  expiresAt: new Date(Date.now() + 60 * 60 * 1000) // 1 hour
})

This is useful if you want to limit the lifetime of a host token. For example when a user shared a preview of their app with someone who should only have access for a limited time.

Managing Host Tokens (CLI)

The CLI allows you to manage host tokens of a sandbox. You can use it to list, revoke and update host tokens.

List:

$ csb sandbox host-tokens :sandbox-id list
 ID                           PREFIX        LAST USED   EXPIRES
 prv_Hca52PUyFHVJsGkciXXbEq   prv_v1_8uKY   Never       Never
 prv_HbE8wC6veXWwcazFYrdUfy   prv_v1__ki7   Never       Never
 prv_MWMhMjbQiY3jSagfaG6D7R   prv_v1_i7iI   Never       Never

Revoke:

$ csb sandbox host-tokens :sandbox-id revoke prv_Hca52PUyFHVJsGkciXXbEq

If you want to revoke all host tokens for a sandbox, you can do so with:

$ csb sandbox host-tokens :sandbox-id revoke --all

Update:

Extend or shorten the expiration time of a host token:

$ csb sandbox host-tokens :sandbox-id update prv_Hca52PUyFHVJsGkciXXbEq --expires-at 2025-03-01
PersistencePreview API Access