Organizations & Teams

Everything in Runtools belongs to an organization — sandboxes, agents, tools, secrets, API keys, SSH keys, projects, and workspaces all live under one. People sign in to the dashboard and CLI through WorkOS sessions; code authenticates with API keys minted inside the org.

Members And Roles

The dashboard Team page is the primary member-management surface.

Role	Access
Admin	Organization settings, broader org views, shared resources, and publishing
Member	Own and use resources allowed by organization policy

Admin-only API options include broader views such as --all-org, org-shared secret writes, and publishing tools or agents to organization or public visibility.

Projects

Projects organize resources inside an organization. They are a filtering and grouping layer; permissions remain organization/member based. Project APIs are available under:

https://api.runtools.ai/v1/projects

Common project-owned or project-filtered resources include agents, sandboxes, API keys, and SSH keys.

Workspaces

Workspaces are persistent storage spaces owned by the organization.

curl https://api.runtools.ai/v1/workspaces \
  -H "X-API-Key: $RUNTOOLS_API_KEY"

Organization workspaces can be mounted into sandboxes and used as persistent filesystem memory for agents attached to those sandboxes:

await rt.sandbox.create({
  template: 'base-ubuntu',
  mounts: [
    {
      workspaceId: '9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e',
      path: '/workspace',
    },
  ],
});

Personal workspaces are owner/admin scoped and cannot be mounted into sandboxes.

API Keys

Create API keys from the dashboard or CLI:

runtools auth keys list
runtools auth keys create "production-api" --scope "*"
runtools auth keys revoke <key-id>
runtools auth keys rotate <key-id> --name "rotated-production-api"

Use keys with the SDK:

import { RunTools } from '@runtools-ai/sdk';

const rt = new RunTools({
  apiKey: process.env.RUNTOOLS_API_KEY,
});

Common scopes include:

Scope	Access
`*`	Full API key access
`sandbox:*`	Sandbox lifecycle and execution
`agent:*`	Agent management and runs
`agent:run`	Run agents
`tool:*`	Tool Hub management and execution
`files:*`	Workspace file access
`ssh-key:*`	SSH key management

API key values are shown once. Store them in a secret manager and rotate keys after team or deployment changes.

SSH Keys

runtools ssh-key list
runtools ssh-key add personal-laptop --file ~/.ssh/id_ed25519.pub
runtools ssh-key set-default <id>

SSH keys can be user-private or org-wide depending on the flags used when adding them.

Secrets

runtools secret set ANTHROPIC_API_KEY "sk-ant-xxx" --category provider
runtools secret set SHARED_CRM_KEY "crm_xxx" --category tool --org-wide
runtools secret list --org-only

Secrets are user-private by default. Org-shared secrets require the appropriate admin policy. See Secrets & Credentials for API and SDK examples.

OAuth Connections

Connected Apps are scoped to the authenticated user and organization context.

runtools oauth connect github
runtools oauth status
runtools oauth set-default <connection-id>

Tool Hub uses connected apps during server-side credential resolution when a tool declares an OAuth provider.

Best Practices

Use projects for navigation, not isolation

Create narrow API keys

Use scopes that match the integration. CI jobs often need fewer scopes than an operator key.

Separate user-private and org-shared secrets

Use org-wide secrets only for credentials meant to be shared by the team.

Use all-org flags deliberately

--all-org surfaces are intended for admins doing organization-level review or support.

Getting Started

Platform

Core Features

Advanced

Organizations & Teams

Members And Roles

Projects

Workspaces

API Keys

SSH Keys

Secrets

OAuth Connections

Best Practices

​Members And Roles

​Projects

​Workspaces

​API Keys

​SSH Keys

​Secrets

​OAuth Connections

​Best Practices

Members And Roles

Projects

Workspaces

API Keys

SSH Keys

Secrets

OAuth Connections

Best Practices