HomeConnect your first agent

Golden path

Connect your first agent

This page helps you choose the right OSuite integration path, then get a real Node or Python agent reporting live actions to your OSuite deployment.

Your agent only needs OSUITE_BASE_URL and OSUITE_API_KEY. It never needs DATABASE_URL.

1

Choose your SDK

Use the Node path below. This page keeps the first-action flow short and only switches the parts that differ by language.

Selected SDK

Node

Install command:

Node install

npm install osuite
Use the URL of your own deployed OSuite app, not https://osuite.io.
Example deployment: https://your-osuite-instance.example.com
Local development: http://localhost:3000

What the agent needs

Base URL: https://studio.osuite.ai
Workspace API key
No direct database access
Never use https://osuite.io as the agent base URL

Decision model

Start by answering four questions: who controls the runtime, who controls the execution boundary, whether approvals can pause and resume deterministically, and who should host the control plane.

Do you control the agent runtime code?

Do you control the real tool or action execution boundary?

Can the runtime pause and resume deterministically for approval?

Do you want the OSuite control plane hosted by you or by us?

Product surfaces

OSuite works through product surfaces, not one universal compatibility claim. Choose the path that matches the control points your runtime exposes.

Embedded Runtime SDK / Package

Instrument customer-controlled runtimes, tools, and orchestrators from inside the code.

Runtime Boundary Adapter

Intercept real tool or action execution at the boundary where side effects occur.

Control Plane

Run policy, approvals, replay, and evidence management as the operator system of record.

Evidence Import Surface

Import actions, traces, and logs when the external runtime cannot be governed directly.

Governance packs

These are the recommended operator-visible runtime surfaces to enable as your agent moves from first connection to governed execution.

Claude Code Hooks

Govern Bash, Edit, Write, and MultiEdit tool calls without SDK instrumentation.

Terminal Approval Channel

Approve or deny gated actions from the terminal while preserving replay evidence.

Verified Agents

Add signed actions, pairing, and stronger identity proof for governed runtimes.

Platform pathways

Code-First Single-Agent Runtime

A self-built agent where the customer owns the orchestration code and can add guard calls directly.

Governance range: Advisory Governance -> Approval-Orchestrated Governance -> Runtime-Enforced Governance

Recommended surfaces: Embedded Runtime SDK / Package + Control Plane

Self-Built Multi-Agent Runtime

An orchestrator plus governed workers where both orchestration and worker execution boundaries can be instrumented.

Governance range: Advisory Governance -> Approval-Orchestrated Governance -> Runtime-Enforced Governance

Recommended surfaces: Embedded Runtime SDK / Package + Runtime Boundary Adapter + Control Plane

Local Execution Agent

A local tool-running runtime where the customer can intercept actions directly at the execution boundary.

Governance range: Approval-Orchestrated Governance -> Runtime-Enforced Governance

Recommended surfaces: Runtime Boundary Adapter + Control Plane

Cloud Agent Platform

A hosted builder or cloud platform where governance depth depends on customer-owned control points around execution.

Governance range: Advisory Governance -> Approval-Orchestrated Governance

Recommended surfaces: Embedded Runtime SDK / Package + Control Plane + Evidence Import Surface

Enterprise Agent Suite

A packaged suite where governance often starts with policy advice or imported evidence and only selectively reaches approval orchestration.

Governance range: Evidence Import -> Advisory Governance -> Approval-Orchestrated Governance

Recommended surfaces: Evidence Import Surface + Control Plane

Low-Code / Workflow Builder

A visual or builder-style platform where governance depth depends on exposed control points.

Governance range: Evidence Import -> Advisory Governance -> Approval-Orchestrated Governance

Recommended surfaces: Evidence Import Surface + Control Plane

Closed Hosted Assistant

A black-box hosted runtime where OSuite typically sees evidence after the fact, not the true execution boundary.

Governance range: Evidence Import -> Advisory Governance

Recommended surfaces: Evidence Import Surface + Control Plane

