Quickstart

Install the SDK, authenticate, and run your first connect → tools → execute flow.

Install

npm install @protoboxai/sdk now resolves to 2.x, which is what these docs describe. The 1.x line still on the registry is an older and completely different API — the modules and auth model below do not exist on it, so pin ^2.0.0 if anything in your tree might drag in the old major.

npm install @protoboxai/sdk

Authenticate

Create a client with your workspace API key. The key identifies your workspace; your end-users are identified separately by a userId you choose.

import { ProtoboxSDK } from '@protoboxai/sdk';

const protobox = new ProtoboxSDK({
  apiKey: process.env.PROTOBOX_API_KEY!,   // required
  // baseUrl defaults to https://platform.protobox.ai
});

1 · Browse the catalog

const { items } = await protobox.integrations.list();
console.log(items.map((i) => i.id)); // ['github', 'gmail', ...]

const actions = await protobox.integrations.actions('github');
console.log(actions.map((a) => a.name)); // ['github.create_issue', ...]

2 · Connect an end-user

Scope to one of your users with protobox.entity(userId), then start a managed OAuth flow. You get back an authorizeUrl — redirect the user's browser there. Protobox hosts the callback and stores their credential.

const user = protobox.entity('user_123');

const { authorizeUrl } = await user.connect('github');
// redirect the user to authorizeUrl, then wait for them to finish:
await user.waitUntilActive('github'); // polls until the connection is active

GitHub App integrations use await user.install('github') (returns installUrl). API-key integrations (no OAuth) use protobox.connections.connectApiKey({ integrationId, apiKey }) at the workspace level.

3 · Execute a tool

Directly:

const result = await user.execute({
  name: 'github.create_issue',
  arguments: { repo: 'octocat/hello', title: 'Hello from Protobox' },
});

if (result.authRequired) {
  // the user hasn't connected this integration yet — send them back to connect()
} else if (result.success) {
  console.log(result.data);
}

4 · …or hand the tools to an LLM

import Anthropic from '@anthropic-ai/sdk';
const anthropic = new Anthropic();

const gh = user.forLLM('anthropic', { integrationId: 'github' });
const tools = await gh.tools();

const message = await anthropic.messages.create({
  model: 'claude-sonnet-5',
  max_tokens: 1024,
  tools,
  messages: [{ role: 'user', content: 'Open an issue titled "Ship it" on octocat/hello' }],
});

const toolResults = await gh.run(message.content); // runs server-side with the user's creds
// append { role: 'user', content: toolResults } and continue the loop

See Framework adapters for the OpenAI and Vercel AI SDK equivalents, and Managed auth for the full connection lifecycle.

Getting access

@protoboxai/sdk 2.x is public on npm — the install above works as written. You need a Protobox workspace and an API key to use it; create both at app.protobox.ai.

Search