# Symbiont Sdk Js

> Javascript SDK for Symbiont

- **Type:** MCP server
- **Install:** `agentstack add mcp-thirdkeyai-symbiont-sdk-js`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ThirdKeyAI](https://agentstack.voostack.com/s/thirdkeyai)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [ThirdKeyAI](https://github.com/ThirdKeyAI)
- **Source:** https://github.com/ThirdKeyAI/symbiont-sdk-js
- **Website:** https://symbiont.dev

## Install

```sh
agentstack add mcp-thirdkeyai-symbiont-sdk-js
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

[](https://www.npmjs.com/package/symbi-core)
[](https://www.typescriptlang.org/)
[](LICENSE)
[](https://docs.symbiont.dev)

---

**Official JavaScript/TypeScript SDK for Symbiont, the policy-governed agent runtime.**
*Same agent. Secure runtime.*

This SDK is the integration surface for the [Symbiont runtime](https://github.com/thirdkeyai/symbiont). Use it from Node.js, edge runtimes, or the browser to manage agents and workflows, drive scheduled and channel-bound execution, manage policies, secrets, and MCP connections, verify webhooks, and integrate AgentPin identity — all against a runtime that enforces Cedar policy, SchemaPin tool verification, ToolClad tool contracts, and tamper-evident audit logging.

The runtime decides what an agent may do. The SDK decides how your application talks to the runtime.

---

## Why Symbiont

AI agents are easy to demo and hard to trust. Once an agent can call tools, access files, send messages, or invoke external services, you need more than prompts and glue code. You need:

- **Policy enforcement** for what an agent may do — built-in DSL and [Cedar](https://www.cedarpolicy.com/) authorization
- **Tool verification** so execution is not blind trust — [SchemaPin](https://github.com/ThirdKeyAI/SchemaPin) cryptographic verification of MCP tools
- **Tool contracts** for how tools execute — [ToolClad](https://github.com/ThirdKeyAI/ToolClad) declarative input validation, scope enforcement, and injection prevention
- **Agent identity** so you know who is acting — [AgentPin](https://github.com/ThirdKeyAI/AgentPin) domain-anchored ES256 identity
- **Audit trails** for what happened and why — cryptographically tamper-evident logs
- **Approval gates** for sensitive actions — human review before execution when policy requires it

Symbiont is the runtime that enforces all of this. This SDK is the typed, ergonomic way to drive it from JavaScript and TypeScript.

---

## Quick start

### Prerequisites

A running Symbiont runtime is required. The fastest way:

```bash
# Start the runtime (API on :8080, HTTP input on :8081)
docker run --rm -p 8080:8080 -p 8081:8081 ghcr.io/thirdkeyai/symbi:latest up
```

For Homebrew, install scripts, building from source, or production deployment, see the [getting-started guide](https://docs.symbiont.dev/getting-started).

### Install

```bash
npm install symbi-core
```

### Hello, runtime

```typescript
import { SymbiontClient } from 'symbi-core';

const client = new SymbiontClient({
  apiKey: process.env.SYMBIONT_API_KEY,
  apiUrl: 'http://localhost:8080/api/v1',
});

await client.connect();

// Create an agent
const agent = await client.agents.createAgent({
  name: 'textProcessor',
  description: 'Processes and analyzes text input',
  parameters: [{ name: 'text', type: { name: 'string' }, required: true }],
  returnType: { name: 'string' },
  capabilities: ['text_processing'],
});

// Execute it
const result = await client.agents.executeAgent(agent.id, { text: 'Hello, Symbiont!' });
console.log(result.result);
```

---

## Compatibility

The SDK talks to the runtime over its versioned REST API (`/api/v1`).

| SDK (`symbi-core`) | Symbiont runtime |
|--------------------|------------------|
| 1.14.x             | 1.14.x (tested); compatible with 1.15.x / 1.16.x for the documented surface |

Pin the SDK's minor version to your runtime's minor version when you can; newer
1.x runtimes remain compatible for the endpoints documented here.

---

## Capabilities

The SDK exposes one client (`SymbiontClient`) with namespaced sub-clients for each runtime feature.

| Sub-client | Surface |
|------------|---------|
| `client.agents` | Agent lifecycle (create, update, execute, re-execute, delete, history, heartbeat, push events) |
| `client.schedules` | Cron schedules with pause/resume/trigger and run history |
| `client.channels` | Slack/Teams/Mattermost adapters, mappings, audit |
| `client.workflows` | Multi-agent workflow execution |
| `client.agentpin` | Client-side AgentPin keygen, credential issuance and verification, discovery, key pinning |
| `client.policies` / `client.policyBuilder` | Policy creation and management |
| `client.secrets` | Vault, encrypted-file, and OS-keychain secrets |
| `client.toolReview` | Tool review workflow |
| `client.mcp` | MCP server connection management |
| `client.system` | Health, metrics, runtime info |
| `client.metricsClient` | OTLP / file metrics export, snapshots, periodic collection |
| `client.http` | Dynamic HTTP endpoint management |

Standalone modules (no client required): `WebhookVerifier` (HMAC, JWT, provider presets), `MarkdownMemoryStore` (file-based agent context), `SkillScanner` / `SkillLoader` (ClawHavoc scanning + skill loading).

---

## Trust Stack integration

The SDK gives you typed access to the Trust Stack primitives it exposes, against
a runtime that enforces the rest:

- **Cedar policies** via `client.policies` and the `client.policyBuilder` namespace — create and manage fine-grained authorization for agent actions
- **AgentPin** via `client.agentpin.*` — domain-anchored ES256 credential issuance and verification, runs entirely client-side (no runtime required)
- **Secrets** via `client.secrets` — Vault, encrypted-file, and OS-keychain backends
- **MCP connections** via `client.mcp` and tool review via `client.toolReview`
- **ToolClad tool contracts and SchemaPin verification** — enforced by the runtime server-side; tool signatures are verified before tool execution

Model output is never treated as execution authority. The runtime controls what actually happens.

---

## Packages

The SDK is published as a set of focused packages. Most users only need `symbi-core` (which re-exports types from `symbi-types` and re-exports the agent client).

| Package | Purpose |
|---------|---------|
| [`symbi-core`](https://www.npmjs.com/package/symbi-core) | Main client, configuration, auth, webhook verification, skills, metrics, memory |
| [`symbi-types`](https://www.npmjs.com/package/symbi-types) | Shared TypeScript interfaces and Zod schemas |
| [`symbi-agent`](https://www.npmjs.com/package/symbi-agent) | Agent, schedule, channel, workflow, AgentPin clients |
| [`symbi-policy`](https://www.npmjs.com/package/symbi-policy) | Policy builder and enforcement |
| [`symbi-secrets`](https://www.npmjs.com/package/symbi-secrets) | Vault / file / OS-keychain secrets backends |
| [`symbi-mcp`](https://www.npmjs.com/package/symbi-mcp) | MCP protocol client |
| [`symbi-tool-review`](https://www.npmjs.com/package/symbi-tool-review) | Tool review workflow |
| [`symbi-testing`](https://www.npmjs.com/package/symbi-testing) | Mocks and test helpers |
| [`symbi-cli`](https://www.npmjs.com/package/symbi-cli) | Command-line tooling |
| [`symbiont-sdk-js`](https://www.npmjs.com/package/symbiont-sdk-js) | Monorepo source distribution |

---

## Examples

### Agents and workflows

```typescript
await client.connect();

// Create and execute an agent
const agent = await client.agents.createAgent({
  name: 'textProcessor',
  description: 'Processes and analyzes text input',
  parameters: [{ name: 'text', type: { name: 'string' }, required: true }],
  returnType: { name: 'string' },
  capabilities: ['text_processing'],
});

const result = await client.agents.executeAgent(agent.id, { text: 'Hello, Symbiont!' });
console.log(result.result);

// List the fleet
const agents = await client.agents.listAgents();
```

### AgentPin — client-side identity

AgentPin operations run client-side; no Symbiont runtime is required.

```typescript
const { privateKeyPem, publicKeyPem } = client.agentpin.generateKeyPair();
const kid = client.agentpin.generateKeyId(publicKeyPem);

const jwt = client.agentpin.issueCredential({
  privateKeyPem,
  kid,
  issuer: 'example.com',
  agentId: 'data-analyzer',
  capabilities: ['read:data', 'write:reports'],
  ttlSecs: 3600,
});

// Verify (fetches discovery automatically)
const result = await client.agentpin.verifyCredential(jwt);
console.log(result.valid, result.agent_id, result.capabilities);
```

### HTTP Input invocation (Symbiont v1.10.0)

The runtime's HTTP Input handler dispatches webhooks to a running agent on the communication bus, or falls back to an on-demand LLM ORGA loop against ToolClad manifests when the agent is not running. The SDK ships typed responses for both shapes:

```typescript
import type {
  WebhookInvocationRequest,
  WebhookInvocationResponse,
  WebhookCompletedResponse,
  WebhookExecutionStartedResponse,
} from 'symbi-types';

// Send to your runtime's HTTP Input endpoint, then parse:
function handle(resp: WebhookInvocationResponse) {
  if (resp.status === 'execution_started') {
    console.log('dispatched message', resp.message_id, 'in', resp.latency_ms, 'ms');
  } else {
    console.log('LLM completed via', resp.provider, resp.model);
    for (const run of resp.tool_runs) {
      console.log(' -', run.tool, run.output_preview);
    }
  }
}
```

### Webhook signature verification

```typescript
import { HmacVerifier, JwtVerifier, createProviderVerifier } from 'symbi-core';

// Provider preset (GitHub, Stripe, Slack, custom)
const verifier = createProviderVerifier('GITHUB', Buffer.from(secret));
verifier.verify(request.headers, Buffer.from(request.body));

// Manual HMAC with prefix stripping
const hmac = new HmacVerifier(Buffer.from(secret), 'X-Hub-Signature-256', 'sha256=');
hmac.verify(headers, body);
```

### Markdown memory persistence

```typescript
import { MarkdownMemoryStore } from 'symbi-core';

const store = new MarkdownMemoryStore('/data/memory', 30);
await store.saveContext('agent-1', {
  agentId: 'agent-1',
  facts: ['User prefers dark mode'],
  procedures: ['Always greet by name'],
  learnedPatterns: ['Responds better to bullet points'],
  metadata: { lastSession: '2026-02-15' },
});
const context = await store.loadContext('agent-1');
```

### Agent skills — ClawHavoc scanning

```typescript
import { SkillScanner, SkillLoader } from 'symbi-core';

// 10 built-in ClawHavoc rules (pipe-to-shell, eval+fetch, base64-decode-exec, etc.)
const scanner = new SkillScanner();
const findings = scanner.scanContent(content, 'SKILL.md');

const loader = new SkillLoader({
  loadPaths: ['/skills/verified', '/skills/community'],
  requireSigned: false,
  scanEnabled: true,
});
const skills = await loader.loadAll();
```

---

## Configuration

### Environment

```bash
SYMBIONT_API_KEY=...                       # required
SYMBIONT_API_URL=http://localhost:8080/api/v1
SYMBIONT_ENVIRONMENT=production
```

### Programmatic

```typescript
const client = new SymbiontClient({
  apiKey: process.env.SYMBIONT_API_KEY,
  apiUrl: process.env.SYMBIONT_API_URL,
  environment: 'production',
  validationMode: 'strict',
  timeout: 30000,
});
```

See the [API reference](https://docs.symbiont.dev/api-reference) for the full configuration surface.

---

## Documentation

- [Getting started](https://docs.symbiont.dev/getting-started)
- [Security model](https://docs.symbiont.dev/security-model)
- [Runtime architecture](https://docs.symbiont.dev/runtime-architecture)
- [Reasoning loop guide](https://docs.symbiont.dev/reasoning-loop)
- [DSL guide](https://docs.symbiont.dev/dsl-guide)
- [API reference](https://docs.symbiont.dev/api-reference)

The Symbiont runtime itself lives at [thirdkeyai/symbiont](https://github.com/thirdkeyai/symbiont).

---

## What's new

### v1.10.1 — packaging
Workspace packages renamed from the previously-unpublished `@symbi/*` scope to unscoped `symbi-*` names so they can actually be installed from npm. Packaging-only release; no API changes.

### v1.10.0 — HTTP Input LLM invocation
- `WebhookInvocationResponse` discriminated union covering both `execution_started` (runtime communication-bus dispatch) and `completed` (on-demand LLM ORGA loop) shapes from the Symbiont v1.10.0 HTTP Input handler
- `WebhookToolRun`, `WebhookInvocationRequest`, `WebhookInvocationStatus` with Zod schemas
- ToolClad v0.4.0 backend strings (`http`, `mcp`, `session`, `browser`) accepted on `ToolManifestInfo.backend`
- All packages aligned to Symbiont runtime v1.10.0

See [`CHANGELOG.md`](./CHANGELOG.md) for the full history.

---

## License

Apache 2.0. See [`LICENSE`](./LICENSE).

The SDK is part of the Symbiont project's Community Edition. For Enterprise licensing of the Symbiont runtime (advanced sandbox backends, compliance audit exports, AI-powered tool review, encrypted multi-agent collaboration, monitoring dashboards, dedicated support), contact [ThirdKey](https://thirdkey.ai).

---

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ThirdKeyAI](https://github.com/ThirdKeyAI)
- **Source:** [ThirdKeyAI/symbiont-sdk-js](https://github.com/ThirdKeyAI/symbiont-sdk-js)
- **License:** Apache-2.0
- **Homepage:** https://symbiont.dev

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-thirdkeyai-symbiont-sdk-js
- Seller: https://agentstack.voostack.com/s/thirdkeyai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.