Core Concepts

Essential terminology and domain model for understanding Jinba Toolbox

Understanding these core concepts will help you use Jinba Toolbox effectively and navigate the platform with confidence.

Key Terms

Term	Definition	Example
Organization	Team or company that owns ToolSets. Users belong to one or more Organizations with roles (owner, admin, member).	acme-corp — a team sharing a collection of AI tools
ToolSet	Collection of related tools with a shared execution environment. Equivalent to an npm package or Docker image. Belongs to an Organization.	slack-tools — a set of Slack integration tools
Tool	Individual executable unit within a ToolSet. Has input/output schemas and code written in TypeScript or Python.	post-message — sends a message to a Slack channel
Run	A single execution record of a Tool. Stores input, output, logs, status, and duration.	Executing post-message with channel and text parameters
Version	Immutable snapshot of a ToolSet at a point in time. Uses semantic versioning (semver).	1.2.0 — a published release of slack-tools
Sandbox	Isolated container environment where tool code executes. Prevents unsafe operations from affecting the host system.	An E2B container running a Python tool

Domain Relationships

The entities in Jinba Toolbox are organized in a clear hierarchy:

Organization
  └── ToolSet
        ├── Tool (1:N)
        ├── Version (1:N)
        └── Run (1:N)

• An Organization contains one or more ToolSets.
• A ToolSet contains one or more Tools, and can have multiple published Versions.
• Each Run records a single execution of a Tool within a ToolSet.
• Users belong to Organizations through memberships with assigned roles.

Entity Relationship Diagram

┌──────────┐
│   User   │
└────┬─────┘
     │
     ├─────1:N─────┐
     │              │
     │         ┌────┴─────┐
     │         │  ApiKey   │
     │         └──────────┘
     │
     └─────N:M─────┐
                    │
        ┌───────────┴───────────┐
        │  OrganizationMember   │  (role: owner / admin / member)
        └───────────┬───────────┘
                    │
        ┌───────────┴───────────┐
        │     Organization      │
        └───────────┬───────────┘
                    │
                   1:N
                    │
        ┌───────────┴───────────┐
        │       ToolSet         │
        └───────────┬───────────┘
                    │
         ┌──────────┼──────────┐
         │          │          │
        1:N        1:N        1:N
         │          │          │
    ┌────┴────┐ ┌───┴───┐ ┌───┴──────┐
    │  Tool   │ │  Run  │ │ Version  │
    └─────────┘ └───────┘ └──────────┘

Organizations

An Organization is the top-level ownership unit. All ToolSets, API keys, and billing belong to an Organization.

• Users can be members of multiple Organizations.
• Each membership has a role: owner, admin, or member.
• API keys are scoped to an Organization and carry permission scopes: read, write, execute, and admin.

ToolSets

A ToolSet groups related tools together with a shared sandbox configuration. Key properties include:

Property	Description
Slug	URL-friendly identifier, unique within the Organization
Sandbox Config	Defines the execution environment: provider (E2B or Daytona), language (TypeScript or Python), packages, and resource limits
Visibility	Controls access: private (organization only), public (anyone), or restricted (specific organizations)
Tags	Searchable labels for discovery in the explore catalog

Tools

A Tool is the smallest executable unit. Each Tool defines:

Property	Description
Slug	URL-friendly identifier, unique within the ToolSet
Input Schema	JSON Schema that validates the input before execution
Output Schema	JSON Schema that describes the expected output structure
Code	The executable source code (TypeScript or Python)
Entrypoint	Optional custom entrypoint function name

Input and output schemas are validated automatically. If the input does not match the schema, the execution is rejected before any sandbox resources are consumed.

Versions

Versions are immutable snapshots of a ToolSet. Once published, a Version cannot be modified.

• Versions follow semantic versioning (e.g., 1.0.0, 1.2.3).
• Publishing a Version captures all Tools, schemas, and code at that point in time.
• The latestVersion field on a ToolSet always points to the most recently published Version.
• AI agents and external consumers should pin to a specific Version for stability.

Runs

A Run represents a single tool execution and records everything about it:

Field	Description
Status	pending, running, success, failed, or timeout
Input	The validated input parameters
Output	The structured result returned by the tool
Logs	Captured stdout and stderr from the sandbox
Duration	Execution time in milliseconds
Error	Error details if the Run failed

Runs provide full observability into tool execution, making it easy to debug failures and monitor performance.

Sandbox Execution

Every tool runs inside an isolated sandbox container. The sandbox system is built on a pluggable provider architecture:

Provider	Description
E2B	Cloud-based sandboxes with fast startup and broad language support
Daytona	Self-hosted sandbox option for teams requiring on-premises execution

The sandbox provider is configured at the ToolSet level. All Tools in a ToolSet share the same sandbox configuration, including language runtime, installed packages, and resource limits.

Access Control

Jinba Toolbox provides multiple layers of access control:

• Organization membership governs who can manage ToolSets and view Runs.
• ToolSet visibility (private, public, restricted) controls who can discover and execute tools.
• API key scopes (read, write, execute, admin) provide fine-grained permission control for programmatic access.

What’s Next?

Quickstart

Build your first ToolSet and run a tool

Web Console

Explore the web interface for managing tools