2

Set environment variables

Set the minimum connection values in the agent runtime. The agent only talks to the OSuite HTTP API.

Node environment

OSUITE_API_KEY=<your-workspace-api-key>
OSUITE_BASE_URL=https://studio.osuite.ai

Do not use the marketing site URL. OSUITE_BASE_URL must point to your deployed OSuite app.

3

Copy the minimal starter snippet

This is the smallest real example that creates a live action in OSuite.

Node starter

// 1. node --env-file=.env demo.js
import { OSuite } from 'osuite'

const claw = new OSuite({
  apiKey: process.env.OSUITE_API_KEY,
  baseUrl: process.env.OSUITE_BASE_URL,
  agentId: 'my-first-agent',
})

await claw.guard({
  actionType: "deploy",
  riskScore: 85
})
4

Optional: enable verified agents

Basic mode works with an API key only. Verified mode adds signed actions and pairing, but it is not required for your first successful connection.

Node pairing

const privateJwk = JSON.parse(process.env.AGENT_PRIVATE_KEY_JWK);

const { pairing, pairing_url } = await claw.createPairingFromPrivateJwk(privateJwk, {
  agentName: 'My Agent',
});

console.log('Approve pairing at:', pairing_url);
await claw.waitForPairing(pairing.id);
5

Validate the connection

This confirms your instance can accept real authenticated SDK traffic and can attach proof back to /setup.

Node validator

node ./osuite-platform-intelligence/scripts/validate-integration.mjs \
  --base-url https://studio.osuite.ai \
  --api-key <api-key> \
  --full \
  --capture-setup-proof

This command assumes you downloaded and extracted osuite-platform-intelligence.zip so the validator lives in ./osuite-platform-intelligence/scripts/. If you installed it elsewhere, adjust the path.

Successful validation can feed proof back into /setup so the verification surface shows that a live SDK integration worked.

6

What success looks like

After the snippet and validator run cleanly, OSuite should start showing live evidence of the connection.

Your first action appears in the dashboard and recent activity.
The agent shows up in live OSuite traffic once it starts sending actions.
If you enable verified mode, the pairing shows as approved.
If policies are active, future risky actions can route into guard and approvals.

Hosting model

Self-host and future SaaS are deployment model choices for the OSuite control plane. That choice does not determine governance level by itself.

Self-Hosted Control Plane

Run the OSuite control plane in your own infrastructure and under your own operations model.

SaaS Control Plane

Use a OSuite-managed control plane once the hosted service is available.

Optional: chain attestation

Each tenant org can configure its own default wallet for platform attestations.

When enabled, OSuite signs each action digest with the tenant wallet and anchors it asynchronously to the configured Solana network.

Self-hosted or air-gapped deployments can use offline queue mode so actions stay signed locally until a broadcaster is available.

Common mistakes

Do not use https://osuite.io as OSUITE_BASE_URL. Use your own OSuite deployment URL.
Use your OSuite instance URL, not an API route or localhost from a different machine.
Set OSUITE_API_KEY in the agent runtime before running the snippet or validator.
Keep DATABASE_URL on the OSuite server only. The agent should never need it.

Next steps

Open dashboard Go to /setupRead full SDK docsEnable verified agents Review policies

Popular runtime-specific guides

Start from an example pathway

These guides are example pathways inside the broader capability model. Pick the runtime class and control points first, then use the nearest implementation guide below.

Claude Code

Govern Bash, Edit, Write, and MultiEdit tool calls via PreToolUse hooks. Zero SDK code required.

Dify

Wrap a Dify app with a DashClaw bridge so each run lands in action, replay, and trust surfaces.

OpenAI Agents SDK

Add guard-record-outcome governance to your OpenAI agent tools with the Node.js SDK.

LangGraph

Add a governance node to your LangGraph StateGraph with the Python SDK. Includes runnable example.

CrewAI

Govern CrewAI tool calls using the @tool decorator pattern with the Python SDK. Includes runnable example.