Skip to main content

​
Overview

Organizations are the top-level container for all your RunTools resources. Everything — sandboxes, agents, tools, secrets, API keys — belongs to an organization.
On Free and Pro plans, you have one organization. Team and Enterprise plans support multiple organizations.

​
Creating Organizations

// Create a new organization
const org = await rt.organizations.create({
  name: 'Acme Corp',
  slug: 'acme-corp',  // Used in URLs
});

// Switch to the new organization
rt.setOrganization('acme-corp');

​
Managing Members

​
Inviting Members

// Invite a team member
await rt.organizations.invite({
  email: '[email protected]',
  role: 'developer',
});

// Invite multiple
await rt.organizations.inviteMany([
  { email: '[email protected]', role: 'developer' },
  { email: '[email protected]', role: 'admin' },
]);

// List pending invites
const invites = await rt.organizations.invites();

​
Roles

RolePermissions
OwnerFull access. Billing, delete org, transfer ownership.
AdminManage members, API keys, settings. Cannot delete org.
DeveloperCreate/manage sandboxes, agents, tools. Cannot manage members.
ViewerRead-only access to resources and logs.

​
Managing Members

// List members
const members = await rt.organizations.members();

// Change role
await rt.organizations.updateMember('user_123', {
  role: 'admin',
});

// Remove member
await rt.organizations.removeMember('user_123');

// Transfer ownership
await rt.organizations.transferOwnership('user_456');

​
Organization Settings

// Get organization settings
const settings = await rt.organizations.settings();

// Update settings
await rt.organizations.updateSettings({
  name: 'Acme Corporation',
  defaultTemplate: 'nodejs-20',
  allowPublicSandboxes: false,
  requireMfa: true,
});

​
API Key Management

API keys are scoped to organizations: 
// Create API key
const key = await rt.apiKeys.create({
  name: 'Production',
  scopes: ['sandboxes', 'agents', 'tools'],
  expiresIn: '90d',
});

console.log(key.key);  // rt_live_xxx... (only shown once!)

// List API keys
const keys = await rt.apiKeys.list();

// Revoke key
await rt.apiKeys.revoke('key_123');

// Rotate key (create new, revoke old)
const newKey = await rt.apiKeys.rotate('key_123');

​
API Key Scopes

ScopeAccess
*Full access (default)
sandboxesCreate, read, update, delete sandboxes
sandboxes:readRead-only sandbox access
agentsCreate and run agents
agents:readRead-only agent access
toolsInstall and execute tools
templatesManage templates
executeCode execution API only

​
Projects

Organize resources within an organization using projects: 
// Create project
const project = await rt.projects.create({
  name: 'Customer Portal',
  slug: 'customer-portal',
});

// Create sandbox in project
const sandbox = await rt.sandboxes.create({
  template: 'nodejs-20',
  project: 'customer-portal',
});

// List project sandboxes
const sandboxes = await rt.sandboxes.list({
  project: 'customer-portal',
});

​
SSO / SAML (Enterprise)

Enterprise organizations can configure SSO: 
// Configure SAML SSO
await rt.organizations.configureSso({
  provider: 'saml',
  entryPoint: 'https://idp.acme.com/sso/saml',
  issuer: 'https://runtools.ai',
  cert: '-----BEGIN CERTIFICATE-----...',
});

// Or use OIDC
await rt.organizations.configureSso({
  provider: 'oidc',
  issuerUrl: 'https://auth.acme.com',
  clientId: 'runtools',
  clientSecret: process.env.OIDC_SECRET,
});

​
Switching Organizations

// List your organizations
const orgs = await rt.organizations.list();

// Switch active organization
rt.setOrganization('other-org');

// Or create client for specific org
const otherClient = new RunTools({
  apiKey: process.env.RUNTOOLS_API_KEY,
  organization: 'other-org',
});

​
Deleting Organizations

Deleting an organization permanently removes all resources including sandboxes, agents, tools, and data. This cannot be undone.
// Delete organization (owner only)
await rt.organizations.delete({
  confirm: 'acme-corp',  // Must type org slug to confirm
});

​
Best Practices

Group related resources into projects. Makes it easier to manage permissions and costs.
Create new keys and phase out old ones periodically. Use the rotate command for seamless transitions.
Don’t use full-access keys in production. Create keys with only the permissions needed.
Require multi-factor authentication for admin and owner roles.
Check audit logs regularly for unexpected activity (Team and Enterprise plans).