Walkthrough

This walkthrough takes you from zero to production integration.

Prerequisites

• Docker
• An LLM provider API key (see Providers and Models)

Giving API keys

There are two ways to provide API keys:

1. Pass host environment variables with -e

Export the key on the host and forward it to the container:

export FIREWORKS_API_KEY=fw_...
docker run --rm -it \
  -e FIREWORKS_API_KEY \
  -v ./workspace:/workspace \
  perstack/perstack start my-expert "query" --provider fireworks

2. Store keys in a .env file in the workspace

Create a .env file in the workspace directory. Perstack loads .env and .env.local by default:

./workspace/.env

FIREWORKS_API_KEY=fw_...

docker run --rm -it \
  -v ./workspace:/workspace \
  perstack/perstack start my-expert "query"

You can also specify custom .env file paths with --env-path:

perstack start my-expert "query" --env-path .env.production

Create an expert

Use the built-in create-expert expert to scaffold your first agent:

# Use `create-expert` to scaffold a micro-agent team named `bash-gaming`
docker run --pull always --rm -it \
  --env-file .env \
  -v ./bash-gaming:/workspace \
  perstack/perstack start create-expert \
    --provider <provider> \
    --model <model> \
    "Form a team named bash-gaming. They build indie CLI games with both AI-facing non-interactive mode and human-facing TUI mode built on Ink + React. Their games must be runnable via npx at any time. Games are polished, well-tested with full playthroughs — TUI mode included."

create-expert is a built-in expert. It generates a perstack.toml by delegating to single-purpose micro-agents — plan, write, and verify — that iterate until the setup works. Each agent has a single responsibility and its own context window.

The result is a perstack.toml ready to use:

[experts."bash-gaming"]
description = "Game development team lead"
instruction = "Coordinate the team to build a CLI dungeon crawler."
delegates = ["@bash-gaming/plan", "@bash-gaming/build", "@bash-gaming/verify"]

[experts."@bash-gaming/plan"]
description = "Expands requirements into a comprehensive plan"
instruction = "Design game mechanics, architecture, and package structure."

[experts."@bash-gaming/build"]
description = "Implements the game"
instruction = "Write the game code using Ink + React, targeting terminal-based gameplay."

[experts."@bash-gaming/verify"]
description = "Tests the game and reports bugs"
instruction = "Play-test the game, find bugs, and verify fixes."

You can also write perstack.toml manually — create-expert is a convenient assistant, not a requirement.

Run your expert

Interactive mode

# Let `bash-gaming` build a Wizardry-like dungeon crawler
docker run --pull always --rm -it \
  --env-file .env \
  -v ./<result-dir>:/workspace \
  -v ./bash-gaming/perstack.toml:/definitions/perstack.toml:ro \
  perstack/perstack start bash-gaming \
    --config /definitions/perstack.toml \
    --provider <provider> \
    --model <model> \
    "Create a Wizardry-like dungeon crawler in a fixed 10-floor labyrinth with complex layouts, traps, fixed room encounters, and random battles. Include special-effect gear drops, leveling, and a skill tree for one playable character. Balance difficulty around build optimization. Death in the dungeon causes loss of one random equipped item."

perstack start opens a TUI for developing and testing experts. You get real-time feedback and can iterate on definitions without deploying anything.

Headless mode

docker run --pull always --rm \
  --env-file .env \
  -v ./<result-dir>:/workspace \
  -v ./bash-gaming/perstack.toml:/definitions/perstack.toml:ro \
  perstack/perstack run bash-gaming \
    --config /definitions/perstack.toml \
    --provider <provider> \
    --model <model> \
    "Create a Wizardry-like dungeon crawler in a fixed 10-floor labyrinth with complex layouts, traps, fixed room encounters, and random battles. Include special-effect gear drops, leveling, and a skill tree for one playable character. Balance difficulty around build optimization. Death in the dungeon causes loss of one random equipped item."

perstack run outputs JSON events to stdout — designed for automation and CI pipelines.

What just happened

Aspect	What Perstack does
State	All experts share the workspace (./workspace), not conversation history.
Collaboration	The coordinator (bash-gaming) delegates to specialists (@bash-gaming/plan, @bash-gaming/build, @bash-gaming/verify) autonomously.
Observability	Every step is visible as a structured JSON event.
Isolation	Each job runs in a sandboxed environment. Each expert has its own context window.

Analyze execution

After running an expert, inspect what happened:

npx perstack log

Or via Docker:

docker run --rm -it \
  -v ./bash-gaming:/workspace \
  perstack/perstack log

By default, this shows a summary of the latest job — the expert that ran, the steps it took, and any errors.

Key options for deeper inspection:

Option	Purpose
--errors	Show only error-related events
--tools	Show only tool call events
--step "5-10"	Filter by step range
--summary	Show summarized view
--json	Machine-readable output

Debugging agents across model changes, requirement changes, and prompt iterations requires visibility into every decision the agent made. perstack log gives you that without adding instrumentation code.

See CLI Reference for the full list of options.

Lock for reproducibility

docker run --rm -it \
  -v ./bash-gaming:/workspace \
  perstack/perstack install

This creates a perstack.lock file that caches tool schemas for all MCP skills. Without the lockfile, Perstack initializes MCP skills at runtime to discover their tool definitions — which can add 500ms–6s startup latency per skill.

Workflow:

1. Develop without a lockfile — MCP skills are resolved dynamically
2. Run perstack install before deploying — tool schemas are cached
3. Deploy with perstack.lock — the runtime starts LLM inference immediately

When to re-run: after adding or modifying skills in perstack.toml, or after updating MCP server dependencies.

The lockfile is optional. If not present, skills are initialized at runtime as usual.

Integrate into your application

The CLI is for prototyping. For production, integrate experts into your application via sandbox providers or runtime embedding.

Sandbox providers

Perstack’s isolation model maps naturally to container and serverless platforms:

• Docker
• AWS ECS
• Google Cloud Run
• Kubernetes
• Cloudflare Workers

Each expert runs in its own sandboxed environment. See Going to Production for the Docker setup pattern. Detailed guides for other providers are coming soon.

Runtime embedding (@perstack/runtime)

For tighter integration, embed the runtime directly in your TypeScript/JavaScript application:

import { run } from "@perstack/runtime"

const checkpoint = await run({
  setting: {
    providerConfig: { providerName: "fireworks" },
    expertKey: "my-expert",
    input: { text: "Start today's session" },
  },
})

You can also listen for events during execution:

import { run } from "@perstack/runtime"

const checkpoint = await run({
  setting: {
    providerConfig: { providerName: "fireworks" },
    expertKey: "my-expert",
    input: { text: "Start today's session" },
  },
  eventListener: (event) => {
    console.log(event.type, event)
  },
})

The CLI is for prototyping. The runtime API is for production. Both use the same perstack.toml.

What’s next

Build more:

• Skills — MCP tool integration and skill configuration
• Base Skill — built-in tools available to all experts
• Taming Prompt Sprawl — break monolithic prompts into collaborating experts

Understand the architecture:

• Concept — why isolation and observability matter
• Experts — best practices for expert design
• Sandbox Integration — infrastructure-level isolation

Reference:

• CLI Reference — all commands and options
• perstack.toml Reference — complete configuration spec
• Events — runtime event schema