SEAL Tooling Gateway

The SEAL Tooling Gateway (aegis-seal-gateway) is a standalone, AGPL-licensed Rust binary that provides the tool orchestration layer for AEGIS agents and for the broader MCP ecosystem. It sits between the orchestrator's inner loop and the external world — REST APIs, SaaS platforms, and CLI tools — enforcing SEAL security on every invocation while hiding API complexity from the LLM's context window.

The Problem It Solves

Context Window Exhaustion

Mapping a SaaS platform 1-to-1 to MCP tools (one tool per REST endpoint) floods the LLM with hundreds of JSON schemas. GitHub alone has 150+ endpoints. An LLM operating over that many tool schemas hallucinates names, confuses parameters, and makes poor decisions.

The gateway solves this with semantic compression: developers register a ToolWorkflow manifests named create_repository_with_teams that internally executes four REST calls in sequence. The LLM sees one tool with four fields. The gateway executes the four HTTP calls, threading extracted values between them.

Stateful API Choreography

Multi-step API interactions require state management — extracting a resource ID from a POST response to use as a path parameter in the subsequent PUT, paginating through results while accumulating values. LLMs perform this class of deterministic mechanical work poorly. The gateway's REST Workflow Engine handles it correctly every time.

Long-Running CLI Overhead

The model assumes MCP tool servers are long-running processes per tool per tenant. For CLI tools (Terraform, AWS CLI, FFmpeg), this means maintaining idle container instances for every registered tool at all times. The gateway replaces this with ephemeral container execution: a container is spawned per invocation, executes the command, and is immediately destroyed.

Architecture

┌─────────────────────────────────────────────────────────────┐
│  AEGIS Orchestrator (Inner Loop)                            │
│  Wraps LLM tool calls in SealEnvelope                       │
└────────────────────────────┬────────────────────────────────┘
                             │ SEAL (signed + verified)
                             ▼
┌─────────────────────────────────────────────────────────────┐
│  SEAL Tooling Gateway  (aegis-seal-gateway)                 │
│                                                             │
│  ┌───────────────────────┐    ┌──────────────────────────┐  │
│  │ Management API        │    │ Auth & Policy Engine     │  │
│  │ POST /v1/specs        │    │ SealMiddleware           │  │
│  │ POST /v1/workflows    │    │ SecurityContext eval      │  │
  │  │ POST /v1/cli-tools    │    │ OpenBao JIT  (Path A)    │  │
  │  │ POST /v1/security-... │    │ Session capability eval  │  │
  │  │ GET  /v1/tools        │    │ Keycloak exchange (Path B)│  │
│  └───────────────────────┘    └─────────────┬────────────┘  │
│                                             │               │
│  ┌──────────────────────────────────────────▼────────────┐  │
│  │              Tool Router                              │  │
│  └────┬────────────────────────┬──────────────────────┬──┘  │
│       │                        │                      │     │
│       ▼                        ▼                      ▼     │
│ ┌────────────┐          ┌─────────────┐        ┌──────────┐ │
│ │ REST       │          │ API Explorer│        │Ephemeral │ │
│ │ Workflow   │          │ (Slicing)   │        │CLI Engine│ │
│ │ Engine     │          │             │        └────┬─────┘ │
│ └─────┬──────┘          └──────┬──────┘             │       │
└───────┼────────────────────────┼────────────────────┼───────┘
        │                        │         1. Semantic Judge
        ▼                        ▼         2. Container spawn
  External REST APIs       External REST        ▼
  (GitHub, AWS, Jira)        APIs          Docker Daemon
                                                │
                                         3. FSAL mount
                                                ▼
                                        Agent SeaweedFS Volume

Core Concepts

ToolWorkflow

A ToolWorkflow is a named macro-tool manifest that maps a single compressed input schema to a sequence of REST calls. Developers author workflows in YAML or JSON and register them via the gateway management API. Once registered, the workflow appears in GET /v1/tools as a single tool entry with a name and description.

