Deployment

Perstack runs on any Node.js environment. Choose your deployment target based on security requirements, cost, and operational preferences.

Docker

The official perstack/perstack base image ships pre-compiled standalone binaries — no Node.js or Bun needed at runtime.

FROM perstack/perstack:latest
COPY perstack.toml .
RUN perstack install
ENTRYPOINT ["perstack", "run", "my-expert"]

docker build -t my-expert .
docker run --rm \
  -e ANTHROPIC_API_KEY \
  -v $(pwd)/workspace:/workspace \
  my-expert "query"

Pin to a specific version for reproducible builds:

FROM perstack/perstack:0.0.93

For production, add resource limits and network restrictions. See Isolation by Design.

AWS ECS + Fargate

taskDefinition:
  cpu: 1024
  memory: 2048
  containerDefinitions:
    - name: perstack-expert
      image: my-org/perstack-runner
      command: ["my-expert", "query"]
      environment:
        - name: ANTHROPIC_API_KEY
          valueFrom: "arn:aws:secretsmanager:region:account:secret:key"
      logConfiguration:
        logDriver: awslogs
        options:
          awslogs-group: /ecs/perstack
          awslogs-region: us-east-1

Parse stdout logs to capture execution events.

Google Cloud Run

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: perstack-expert
spec:
  template:
    spec:
      containers:
        - image: my-org/perstack-runner
          command: ["perstack", "run", "my-expert"]
          env:
            - name: ANTHROPIC_API_KEY
              valueFrom:
                secretKeyRef:
                  name: anthropic-key
                  key: latest
          resources:
            limits:
              cpu: "1"
              memory: 2Gi

Cloudflare Workers

import { run } from "@perstack/runtime"

export default {
  async fetch(request: Request, env: Env) {
    const { query, expertKey } = await request.json()
    const events: unknown[] = []
    await run(
      {
        setting: {
          providerConfig: { providerName: "anthropic", apiKey: env.ANTHROPIC_API_KEY },
          expertKey,
          input: { text: query },
        },
      },
      { eventListener: (event) => events.push(event) }
    )
    return Response.json(events)
  }
}

Secrets management

Never hardcode API keys. Use platform-native secrets:

Platform	Method
Docker	Environment variables, Docker secrets
AWS	Secrets Manager, Parameter Store
GCP	Secret Manager
Cloudflare	Workers secrets (wrangler secret put)

Registry Experts

Deploy Experts from the registry without building custom images:

docker run --rm \
  -e ANTHROPIC_API_KEY \
  -v $(pwd)/workspace:/workspace \
  perstack/perstack:latest \
  run @org/expert@1.0.0 "query"

Pin versions for reproducible deployments.

What’s next

• Isolation by Design — security configuration
• Observing — monitoring and auditing