Create and Run Your First Jinba Toolbox ToolSet

Get started with Jinba Toolbox by opening your 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:

Accepts a text input
Processes it in an isolated sandbox
Returns structured output

Prerequisites

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

Steps

Go to toolbox.jinba.io and sign in to your account.After signing in, the dashboard lists Your Organizations. An Organization is the ownership unit for all your ToolSets and team members. Organizations and their members are managed in JinbaAuth, not in the Toolbox console — an organization appears here once you have been invited to it.

Click the organization you want to work in
You land on its Tool Sets page

The organization ID (visible in the URL as /org/{orgId}/...) is what you use in API URLs and MCP endpoints.

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.

Navigate to Tool Sets in the organization sidebar
Click “New Tool Set”
Fill in the details:
- Name: e.g., Text Utils (the Slug, e.g. text-utils, is generated from the name and can be edited)
- Description: e.g., “Text processing utilities”
- Visibility: Private (default) or Public
- Provider: E2B
- Language: Choose Python or TypeScript
- Timeout (seconds): optional, default 900 (max 3600)
Click “Create Tool Set”

Write your first Tool

A Tool is an individual executable unit inside a ToolSet. Each tool has an input schema, output schema, and code. The schemas are not entered separately — they are extracted from the input and output definitions in your code every time you save.

Open your newly created ToolSet
Click “Add Tool”
Configure the tool:
- Name: Word Count (the Slug word-count is generated from the name)
- Description: “Counts words in a given text”
Click “Create Tool” — the tool editor opens
Replace the starter template with the tool code (TypeScript):

import { z } from "zod";

export const input = z.object({
  text: z.string().describe("The text to count words in"),
});

export const output = z.object({
  wordCount: z.number().describe("Number of words in the text"),
});

export async function run(data: z.infer<typeof input>) {
  const words = data.text.trim().split(/\s+/).filter(Boolean);
  return { wordCount: words.length };
}

Click “Save” (or press Cmd/Ctrl + S). The input and output JSON Schemas are generated from the Zod definitions on save.

Test the Tool

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

In the test panel at the bottom of the editor, open the Input tab and enter a sample input:

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

Click “Run” (or press Cmd/Ctrl + Enter)
The panel switches to the Output tab. Verify the output:

{
  "wordCount": 5
}

The tool runs inside an isolated sandbox container. Test runs are recorded in the organization’s Runs page (with version test), where you can inspect stdout, stderr, and execution duration.

Publish a Version

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

Go to the Versions tab in your ToolSet
Click “New Version” (or “Publish” in the ToolSet header)
Enter a semver version number (e.g., 1.0.0; the console suggests the next patch version) and optional release notes
Click “Publish”

Published versions are immutable snapshots, and the new version immediately becomes the active version for the selected environment. Any future changes require publishing a new version.

Execute via API or MCP

Now your tool is ready to be called programmatically.First create an API key under API Keys in the organization sidebar.Using the REST API (the input goes under an input key):

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

Using the TypeScript SDK:

import { createClient } from "@jinba-toolbox/sdk";

const client = createClient({
  baseUrl: "https://toolbox-api.jinba.io",
  apiKey: process.env.JINBA_TB_API_KEY!,
  organizationId: "your-org-id",
});

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):Turn on the MCP switch in the ToolSet header. Your ToolSet is then available as an MCP server at:

POST /v1/orgs/{orgId}/toolsets/{toolsetSlug}/mcp

(Public ToolSets can also be reached at POST /v1/public/{orgId}/{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

​What You’ll Build

​Prerequisites

​Steps

​What’s Next?