Skip to main content

​
Overview

Organizations are the top-level container for all your RunTools resources. Everything — sandboxes, agents, tools, secrets, API keys, SSH keys — belongs to an organization. When you sign up, you’re prompted to create an organization. All users must belong to at least one organization.

​
How Organizations Work

RunTools uses WorkOS AuthKit for authentication and organization management. This means:
  • SSO support out of the box (Google, GitHub, SAML, OIDC)
  • Organization creation happens during onboarding
  • Member management via the WorkOS-powered dashboard
  • Role-based access via WorkOS roles

​
Members and Roles

View and manage team members on the Team page in the dashboard (Dashboard > Organization > Team).
RoleDescription
AdminFull access to all resources and settings
MemberCreate and manage sandboxes, agents, tools
Member management (invites, role changes, removals) is handled through the dashboard Team page, which reads directly from WorkOS.

​
Projects

Projects are UI grouping within an organization for keeping resources tidy. They don’t affect permissions — all resources are org-scoped.

​
How Projects Work

  • Every org has a default project (created automatically)
  • Create additional projects from the dashboard sidebar
  • Assign sandboxes, agents, API keys, and SSH keys to projects
  • Switch between projects in the sidebar to filter resources
  • Projects are for organization only — permissions are always org-level

​
Managing Projects

From the dashboard:
  • Click New Project in the sidebar to create a project
  • Go to Project Settings to rename, change color, or delete a project
  • Use the Resource Assigner (drag-and-drop) to bulk-assign resources to projects

​
API Keys

API keys authenticate programmatic access to the RunTools API. They are org-scoped.

​
Creating API Keys

Go to Dashboard > Credentials > API Keys, or use the CLI: 
# Create via dashboard (recommended)
# Dashboard > Credentials > API Keys > Create New Key

# Or via API (the CLI doesn't have apikey commands yet)
# POST /v1/api-keys with Bearer token

​
Key Format

PrefixEnvironment
rt_live_Production
rt_test_Testing

​
Scopes

ScopeAccess
*Full access (default)
sandbox:*All sandbox operations
agent:*All agent operations
template:*Template management
ssh-key:*SSH key management
billing:*Billing access
API keys are shown only once when created. Store them securely. Never commit keys to version control.

​
SSH Keys

SSH keys enable secure access to sandboxes. Register a key once, and it’s available for all sandboxes in your org. 
# Add your SSH key
runtools ssh-key add ~/.ssh/id_ed25519.pub

# Or from the dashboard: Credentials > SSH Keys

# Then SSH into any sandbox
ssh sandbox-xxx@ssh.runtools.ai
SSH keys are org-scoped — all members can use registered keys to access sandboxes.

​
Secrets

Centralized secrets management for provider API keys, tool credentials, and custom secrets. 
# Store secrets via CLI
runtools secret set ANTHROPIC_API_KEY sk-ant-xxx --category provider
runtools secret set GITHUB_TOKEN ghp_xxx --category tool

# Or via dashboard: Credentials > Tool & Provider Keys
Secrets are:
  • Encrypted at rest with AES-256-GCM
  • Never exposed in API responses (only metadata, never values)
  • Auditable — reveal operations are logged
  • Org-scoped — shared across all projects
See Secrets for more details.

​
Authentication Methods

RunTools supports two authentication methods:

​
1. WorkOS Session (Dashboard & CLI)

When you log in via the dashboard or runtools login, you get a WorkOS JWT that includes your user ID and organization. The CLI uses device flow authentication (opens browser, polls for completion).

​
2. API Key (SDK & Programmatic)

For programmatic access, use an API key: 
import { RunTools } from '@runtools/sdk';

const rt = new RunTools({ apiKey: 'rt_live_xxx' });
Or set the environment variable: 
export RUNTOOLS_API_KEY=rt_live_xxx

​
Best Practices

Group related sandboxes, agents, and tools into projects. This keeps your dashboard clean as you scale.
Create keys with only the permissions needed. Don’t use full-access keys in production services.
Use the secrets system for API keys and tokens instead of hardcoding them. Secrets are encrypted at rest and auditable.
Each team member should register their SSH key. This enables passwordless SSH access to all sandboxes.