name: create_repository_with_teams
description: "Create a GitHub repo and configure team access in one operation"
api_spec_id: "github-v3"
input_schema:
  type: object
  properties:
    repo_name: { type: string }
    org: { type: string }
    team_slugs: { type: array, items: { type: string } }
steps:
  - name: create_repo
    operation_id: repos/create-in-org
    body_template: '{"name": "{{input.repo_name}}", "private": true}'
    extractors:
      repo_id: "$.id"
      full_name: "$.full_name"
  - name: add_teams
    operation_id: teams/add-or-update-repo-permissions-in-org
    body_template: '{"permission": "push"}'

Each step's body_template is a Handlebars template that can reference {{input.*}} (the original call inputs) and {{steps.<name>.*}} (extracted values from earlier steps).

The LLM provides repo_name, org, and team_slugs. The gateway runs the sequence, threads extracted values, and returns the final result. The LLM never sees the intermediate HTTP calls.

ToolWorkflow vs ContainerRun: ToolWorkflow is a synchronous, sub-second REST macro-tool. It is completely separate from ContainerRun / ParallelContainerRun, which are long-running Temporal-backed CI/CD pipeline primitives. Do not conflate them.

ApiSpec

An ApiSpec is a registered OpenAPI 3.x document. The gateway resolves operation_id values in WorkflowStep entries against the registered spec at invocation time. Specs are registered via POST /v1/specs and can be fetched from a URL or submitted inline.

POST /v1/specs
{
  "name": "github-v3",
  "source_url": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json"
}

EphemeralCliTool

An EphemeralCliTool registers a CLI tool backed by a Docker image. When an agent invokes it, the gateway spawns an ephemeral container from the image, mounts all execution volumes at their canonical /workspace... paths via AegisFSAL, executes the command, streams output, and immediately destroys the container.

name: terraform
docker_image: "hashicorp/terraform:1.9"
allowed_subcommands:
  - plan
  - output
  - show
require_semantic_judge: true
default_timeout_seconds: 120
registry_credential_path:
  Auto:
    system_jit_openbao_engine_path: "docker/creds"
    system_jit_role: "puller"
    target_service: "ghcr.io"

allowed_subcommands provides a static lexical allowlist. If require_semantic_judge is true, the parsed command intent is also submitted to a Semantic Judge (see below) before the container is created.

Execution Paths

Path 1 — REST Workflow Engine

1. Agent invokes a registered ToolWorkflow via SEAL-wrapped JSON-RPC.
2. Gateway verifies the SealEnvelope, loads the SecurityContext, checks the workflow name against Capability constraints.
3. Gateway resolves credentials (see Credential Resolution).
4. Gateway executes steps sequentially — renders Handlebars templates, calls the upstream API, applies JSONPath extractors to pass state to the next step.
5. Returns the final step's output to the orchestrator.

Path 2 — API Explorer (Workflow Authoring Mode)

The API Explorer is not exposed to agents in production runs. It is activated in a dedicated workflow-authoring session for engineers or agents building new ToolWorkflow manifests. In the current implementation, explorer endpoints require operator auth on both HTTP and gRPC management surfaces.

The agent provides a fields array of JSONPath selectors. The gateway executes the requested API call, filters the response to include only the requested fields (Response Slicing), and optionally injects _hints metadata (next page URL, related operations) to guide exploration without returning verbose raw responses.

Once the agent has mapped the API's shape through a series of sliced calls, it uses POST /v1/workflows to author a permanent workflow. The Explorer is then not needed again.

Path 3 — Ephemeral CLI Engine

Agent calls "terraform" tool
        │
        ▼
Gateway: static allowlist check
  "plan" ∈ allowed_subcommands? ✅
        │
        ▼
Gateway: Semantic Judge (if require_semantic_judge = true)
  Intent safe for agent's SecurityContext? ✅
        │
        ▼
