Skip to main content

Getting Started

What is Pai​

Pai is a platform for running AI agents securely in the public or private cloud. You describe what your agent needs -- which model, what tools, what external services -- and Pai runs it with enterprise-grade security controls.

Building Blocks of an Agent​

Container Image or System Prompt​

An agent is either a custom container image (for complex apps with their own runtime) or a system prompt that runs on the Pai harness. The harness requires no image -- Pai provides bash, file operations, web search, and more out of the box. Both are declared as an Agent.

Models​

Which LLM the agent uses. You set up a ModelProvider once per API subscription (Anthropic, Google, OpenAI), then agents reference models as anthropic/claude-sonnet-4-6. The platform routes requests to the right provider and injects API keys automatically.

Providers​

External services the agent can access: GitHub, AWS, Linear, Telegram, MCP servers, any REST API. Pai injects credentials transparently -- the agent never sees real API keys. Each Provider declares the service type, authentication method, and access policy.

Skills​

Reusable capabilities -- files, scripts, instructions -- that can be mounted into any agent. Skills let you share common behaviour across agents without duplicating configuration. See Skills.

Security Controls​

Non-root Execution​

Agent containers always run as a non-root user. Pai defaults to UID 65532 and rejects any workload that tries to run as root (runAsUser: 0) at reconcile time. Combined with allowPrivilegeEscalation: false and the RuntimeDefault seccomp profile, a compromised agent cannot setuid, escape via ptrace, or reach kernel interfaces the runtime blocks by default.

Credential Isolation​

API keys, tokens, and cloud credentials are never visible to the agent container. The platform injects them to outbound requests and attaches the correct authentication headers. See Provider.

Model and Tool Access Control​

Control which models, MCP servers, tools, and APIs each agent can use. Inline provider narrowing lets you tighten permissions per-agent without duplicating resources. See Agent.

LLM Security Proxy​

Prompt-injection and jailbreak scanning on every LLM call via pluggable guard classifiers. Guards can be set per-agent or per-ModelProvider as an org-wide baseline. The LLM gateway can also be exposed to external developers outside the cluster. See Prompt Guard and LLM Gateway.

Audit​

Tamper-evident audit chain on every LLM call and provider request. Full token usage tracking across all agents. pai audit <agent> merges sidecar and gateway events and supports --type filtering. See Agent.

Enterprise Controls​

Pai gives platform teams the levers you expect from an enterprise runtime — budgets, triggers, and autoscaling — all declared on the Agent resource.

Token budgets and cost caps​

Every LLM call routes through the Pai Gateway, so usage is tracked per agent in real time. You can set a hard daily token cap (spec.tokens.maxPerDay), a per-request context ceiling (spec.tokens.maxPerRequest), a requests-per-minute limit, a concurrent-request limit, or a daily USD cap (spec.rateLimits). Excess requests are rejected with HTTP 429 — no runaway spend. See Agent token budgets.

Triggers — run on a schedule or in response to events​

An agent can be always-running (service type) or wake up only when needed:

  • Cron schedule -- set spec.schedule: "0 9 * * *" on a task agent to run it daily at 9am UTC (or any 5-field cron expression). The controller creates a CronJob and each run is isolated.
  • Telegram message -- a message in a Telegram chat wakes the agent and passes it as input.
  • Email -- an incoming email creates a session. The agent receives the sender, subject, and body.
  • Webhook -- an HTTP POST to a unique URL triggers the agent with the request payload.

Triggers are configured via spec.triggers and spec.schedule. See Agent scheduled tasks and the full trigger reference on the Agent page.

Autoscaling on custom metrics​

Service agents scale replicas up and down automatically based on traffic or queue depth. Built-in metric types:

  • tokenRate -- gateway-observed tokens per minute per replica.
  • http -- poll any URL returning a JSON number (JIRA backlog, SQS depth, custom queues).

Configure minReplicas, maxReplicas, cooldown windows, and per-replica targets. See Agent autoscaling.

Install the CLI​

curl -Lo pai https://pairun.dev/download/pai-macos-arm64
chmod +x pai
sudo mv pai /usr/local/bin/pai
note

Linux and Windows builds are also available at pairun.dev/download.

Log in​

pai login https://api.pairun.dev --token <your-token>

Your token was provided when your account was created. Verify you're connected:

pai get agents
Integrating with agents on your laptop

Pai can also act as an LLM and MCP gateway for AI tools running on your own machine (Claude Code, IDE assistants, scripts), giving them the same audit trail, token budgets, and prompt guards the platform gives its own agents. This requires enabling external access on your Provider and a bit of extra setup — see LLM Gateway.

Next steps​