Quickstart

Create your first ToolSet and execute a tool in minutes

Get started with Jinba Toolbox by creating an organization, building a ToolSet, writing a tool, and executing it in a sandbox environment.

What You’ll Build

A simple ToolSet containing a tool that:

1. Accepts a text input
2. Processes it in an isolated sandbox
3. Returns structured output

Prerequisites

• A Jinba Toolbox account (Sign up here)
• No local setup required — everything runs in the cloud

Steps

1. Sign up and create an Organization

   Go to toolbox.jinba.io and sign in to your account.

   After signing in, create a new Organization. An Organization is the ownership unit for all your ToolSets and team members.

   1. Click “Create Organization” in the dashboard
   2. Enter a name and slug (e.g., my-team)
   3. Click “Create”

   Your organization slug will be used in API URLs and MCP endpoints.

2. Create a ToolSet

   A ToolSet is a collection of related tools with a shared execution environment — similar to an npm package or a Docker image.

   1. Navigate to your organization dashboard
   2. Click “New ToolSet”
   3. Fill in the details:
      • Name: e.g., text-utils
      • Description: e.g., “Text processing utilities”
      • Language: Choose TypeScript or Python
      • Sandbox Provider: Select E2B or Daytona
      • Visibility: Private (default) or Public
   4. Click “Create ToolSet”
3. Write your first Tool

   A Tool is an individual executable unit inside a ToolSet. Each tool has an input schema, output schema, and code.

   1. Open your newly created ToolSet
   2. Click “Add Tool”
   3. Configure the tool:
      • Name: word-count
      • Description: “Counts words in a given text”
   4. Define the input schema:

   {
     "type": "object",
     "properties": {
       "text": {
         "type": "string",
         "description": "The text to count words in"
       }
     },
     "required": ["text"]
   }
   

   5. Define the output schema:

   {
     "type": "object",
     "properties": {
       "wordCount": {
         "type": "number",
         "description": "Number of words in the text"
       }
     },
     "required": ["wordCount"]
   }
   

   6. Write the tool code (TypeScript):

   export default async function run(input: { text: string }) {
     const words = input.text.trim().split(/\s+/).filter(Boolean);
     return { wordCount: words.length };
   }
   

   7. Click “Save”
4. Test the Tool

   Before publishing, test your tool to make sure it works correctly.

   1. Click the “Test” button on the tool detail page
   2. Enter a sample input:

   {
     "text": "Hello world from Jinba Toolbox"
   }
   

   3. Click “Run Test”
   4. Verify the output:

   {
     "wordCount": 5
   }
   

   The tool runs inside an isolated sandbox container. You can inspect stdout, stderr, and execution duration in the run details.

5. Publish a Version

   Once testing is successful, publish an immutable version of your ToolSet.

   1. Go to the Versions tab in your ToolSet
   2. Click “Publish Version”
   3. Enter a semver version number (e.g., 1.0.0)
   4. Click “Publish”

   Published versions are immutable snapshots. Any future changes require publishing a new version.

6. Execute via API or MCP

   Now your tool is ready to be called programmatically.

   Using the REST API:

   curl -X POST https://toolbox-api.jinba.dev/v1/orgs/{orgId}/toolsets/text-utils/tools/word-count/run \
     -H "Authorization: Bearer jtb_your_api_key" \
     -H "Content-Type: application/json" \
     -d '{"text": "Hello world from Jinba Toolbox"}'
   

   Using the TypeScript SDK:

   import { createClient } from "@jinba-toolbox/sdk";
   
   const client = createClient({
     apiKey: process.env.JINBA_TR_API_KEY,
   });
   
   const result = await client.run("text-utils", "word-count", {
     text: "Hello world from Jinba Toolbox",
   });
   
   console.log(result.output); // { wordCount: 5 }
   

   Using the MCP endpoint (for AI agents):

   Your ToolSet is also available as an MCP server at:

   POST /v1/public/{orgSlug}/{toolsetSlug}/mcp
   

   AI agents that support the Model Context Protocol can call your tools directly.

What’s Next?

Core Concepts

Understand the domain model and key terminology

Web Console

Explore the full web console for managing your tools

API Reference

Browse the complete REST API documentation

SDK Guide

Integrate Jinba Toolbox into your applications