Zaru Integration

Zaru (myzaru.com) is the consumer-facing product built atop the AEGIS orchestrator. It uses a custom Zaru chat client (zaru-client) that connects to AEGIS's execution semantics via the Signed Envelope Attestation Layer (SEAL), providing users access to the Glass Laboratory UX and intelligent agent swarm orchestration.

Identity Bridging

Zaru authenticates consumer users via an Identity Provider (e.g., OAuth 2.0 or Enterprise SAML). To bridge this web-layer identity to the AEGIS execution engine securely, the orchestrator employs the ZaruAuthMiddleware.

1. Token Validation: Zaru passes a JSON Web Token (JWT) representing the user session (MyzaruJWT) to the Orchestrator via HTTP headers.
2. Attestation: The middleware validates the JWT against the identity provider's JWKS and extracts the user identity (ZaruUserId) and their subscription layer (ZaruTierClaim).
3. Security Token Issuance: AEGIS translates this verified identity into an SEAL SecurityToken, granting the user's agent executions authorized access to a specific SecurityContext.

Note: The MyzaruJWT is treated as a highly sensitive credential and is wrapped in a redacted display type; it is never logged or stored in plain text by the orchestrator.

Zaru Client MCP Configuration

The Zaru client connects to the AEGIS orchestrator as an MCP server using the Streamable HTTP transport. Identity headers are injected by the client to bridge authenticated user sessions into SEAL security contexts.

# zaru-client MCP configuration (myzaru.com deployment example)

mcpServers:
  aegis-orchestrator:
    type: sse
    url: "https://api.myzaru.com/mcp/v1/sse"
    headers:
      # Inject Zaru user identity as a signed claim.
      # The AEGIS ZaruAuthMiddleware validates this against the JWKS endpoint.
      X-Zaru-User-ID: "{{ZARU_USER_ID}}"
      X-Zaru-Tier: "{{ZARU_USER_TIER}}"
      Authorization: "Bearer {{ZARU_USER_TOKEN}}"
    timeout: 120000 # 2-minute tool call timeout (covers long 100monkeys iterations)

Session and Swarm Management

In Zaru, a session (a single chat conversation) maps directly to a root ExecutionId.

• Single Active Root: A user cannot launch two independent top-level agent tasks concurrently within the same session.
• Swarm Subordination: If the primary agent decides to parallelize work, it can spawn child agents (forming a Swarm). Every child execution is subordinate to the root ExecutionId representing the Zaru session.
• Cascade Cancellation: If the user cancels the session via the Zaru UI, the root execution is cancelled, and this cancellation cascades downwards to terminate all active child executions in the swarm.

Tier Routing

A user's ZaruTier determines their allocated resources and tool capabilities. The ZaruAuthMiddleware intercepts the tier claim from the JWT and automatically maps it to a pre-configured SEAL SecurityContext.

The Zaru client does not hardcode AEGIS tools locally. It discovers the orchestrator's current tool inventory at runtime via MCP and then exposes only the tools allowed by the user's tier-derived SecurityContext.

Consumer tiers access AEGIS via aegis.agent.generate and aegis.workflow.generate — authoring loops that handle creation, validation, and deployment from natural language intent. Direct manifest deployment tools (aegis.agent.create, aegis.workflow.create, aegis.agent.update, aegis.workflow.update) are not part of the consumer tool surface; they are available only to operators. All paid tiers (Pro, Business, Enterprise) share identical consumer tool access. Free has a slightly reduced set — it lacks aegis.workflow.signal. The primary tier differentiators are rate limits, resource allocation, teams and organization support, storage quotas, and self-hosted deployment options.

Tier contexts govern the chat surface only. When a user calls aegis.task.execute, the agent container that is spawned does not run under the user's tier context (zaru-free, zaru-pro, etc.). It runs under the platform's built-in agent-runtime context, which grants filesystem access scoped to /workspace, shell execution, outbound web access, and aegis read/execution tools. The user's tier context determines whether they are permitted to trigger an execution at all — agent-runtime determines what the agent container can do once it is running.

• Free (ZaruTier::Free) — maps to "zaru-free". Slightly reduced tool set (no workflow signal). Strict rate limits (3 agent executions/min, 20/day). 5-minute execution timeout, 5 max iterations, 1 concurrent execution, 512 MB memory. Limited persistent storage with a configurable volume count.
• Pro (ZaruTier::Pro) — maps to "zaru-pro". Full tool access, persistent storage up to 10 GB (30-day TTL), 30-minute timeout, 10 iterations, 5 concurrent executions. Rate limits: 10 agent executions/min, 200/day. BYOK users are exempt from LLM-specific rate limits.
• Business (ZaruTier::Business) — maps to "zaru-business". Same tool access as Pro. Adds teams and organization support, dedicated node option, custom agent and workflow manifests, and audit logs with 90-day retention. 50 GB storage, 4-hour timeout, 50+ concurrent executions. Rate limits: 30 agent executions/min, 1,000/day. Limits are customizable per-tenant.
• Enterprise (ZaruTier::Enterprise) — maps to "zaru-enterprise". Same tool access. Adds self-hosted and air-gapped deployment, SAML federation, and a full audit trail with 365-day retention. 100 GB storage, 24-hour timeout, unlimited concurrent executions. Rate limits: 100 agent executions/min, 10,000/day. All limits are fully customizable per-tenant and per-user.

