Skip to Content
Perstack 0.0.1 is released 🎉
Get StartedInstallation

Installation

Choose between the CLI for immediate use or the SDK for integrating into your applications.

Prerequisites

Before installing Perstack, ensure you have:

  • Node.js 22+ installed
  • One of the following API keys set as environment variables:
    • ANTHROPIC_API_KEY for Claude models
    • GOOGLE_GENERATIVE_AI_API_KEY for Gemini models
    • OPENAI_API_KEY for OpenAI models
# Example: Set your API key
export ANTHROPIC_API_KEY="your-api-key-here"

CLI

Running with npx

The fastest way to try Perstack is using npx, which runs the CLI without installation.

npx perstack run <expertKey> <query>

Example:

# Run a deep research expert
npx perstack run @perstack/deep-research \
  "Research the latest advances in quantum computing"
 
# Run an integration expert
npx perstack run @perstack/integrator \
  "Build a React component that displays weather data"

Installing the CLI Globally

For frequent use, install Perstack globally:

npm install -g perstack

After installation, you can run:

perstack run <expertKey> <query>

SDK

For programmatic access and integration into your applications, use the Perstack runtime SDK.

Install the Runtime

npm install @perstack/runtime

Basic Usage

Create a simple script to run an expert:

import { run } from "@perstack/runtime";
 
// Run an expert with minimal configuration
const result = await run({
  setting: {
    expertKey: "@perstack/deep-research",
    input: {
      text: "Research about Perstack and generate comprehensive tutorial",
    },
  },
});
 
// Access the result
const lastMessage = result.messages[result.messages.length - 1];
if (lastMessage.type === "expertMessage") {
  const contents = lastMessage.contents;
  for (const content of contents) {
    if (content.type === "textPart") {
      console.log("Result:", content.text);
    }
  }
}

Model Configuration

Perstack requires the following environment variables to access the model:

  • ANTHROPIC_API_KEY - API key for Claude models
  • GOOGLE_GENERATIVE_AI_API_KEY - API key for Gemini models
  • OPENAI_API_KEY - API key for OpenAI models

Changing the Model

You can change the model one of three ways:

  1. perstack.toml:
[model]
name = "gemini-2.5-pro-preview-05-06"
  1. CLI:
# Run an expert with a specific model
npx perstack run @perstack/deep-research \
  "Research the latest advances in quantum computing" \
  --model gemini-2.5-pro-preview-05-06
  1. SDK:
// Run an expert with a specific model
const result = await run({
  setting: {
    expertKey: "@perstack/deep-research",
    input: {
      text: "Research about Perstack and generate comprehensive tutorial",
    },
    model: "gemini-2.5-pro-preview-05-06",
  },
});

Next Steps

IntroductionTutorial