TypeScript SDK

Configure the GitHub Packages registry, then install:

npm config set @100monkeys-ai:registry https://npm.pkg.github.com
npm install @100monkeys-ai/aegis-sdk

AegisClient

Authentication

The client supports two authentication modes:

Service-to-service (OAuth2 client credentials):

import { AegisClient } from '@100monkeys-ai/aegis-sdk';

const client = new AegisClient({
  baseUrl: 'https://your-orchestrator.com',
  keycloakUrl: 'https://auth.example.com',
  realm: 'aegis-system',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

const { execution_id } = await client.startExecution('agent-uuid', 'Write a primality check');
console.log(execution_id);

Bearer token passthrough (for user-scoped access):

import { AegisClient } from '@100monkeys-ai/aegis-sdk';

const client = new AegisClient({
  baseUrl: 'https://your-orchestrator.com',
  bearerToken: 'user-jwt-token-here',
});

const agents = await client.listAgents();

Constructor

new AegisClient(options: AegisClientOptions)

interface AegisClientOptions {
  baseUrl: string;
  // OAuth2 client credentials mode
  keycloakUrl?: string;
  realm?: string;
  clientId?: string;
  clientSecret?: string;
  tokenRefreshBufferSecs?: number; // default: 30
  // Bearer token passthrough mode
  bearerToken?: string;
}

Method Reference

Agent Management

deployAgent(manifest)

Deploy a new agent from a manifest object.

const resp = await client.deployAgent({
  name: 'code-reviewer',
  language: 'typescript',
  instruction: 'You are a code reviewer.',
});
console.log(resp.agent_id);

Returns: Promise<{ agent_id: string }>

listAgents()

List all deployed agents visible to the caller's tenant.

Returns: Promise<{ agents: Agent[] }>

getAgent(agentId)

Get details for a specific agent.

Returns: Promise<Agent>

lookupAgent(name)

Look up an agent by its unique name.

const { agent_id } = await client.lookupAgent('code-reviewer');

Returns: Promise<{ agent_id: string; name: string; tenant_id: string }>

updateAgent(agentId, payload)

Update an agent's configuration (partial update).

Returns: Promise<any>

deleteAgent(agentId)

Delete a deployed agent.

Returns: Promise<any>

executeAgent(agentId, input, intent?, contextOverrides?)

Execute an agent via the direct route.

Returns: Promise<{ execution_id: string }>

listAgentVersions(agentId)

List the version history of an agent.

Returns: Promise<{ versions: any[] }>

updateAgentScope(agentId, payload)

Update an agent's visibility scope (e.g., public, tenant-only).

Returns: Promise<any>

streamAgentEvents(agentId)

Stream real-time SSE events for all executions of a given agent.

Returns: Promise<ReadableStream>

Execution

startExecution(agentId, input, contextOverrides?, intent?)

Start a new agent execution. Returns the execution ID immediately; use streamExecution to follow progress.

const { execution_id } = await client.startExecution(
  'agent-uuid',
  'Write a primality check in TypeScript',
  undefined,
  'code-generation',
);
console.log(execution_id); // "exec-uuid"

Returns: Promise<StartExecutionResponse>

interface StartExecutionResponse {
  execution_id: string;
}

streamExecution(executionId, token?)

Stream SSE events for a running execution.

const stream = await client.streamExecution(execution_id);

Returns: Promise<ReadableStream> — an SSE event stream (see Streaming Executions below).

getExecution(executionId)

Get details of a specific execution.

Returns: Promise<any> — full execution record including status, agent_id, timestamps.

listExecutions()

List all executions visible to the caller.

Returns: Promise<{ executions: any[] }>

cancelExecution(executionId)

Cancel a running execution.

Returns: Promise<any>

deleteExecution(executionId)

Delete an execution record.

Returns: Promise<any>

getExecutionFile(executionId, path)

Download a file from an execution's workspace.

Returns: Promise<ArrayBuffer> — raw file content.

Human Approvals

listPendingApprovals()

List all pending human approval requests.

const { pending_requests, count } = await client.listPendingApprovals();
console.log(`${count} pending approvals`);

Returns: Promise<{ pending_requests: PendingApproval[]; count: number }>

getPendingApproval(id)

Get a specific pending approval by ID.

Returns: Promise<{ request: PendingApproval }>

approveRequest(id, request?)

Approve a pending request.

await client.approveRequest('approval-uuid', {
  feedback: 'Looks good',
  approved_by: 'jeshua',
});

Returns: Promise<ApprovalResponse>

rejectRequest(id, request)

Reject a pending request with a reason.

await client.rejectRequest('approval-uuid', {
  reason: 'Scope too broad',
  rejected_by: 'jeshua',
});

Returns: Promise<ApprovalResponse>

Workflow Management

registerWorkflow(payload)

Register a new workflow definition.

Returns: Promise<any>

listWorkflows()

List all registered workflow definitions.

Returns: Promise<{ workflows: any[] }>

getWorkflow(name)

Get a workflow definition by name.

Returns: Promise<any>

deleteWorkflow(name)

Delete a workflow definition.

Returns: Promise<any>

listWorkflowVersions(name)

List version history for a workflow.

Returns: Promise<{ versions: any[] }>

updateWorkflowScope(name, payload)

Update a workflow's visibility scope.

Returns: Promise<any>

runWorkflow(name, payload)

Run a workflow by name with the given input payload.

Returns: Promise<any>

executeTemporalWorkflow(payload)

Execute a Temporal workflow directly.

Returns: Promise<any>

Workflow Execution Management

listWorkflowExecutions()

List all workflow executions.

Returns: Promise<{ executions: any[] }>

getWorkflowExecution(executionId)

Get a workflow execution by ID, including final_output when available.

Returns: Promise<WorkflowExecution>

interface WorkflowExecution {
  execution_id: string;
  status: 'running' | 'completed' | 'failed';
  final_output?: Record<string, any>;
}

removeWorkflowExecution(executionId)

Remove a workflow execution record.

Returns: Promise<any>

signalWorkflowExecution(executionId, payload)

Send a signal to a running workflow execution (e.g., to advance state or provide input).

Returns: Promise<any>

cancelWorkflowExecution(executionId)

Cancel a running workflow execution.

Returns: Promise<any>

SEAL

attestSeal(payload)

Request a SEAL security token via attestation.

Returns: Promise<SealAttestationResponse>

interface SealAttestationResponse {
  security_token: string;
}

invokeSeal(payload)

Invoke a SEAL tool with a signed payload.

Returns: Promise<any>

listSealTools(securityContext?)

List available SEAL tools, optionally filtered by security context.

Returns: Promise<SealToolsResponse>

interface SealToolsResponse {
  protocol: string;
  attestation_endpoint: string;
  invoke_endpoint: string;
  security_context?: string;
  tools: any[];
}

SEAL Protocol

The @100monkeys-ai/aegis-sdk package exports a low-level SEAL module for workloads that need to self-attest and call SEAL tools directly — without going through AegisClient. Useful for custom bootstrap scripts and server-side envelope verification.

Import

import { SEALClient, Ed25519Key, createSealEnvelope, verifySealEnvelope } from '@100monkeys-ai/aegis-sdk';

SEALClient

High-level client: generates a keypair, attests, and calls tools.

import { SEALClient } from '@100monkeys-ai/aegis-sdk';

const seal = new SEALClient(
  'https://your-aegis-node',
  'my-workload',
  'default',
);

try {
  const result = await seal.attest();
  console.log(result.security_token);

  const output = await seal.callTool('read_file', { path: '/workspace/main.ts' });
  console.log(output);
} finally {
  seal.dispose();  // zeroes the in-memory private key
}

Constructor:

new SEALClient(gatewayUrl: string, workloadId: string, securityScope: string)

Methods:

AttestationResult:

type AttestationResult = {
  security_token: string;
  expires_at: string;
  session_id?: string;
}

Ed25519Key

Low-level Ed25519 keypair for manual envelope construction.

import { Ed25519Key } from '@100monkeys-ai/aegis-sdk';

const key = Ed25519Key.generate();
const signatureB64 = key.signBase64(new TextEncoder().encode('my message'));
const pubKeyB64 = key.getPublicKeyBase64();
key.erase();  // zeroes the private key when done

Envelope utilities

createSealEnvelope(securityToken, mcpPayload, privateKey)

Construct a signed SEAL envelope.

import { createSealEnvelope, Ed25519Key } from '@100monkeys-ai/aegis-sdk';

const key = Ed25519Key.generate();
const envelope = createSealEnvelope(
  '<security-token>',
  { jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'read_file', arguments: {} } },
  key,
);
// Pass envelope to AegisClient.invokeSeal() or the raw SEAL endpoint

verifySealEnvelope(envelope, publicKeyBytes, maxAgeSeconds?)

Server-side verification. Throws on invalid signature or expired timestamp; returns the inner MCP payload on success.

import { verifySealEnvelope } from '@100monkeys-ai/aegis-sdk';

const payload = verifySealEnvelope(
  envelopeObject,
  registeredPublicKeyBytes,
  30,   // max age in seconds (default: 30)
);

createCanonicalMessage(securityToken, payload, timestampUnix)

Low-level helper that produces the canonical Uint8Array that is signed.

import { createCanonicalMessage } from '@100monkeys-ai/aegis-sdk';

const msgBytes = createCanonicalMessage('<token>', mcpPayload, Math.floor(Date.now() / 1000));

SEAL types

interface McpPayload {
  jsonrpc: string;
  id: string | number;
  method: string;
  params?: Record<string, unknown>;
}

interface SealEnvelope {
  protocol: string;
  security_token: string;
  signature: string;
  payload: McpPayload;
  timestamp: string;
}

class SEALError extends Error {}

Dispatch Gateway

dispatchGateway(payload)

Dispatch a message to the inner loop gateway.

Returns: Promise<any>

Stimulus

listStimuli()

List all stimulus events.

Returns: Promise<{ stimuli: any[] }>

getStimulus(stimulusId)

Get a stimulus event by ID.

Returns: Promise<any>

ingestStimulus(payload)

Ingest an external stimulus event.

Returns: Promise<any>

sendWebhook(source, payload)

Send a webhook event from a named source.

Returns: Promise<any>

Volume Management

createVolume(payload)

Create a new storage volume.

const vol = await client.createVolume({ name: 'my-dataset' });
console.log(vol.id);

Returns: Promise<any>

listVolumes()

List all volumes owned by the caller's tenant.

Returns: Promise<{ volumes: any[] }>

getVolume(volumeId)

Get volume details by ID.

Returns: Promise<any>

renameVolume(volumeId, payload)

Rename a volume.

Returns: Promise<any>

deleteVolume(volumeId)

Delete a volume and all its contents.

Returns: Promise<any>

getVolumeQuota()

Get the caller's storage quota and current usage.

Returns: Promise<any>

listFiles(volumeId, path?)

List files and directories in a volume at the given path.

Returns: Promise<{ files: any[] }>

downloadFile(volumeId, path)

Download a file from a volume.

Returns: Promise<ArrayBuffer>

uploadFile(volumeId, file, path?)

Upload a file to a volume.

Returns: Promise<any>

mkdir(volumeId, path)

Create a directory in a volume.

Returns: Promise<any>

movePath(volumeId, payload)

Move or rename a file or directory within a volume.

Returns: Promise<any>

deletePath(volumeId, path)

Delete a file or directory from a volume.

Returns: Promise<any>

Credential Management

listCredentials()

List all stored credentials for the caller's tenant.

Returns: Promise<{ credentials: any[] }>

getCredential(credentialId)

Get a credential by ID (metadata only; secrets are not returned).

Returns: Promise<any>

storeApiKeyCredential(payload)

Store an API key credential.

const cred = await client.storeApiKeyCredential({
  name: 'github-token',
  provider: 'github',
  api_key: 'ghp_xxxx',
});

Returns: Promise<any>

revokeCredential(credentialId)

Revoke (delete) a credential.

Returns: Promise<any>

rotateCredential(credentialId)

Rotate a credential's secret value.

Returns: Promise<any>

oauthInitiate(payload)

Initiate an OAuth credential flow. Returns a URL for the user to authorize.

Returns: Promise<{ authorization_url: string }>

oauthCallback(params)

Handle OAuth callback after user authorization.

Returns: Promise<any>

devicePoll(payload)

Poll for device authorization flow completion.

Returns: Promise<any>

listGrants(credentialId)

List agent grants for a credential.

Returns: Promise<{ grants: any[] }>

addGrant(credentialId, payload)

Grant an agent access to a credential.

Returns: Promise<any>

revokeGrant(credentialId, grantId)

Revoke an agent's access to a credential.

Returns: Promise<any>

Secrets Management

listSecrets()

List all secrets in the caller's tenant namespace.

Returns: Promise<{ secrets: any[] }>

getSecret(path)

Read a secret by its path.

Returns: Promise<any>

writeSecret(path, payload)

Write or update a secret at the given path.

Returns: Promise<any>

deleteSecret(path)

Delete a secret.

Returns: Promise<any>

API Key Management

listApiKeys()

List all API keys for the caller.

Returns: Promise<{ api_keys: any[] }>

createApiKey(payload)

Create a new API key. The raw key value is only returned once at creation time.

const key = await client.createApiKey({ name: 'ci-pipeline' });
console.log(key.api_key); // Save this — it won't be shown again

Returns: Promise<{ id: string; api_key: string }>

revokeApiKey(keyId)

Revoke an API key.

Returns: Promise<any>

Colony Management

listMembers()

List all members of the caller's colony (tenant team).

Returns: Promise<{ members: any[] }>

inviteMember(payload)

Invite a new member to the colony.

Returns: Promise<any>

removeMember(userId)

Remove a member from the colony.

Returns: Promise<any>

updateRole(payload)

Update a colony member's role.

Returns: Promise<any>

getSamlConfig()

Get the colony's SAML IdP configuration.

Returns: Promise<any>

setSamlConfig(payload)

Set or update the colony's SAML IdP configuration for SSO.

Returns: Promise<any>

getSubscription()

Get the colony's subscription details.

Returns: Promise<any>

Billing

All billing methods return a rejected promise with a 501 status if STRIPE_SECRET_KEY is not configured on the orchestrator.

listPrices()

List all available pricing tiers with their Stripe price IDs.

const { tiers } = await client.listPrices();
tiers.forEach((t) => console.log(t.tier, t.monthly?.amount));

Returns: Promise<PricingResponse>

createCheckoutSession(options)

Create a Stripe Checkout Session URL for subscribing to a plan.

const { url } = await client.createCheckoutSession({
  price_id: 'price_xxx',
  seat_price_id: 'price_seat_xxx',
  seats: 5,
});
// Redirect user to url

Returns: Promise<{ url: string }>

createPortalSession()

Create a Stripe Customer Portal session URL for managing payment methods and invoices.

const { url } = await client.createPortalSession();
// Redirect user to url

Returns: Promise<{ url: string }>

getSubscriptionBilling()

Get the current user's subscription billing details from Stripe.

const sub = await client.getSubscriptionBilling();
console.log(sub.tier, sub.status);

Returns: Promise<{ tier: string; status: string; current_period_end: string; cancel_at_period_end: boolean; stripe_customer_id: string }>

getInvoices()

List invoices for the current user.

const { invoices } = await client.getInvoices();
invoices.forEach((inv) => console.log(inv.id, inv.amount, inv.status));

Returns: Promise<{ invoices: Array<{ id: string; amount: number; currency: string; status: string; created: string; pdf_url: string }> }>

Cluster & Infrastructure

getClusterStatus()

Get the overall cluster status.

Returns: Promise<any>

getClusterNodes()

List all nodes in the cluster with their status and capabilities.

Returns: Promise<{ nodes: any[] }>

Swarm Coordination

listSwarms()

List all active swarms (multi-agent coordination groups).

Returns: Promise<{ swarms: any[] }>

getSwarm(swarmId)

Get details of a specific swarm including member agents and coordination state.

Returns: Promise<any>

Observability

getDashboardSummary()

Get an aggregated observability dashboard summary (execution counts, error rates, active agents).

Returns: Promise<any>

listSecurityIncidents()

List recent security incidents.

Returns: Promise<{ incidents: any[] }>

listStorageViolations()

List storage policy violations.

Returns: Promise<{ violations: any[] }>

Cortex

listCortexPatterns()

List learned execution patterns from the Cortex memory system.

Returns: Promise<{ patterns: any[] }>

getCortexSkills()

Get the Cortex skill inventory — a summary of capabilities the system has learned.

Returns: Promise<any>

getCortexMetrics()

Get Cortex performance metrics (memory utilization, recall accuracy, decay stats).

Returns: Promise<any>

User

getUserRateLimitUsage()

Get the current authenticated user's rate limit usage.

Returns: Promise<any>

Workflow Logs

getWorkflowExecutionLogs(executionId, limit?, offset?)

Retrieve paginated workflow execution logs.

Returns: Promise<WorkflowExecutionLogs>

interface WorkflowExecutionLogs {
  execution_id: string;
  events: any[];
  count: number;
  limit: number;
  offset: number;
}

streamWorkflowExecutionLogs(executionId)

Stream workflow execution logs via SSE.

Returns: Promise<ReadableStream>

Admin: Tenant Management

createTenant(slug, displayName, tier?)

Create a new tenant. The tier parameter defaults to 'enterprise'.

Returns: Promise<Tenant>

interface Tenant {
  slug: string;
  display_name: string;
  status: string;
  tier: string;
  keycloak_realm: string;
  openbao_namespace: string;
  quotas: TenantQuotas;
  created_at: string;
  updated_at: string;
  deleted_at?: string;
}

interface TenantQuotas {
  max_concurrent_executions: number;
  max_agents: number;
  max_storage_gb: number;
}

listTenants()

List all tenants.

Returns: Promise<{ tenants: Tenant[]; count: number }>

suspendTenant(slug)

Suspend a tenant by slug.

Returns: Promise<{ status: string; slug: string }>

deleteTenant(slug)

Soft-delete a tenant by slug.

Returns: Promise<{ status: string; slug: string }>

Admin: Rate Limits

listRateLimitOverrides(tenantId?, userId?)

List rate limit overrides, optionally filtered by tenant or user.

Returns: Promise<{ overrides: RateLimitOverride[]; count: number }>

interface RateLimitOverride {
  id: string;
  resource_type: string;
  bucket: string;
  limit_value: number;
  tenant_id?: string;
  user_id?: string;
  burst_value?: number;
  created_at: string;
  updated_at: string;
}

createRateLimitOverride(payload)

Create or update a rate limit override.

Returns: Promise<RateLimitOverride>

deleteRateLimitOverride(overrideId)

Delete a rate limit override by ID.

Returns: Promise<{ status: string; id: string }>

getRateLimitUsage(scopeType, scopeId)

Get rate limit usage for a specific scope.

Returns: Promise<{ usage: UsageRecord[]; count: number }>

interface UsageRecord {
  scope_type: string;
  scope_id: string;
  resource_type: string;
  bucket: string;
  window_start: string;
  counter: number;
}

Health

healthLive()

Liveness probe. Returns { status: string }.

healthReady()

Readiness probe. Returns { status: string }.

Streaming Executions

Use streamExecution to follow a running execution via SSE:

import { AegisClient } from '@100monkeys-ai/aegis-sdk';

const client = new AegisClient({
  baseUrl: 'https://your-aegis-node',
  bearerToken: process.env.AEGIS_TOKEN,
});

const { execution_id } = await client.startExecution('agent-uuid', 'Analyze this codebase');
const stream = await client.streamExecution(execution_id);

const decoder = new TextDecoder();
const reader = stream.getReader();

while (true) {
  const { value, done } = await reader.read();
  if (done) break;

  const text = decoder.decode(value);
  for (const line of text.split('\n')) {
    if (!line.startsWith('data:')) continue;
    const event = JSON.parse(line.slice(5).trim());

    if (event.iteration_started) {
      console.log(`Iteration ${event.iteration_started.iteration_number}`);
    } else if (event.execution_completed) {
      console.log('Output:', event.execution_completed.final_output);
    } else if (event.execution_failed) {
      console.error('Failed:', event.execution_failed.reason);
    }
  }
}

See SSE stream format for the full event schema.

Agent Manifests

The @100monkeys-ai/aegis-sdk package exports manifest types and a fluent builder for constructing agent manifest YAML files programmatically.

import { AgentManifestBuilder, ImagePullPolicy } from '@100monkeys-ai/aegis-sdk';

AgentManifestBuilder

Fluent builder — the recommended API for creating manifests in code.

import { AgentManifestBuilder, ImagePullPolicy } from '@100monkeys-ai/aegis-sdk';

const manifest = new AgentManifestBuilder('my-agent', 'typescript')
  .withDescription('Analyses TypeScript repos for security issues')
  .withInstruction('You are a security auditor. Analyse the code and report CVEs.')
  .withExecutionMode('iterative', 15)
  .withImagePullPolicy(ImagePullPolicy.IfNotPresent)
  .withNetworkAllow(['api.github.com', 'registry.npmjs.org'])
  .withTool('read_file')
  .withTool('run_command')
  .withEnv('LOG_LEVEL', 'debug')
  .build();

Constructor:

new AgentManifestBuilder(name: string, language?: string, version?: string)

Methods:

ImagePullPolicy

enum ImagePullPolicy {
  Always = 'Always',
  IfNotPresent = 'IfNotPresent',
  Never = 'Never',
}

Manifest utility functions

Key manifest types

For the full field reference, see the Agent Manifest Reference.

Error Handling

All methods throw on non-2xx responses. Catch and inspect errors for HTTP-level details:

import { AegisClient } from '@100monkeys-ai/aegis-sdk';

const client = new AegisClient({
  baseUrl: 'https://your-aegis-node',
  bearerToken: process.env.AEGIS_TOKEN,
});

try {
  const { execution_id } = await client.startExecution('agent-uuid', 'Do something');
} catch (err: any) {
  if (err.response) {
    console.error(err.response.status, err.response.data);
  } else {
    throw err;
  }
}

See Also

• Python SDK Reference
• Agent Manifest Reference
• REST API Reference