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 anyoneunlisted
⚠️ (deprecated) - Usepublic
orpublic-hosts
insteadprivate
- Sandbox is private and hosts require authentication via host tokenspublic-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