Users
When connecting to a Sandbox you will be using the default global user. If your individual Sandboxes are used by a single user, you should use the global user.
const sandbox = await sdk.sandboxes.create({
id: 'some-template-id'
})
const client = await sandbox.connect()
Or when creating a session to use in browser/node clients:
const sandbox = await sdk.sandboxes.create({
id: 'some-template-id'
})
const session = await sandbox.createSession()
Configure Git
const sandbox = await sdk.sandboxes.create({
id: 'some-template-id'
})
// Or with createSession
const client = await sandbox.connect({
git: {
email: '[email protected]',
name: 'Foo Bar',
// Optional credentials
accessToken: '...',
provider: 'github.com',
username: 'my-provider-username' // Optional, defaults to x-access-token
}
})
Configure Env
These variables will be available to the user inside the commands and terminals that are run in the Sandbox.
const sandbox = await sdk.sandboxes.create({
id: 'some-template-id'
})
// Or with createSession
const client = await sandbox.connect({
env: {
FOO: 'bar'
}
})
Multiple Users
If your Sandbox can be accessed by multiple users you should connect or create sessions with an id
. This ensures privacy and isolation between users.
const sandbox = await sdk.sandboxes.create({
id: 'some-template-id'
})
const client = await sandbox.connect({
id: 'some-user-reference'
})
Or create a session to use in browser/node:
const sandbox = await sdk.sandboxes.create({
id: 'some-template-id'
})
const session = await sandbox.createSession({
id: 'some-user-reference'
})
When you run whoami
, it will say that you are root
. That's because we run every session inside a Docker container where you are root
. However the container itself is started as the user of your session.
Host Tokens
Passing a host token to the session will sign all url generation from the client APIs.
const sandbox = await sdk.sandboxes.create({
id: 'some-template-id'
})
const hostToken = await sdk.hosts.createToken()
const session = await sandbox.createSession({
hostToken
})
// Or if connecting on the server
const client = await sandbox.connect({
hostToken
})
⚡ Best practices
- Prefer global user - If the Sandbox will only have a single user, use the default global user
- Use consistent user identifiers - Any custom user should use a stable and meaningful ID (e.g., username, user ID)
- Privacy - Do not write git/env configuration to public Sandboxes or the global user if multiple users has access to Sandbox