Because the system enforces a strict "ceiling rule" during Swarm creation, a child agent can never be spawned with a broader SecurityContext than its parent, ensuring tier restrictions apply collectively across the entire agent swarm.

Subscription Billing

Zaru uses Stripe for subscription management. Each consumer user's ZaruTier is backed by a Stripe subscription, and tier changes are propagated automatically through the platform.

Tier Lifecycle

1. Checkout: The user selects a plan via the Zaru pricing page (or a POST /v1/billing/checkout API call). This creates a Stripe Checkout Session and redirects the user to Stripe's hosted payment form.
2. Activation: When payment succeeds, Stripe fires a checkout.session.completed webhook. The orchestrator receives this at POST /v1/webhooks/stripe, resolves the user, and updates their zaru_tier attribute in Keycloak.
3. Renewal: Stripe automatically renews subscriptions at each billing period. On invoice.payment_succeeded, the orchestrator confirms the tier remains active.
4. Tier Change: When a user upgrades or downgrades, Stripe fires customer.subscription.updated. The orchestrator maps the new Stripe Price ID to the corresponding ZaruTier and updates Keycloak accordingly.
5. Cancellation: When a subscription is cancelled (customer.subscription.deleted), the user's tier reverts to Free at the end of the current billing period. The cancel_at_period_end flag is set on the subscription so the user retains paid access until the period expires.
6. Payment Failure: On invoice.payment_failed, the subscription enters past_due status. The user's tier remains unchanged during the grace period configured in Stripe's retry settings.

Propagation Path

Tier changes flow through the system as follows:

Stripe webhook → Orchestrator → Keycloak (zaru_tier attribute) → JWT claim → SecurityContext

The orchestrator updates the user's zaru_tier attribute in the zaru-consumer Keycloak realm. The next JWT issued for that user carries the updated zaru_tier claim, which the ZaruAuthMiddleware uses to resolve the appropriate SecurityContext. Existing sessions continue with their current tier until the JWT expires and is refreshed.

Self-Hosted Deployments

Stripe billing is entirely optional. Self-hosted deployments that omit the spec.billing configuration section manage tiers directly through Keycloak user attributes or the admin API. All /v1/billing/* endpoints return 501 Not Implemented when STRIPE_SECRET_KEY is not configured.

Operator Tier

Alongside the consumer tiers above, AEGIS supports a separate operator tier for platform administrators and SREs. Operators and consumers use distinct identity paths:

All consumer users authenticate through the shared zaru-consumer Keycloak realm, but each user is assigned a dedicated per-user tenant at signup (slug format u-{uuid}). This provides full data isolation between consumer users — agents, workflows, executions, and secrets are scoped to the individual's tenant rather than a shared pool. The tenant_id is injected into the JWT via a protocol mapper on the zaru-consumer realm, and each per-user tenant is provisioned with tier-appropriate quotas (Free, Pro, Business, or Enterprise).

ZaruTier is a subscription tier — it determines the consumer's resource allocation, rate limits, and storage quotas. AegisRole is a platform role — it determines what administrative operations an operator may perform.

Operators authenticate via the aegis-system Keycloak realm and carry aegis_role claims in their JWT. Their sessions are mapped to the aegis-system-operator SecurityContext, which provides access to all safe commands (the same set available to enterprise consumers) plus destructive and orchestrator commands that are never exposed to any consumer tier.

The three operator roles provide graduated access:

• aegis:admin — full read/write on all objects, daemon configuration, user management
• aegis:operator — deploy/manage agents and workflows, start/cancel executions, manage volumes
• aegis:readonly — read any object, list executions, stream events, no mutations

Glass Laboratory UX

The Zaru client provides a specialized frontend experience known as the Glass Laboratory. This includes:

• Transparent Iteration Panel: Renders the agent's iteration loop as plain-English system bubbles inline in the conversation — showing attempts, fixes, memory reuse, and completion without exposing technical internals.
• Zaru Conversation Modes: Conversations have five user-selected modes — ZaruConversationMode::Chat, ZaruConversationMode::Agentic, ZaruConversationMode::Architect, ZaruConversationMode::Execute, and ZaruConversationMode::Operator — chosen at conversation creation and locked once the first message is sent. For example, ZaruConversationMode::Architect transitions the interface into a specialized state for interactively defining AEGIS workflow manifests. ZaruConversationMode::Execute provides a single-shot code execution path: describe a computation, optionally supply typed inputs, and Zaru runs the generated code in a sandboxed container and returns the result directly in chat (see Running Code with Execute Mode).
• Context Panel: A collapsible right sidebar available in most conversation modes. Expand it using the panel icon in the top-right corner of the chat interface to browse resources relevant to the active mode — agents, workflows, and tools. The panel is hidden in pure Chat mode, where no platform resources are in scope. In all other modes, each listed resource offers two actions: Execute opens an inline parameter form and runs the resource directly, showing the result inside the panel; Send to Chat injects a structured prompt into the chat input so Zaru can assist with configuration or explain the resource before running it.
• Documentation Search: Zaru can search its own documentation via zaru.docs in any conversation mode. Ask Zaru about AEGIS concepts, API usage, manifest formats, or any topic covered at docs.100monkeys.ai and it will return relevant documentation sections inline.