Gateway: resolve image registry credentials from OpenBao
        │
        ▼
Docker: spawn ephemeral container from "hashicorp/terraform:1.9"
        │
        ▼
FSAL: mount all execution volumes → /workspace... (AegisFSAL enforces access mode)
        │
        ▼
Container: terraform plan (working directory /workspace)
        │
        ▼
Gateway: collect stdout/stderr (capped at 1 MB)
        │
        ▼
Docker: destroy container immediately
        │
        ▼
Return result to orchestrator

Semantic Judging: The gateway integrates with the Semantic Judge mechanism from Advanced Judge Capabilities to catch semantically dangerous commands that pass the static allowlist. For example, terraform apply -destroy passes a lexical check for apply but a Semantic Judge configured for a read-only SecurityContext will reject it before any container is created. A CliToolSemanticRejected event is emitted for audit purposes.

When invoking CLI tools internally, the orchestrator passes the full mount set as fsal_mounts[] (volume_id, mount_path, read_only), not a single volume identifier.

Credential Resolution

The gateway never holds static credentials. All credentials are resolved at invocation time based on the CredentialResolutionPath configured per ApiSpec or EphemeralCliTool (registry_credential_path for CLI image pulls).

Human-Delegated Auth is the key differentiator for Zaru users. When you ask a Zaru agent to create a pull request on your behalf, GitHub sees the request as coming from your account with your permissions — not from a generic service account. If you don't have permission to push to a repo, neither does the agent.

Management API

The management API is authenticated via Bearer JWT (Keycloak aegis-system realm, AegisRole::Operator or higher). Agents use their SecurityToken; human operators use their Keycloak JWT.

# Spec management
POST   /v1/specs              Register an OpenAPI spec
GET    /v1/specs              List registered specs
GET    /v1/specs/{id}         Retrieve a spec
DELETE /v1/specs/{id}         Remove a spec

# Workflow management
POST   /v1/workflows          Author and register a ToolWorkflow
GET    /v1/workflows          List workflows (name + description only)
GET    /v1/workflows/{id}     Retrieve full workflow definition
PUT    /v1/workflows/{id}     Update a workflow
DELETE /v1/workflows/{id}     Remove a workflow

# CLI tool management
POST   /v1/cli-tools          Register an EphemeralCliTool
GET    /v1/cli-tools          List CLI tools
DELETE /v1/cli-tools/{name}   Remove a CLI tool registration

# SecurityContext management
POST   /v1/security-contexts        Create or update a SecurityContext
GET    /v1/security-contexts        List SecurityContexts
GET    /v1/security-contexts/{name} Retrieve one SecurityContext

# Agent-facing discovery
GET    /v1/tools              List all tools visible to agents (name + description only)

GET /v1/tools is the endpoint that AEGIS Orchestrator calls to populate the tool schema list it injects into the LLM prompt. It returns only names and descriptions — never raw OpenAPI schemas — keeping the LLM's tool list compact regardless of how many workflows are registered.

Built-in Web UI (Optional, Enabled by Default)

The gateway ships with a built-in operator web UI:

• GET / — dashboard shell
• GET /ui/app.js and GET /ui/styles.css — bundled assets

Use SEAL_GATEWAY_UI_ENABLED=false to disable all UI routes.

Integration with the AEGIS Ecosystem

Deployment

The gateway is a standalone binary following the same deployment pattern as aegis-cortex, aegis-embedding-service, and aegis-temporal-worker.

# aegis-config.yaml — orchestrator node config
spec:
  seal_gateway:
    url: "http://aegis-seal-gateway:50055"          # gateway gRPC endpoint

When spec.seal_gateway.url is configured, the orchestrator routes SEAL envelopes for registered external tool names to the gateway over gRPC. When it is absent, the orchestrator's internal tool router handles all tools (built-in only — no workflows or ephemeral CLI tools).

The gateway can also be deployed independently of AEGIS Orchestrator for organizations using standard MCP.

Security Summary