Sessions
To connect to a Sandbox you need to create a session.
const sandbox = await sdk.sandboxes.create()
const session = await sandbox.createSession({ id: 'some-session-ref' })
// When connecting on your server you can configure
// the session directly when connecting
const client = await sandbox.connect({ id: 'some-session-ref' })
You can create a session without passing an argument. This will create a session bound to a user called pitcher-host
. This user has write access to any API. We refer to this session as the "global" session.
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.
User Sessions
You should use user sessions for your users. This ensures privacy and isolation between users. You can configure a user session to have specific permissions, git access, tokens to securily access private hosts and even environment variables.
Permissions
By default a user has write
access, but you can configure a user session to have read
access.
// Now configure a user session that only has read access to the sandbox
const sandbox = await sdk.sandboxes.create()
const session = sandbox.createSession({
id: 'anonymous',
permission: 'read'
})
Git
Passing git details allows the user to use git commands inside the sandbox.
const sandbox = await sdk.sandboxes.create()
const session = await sandbox.createSession({
id: 'some-user-reference',
git: {
email: '[email protected]', // Required
name: 'Foo Bar', // Optional, defaults to session id
// Optional credentials
accessToken: '...',
provider: 'github.com',
username: 'my-provider-username' // Optional, defaults to x-access-token
}
})
It is highly recommended that Sandboxes where git credentials are used, are not exposed to the public. Even though we store the token in the isolated ~/.private
folder, there are still some security concerns if the Sandbox is public or shared between multiple user sessions.
Environment variables
If you pass environment variables, these variables will be available to the user inside the commands and terminals that they run in the Sandbox.
const sandbox = await sdk.sandboxes.create()
const session = await sandbox.createSession({
id: 'anonymous',
env: {
FOO: 'bar'
}
})
Host Tokens
Passing a host token to the session will sign all url generation from the client APIs.
const sandbox = await sdk.sandboxes.create()
const hostToken = await sdk.hosts.createToken()
const session = await sandbox.createSession({
id: 'some-user-reference',
hostToken
})
Storage
Every session will have the same filesystem as the global session. This means that if one user creates a file inside the workspace folder (or even the home folder), other users will be able to see it with one exception. The ~/.private
folder will be private for each session. No other session (including the global session) will be able to read or write to files inside this folder.
The ~/.private
folder will not be persisted between restarts of the sandbox. This means that files inside this folder will disappear between restarts.