SDK
Users

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