Deploying a KYA-OS Server

Overview

Checkpoint provides three ways to run a KYA-OS server:

This page covers Dashboard Deploy and Self-Host (BYOK) below. For managed hosting where Checkpoint runs the agent process for you instead, see Molti.

All three register with Checkpoint for delegation verification, proof auditing, and dashboard monitoring.

Dashboard Deploy

The fastest path to a running KYA-OS server. Checkpoint scaffolds a complete project, creates a GitHub repository, and configures deployment.

Prerequisites

• A Checkpoint account with a GitHub App connection
• A Cloudflare account (for Workers deployment)

Deployment Flow

1. Start Deployment

Open Servers in the dashboard and choose a template: Verifier (an authorization host), OpenAPI import, or Blank Canvas. OpenAPI import first adds an Import your API step:

Then fill in the configuration form:

The rest of this section follows Self-host with Cloudflare Workers, which creates the GitHub repository and the Worker described below. When the form is complete, click Review deploy: the review screen lists everything the deploy will create, and Approve & deploy starts it.

2. Watch Deployment Progress

After submitting, Checkpoint executes a deployment pipeline with real-time progress. The steps, in order:

1. Verify GitHub (github_verify): Confirms the GitHub App installation
2. Check repo name (repo_check): Confirms the repository name is available
3. Create Project (project_create): Creates (or reuses) the Checkpoint project for monitoring
4. Generate API Key (api_key): Creates an encrypted API key for the worker
5. Register Identity (kta_register): Registers the agent DID with KnowThat.ai for reputation tracking (with reputation disabled it still runs as a shadow registration for agent tracking, reporting skipped only when tracking is unavailable or the server has no identity; runs before or after scaffolding depending on that setting)
6. Scaffold Files (scaffold): Generates the KYA-OS server source code
7. Create Repository (repo_create): Creates a private GitHub repository
8. Commit Files (commit_files): Pushes the scaffolded code to the repository
9. Add Secrets (add_secrets): Configures GitHub Secrets for deployment
10. Deploy to Cloudflare (cloudflare_deploy): Deploys the worker (skipped when Cloudflare isn't connected)

3. Deploy to Cloudflare

After the pipeline completes, you'll see:

• GitHub Repository URL: Link to your new repo with the full KYA-OS server source
• Agent DID: Your agent's decentralized identifier
• Deploy to Cloudflare button: One-click Cloudflare Workers deployment
• KTA Claim URL: Claim your agent's profile on KnowThat.ai (if reputation was enabled)

Click Deploy to Cloudflare to deploy the worker, or push changes to the repo to trigger the auto-deploy GitHub Actions workflow.

What Gets Created

GitHub Repository:

my-mcp-server/
├── src/
│   └── index.ts          # KYA-OS server entry point
├── wrangler.toml          # Cloudflare Workers configuration
├── package.json
├── tsconfig.json
└── .github/
    └── workflows/
        └── deploy.yml    # Auto-deploy on push to main

GitHub Secrets (encrypted):

Cloudflare Worker secrets (set on the worker during the deploy step): CHECKPOINT_API_KEY, CHECKPOINT_PROJECT_ID (the project's friendly ID), MCP_IDENTITY_PRIVATE_KEY, OAUTH_ENCRYPTION_SECRET, KTA_REGISTRATION (lets the proof service notify the reputation engine), and MCP_SERVER_URL (the worker's public URL, required for consent-flow redirects).

Checkpoint Dashboard:

• A project entry for monitoring delegations, proofs, and sessions
• An API key linked to the project

KnowThat.ai (optional):

• Agent DID registered for reputation tracking
• Public profile page at knowthat.ai/agents/{slug}

Auto-Deploy with GitHub Actions

The generated repository includes a GitHub Actions workflow that deploys to Cloudflare Workers on every push to main (and on manual workflow_dispatch). Abridged:

# .github/workflows/deploy.yml
on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install
      - name: Deploy to Cloudflare
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          secrets: |
            MCP_IDENTITY_PRIVATE_KEY
            OAUTH_ENCRYPTION_SECRET
            CHECKPOINT_API_KEY
        env:
          MCP_IDENTITY_PRIVATE_KEY: ${{ secrets.MCP_IDENTITY_PRIVATE_KEY }}
          OAUTH_ENCRYPTION_SECRET: ${{ secrets.OAUTH_ENCRYPTION_SECRET }}
          CHECKPOINT_API_KEY: ${{ secrets.CHECKPOINT_API_KEY }}

If you chose Clone to repository, add CLOUDFLARE_API_TOKEN to your repository's Settings → Secrets and variables → Actions before the workflow can deploy. Checkpoint writes that secret itself only for a Cloudflare Workers deploy that used your own API token.

Self-Host (BYOK)

For full control over your KYA-OS server infrastructure, use the KYA-OS packages directly. You'll need a Project ID and API key: see Credentials for where to find them and which environment variable name applies to this plane.

Option 1: Cloudflare Workers

npx @kya-os/create-mcpi-app my-server

This scaffolds a Cloudflare Workers project with KYA-OS built in. Configure and deploy with wrangler:

import { MCPICloudflareServer } from '@kya-os/mcp-i-cloudflare';
import { defineConfig } from '@kya-os/mcp-i-cloudflare';

export function getRuntimeConfig(env: CloudflareEnv) {
  return defineConfig({
    vars: {
      ENVIRONMENT: env.ENVIRONMENT || 'production',
      CHECKPOINT_API_KEY: env.CHECKPOINT_API_KEY,
    },
    admin: {
      enabled: true,
      apiKey: env.ADMIN_API_KEY,
    },
  });
}

export default {
  async fetch(request: Request, env: CloudflareEnv, ctx: ExecutionContext) {
    const server = new MCPICloudflareServer({
      env,
      config: getRuntimeConfig(env),
    });
    return server.handleRequest(request, ctx);
  },
};

Required Environment Variables:

KV Namespaces (Cloudflare):

Only NONCE_CACHE is a required binding: the others are optional and unlock the listed features.

Option 2: Node.js / Express

Add KYA-OS verification to any Node.js server using the middleware:

npm install @kya-os/bouncer-middleware

See Migrating MCP to KYA-OS for the full Express integration guide.

Option 3: Node.js Runtime

For advanced use cases, use the core KYA-OS runtime directly:

npm install @kya-os/mcp-i

import { createMCPIRuntime } from '@kya-os/mcp-i';

const runtime = createMCPIRuntime({
  identity: {
    environment: 'production',
  },
  wellKnown: {
    environment: 'production',
    baseUrl: 'https://my-server.example.com',
  },
});
await runtime.initialize();

// Get agent identity
const identity = await runtime.getIdentity();
console.log(`Agent DID: ${identity.did}`);

// Execute a tool through the runtime: a proof is generated
// automatically and stored for out-of-band retrieval
const result = await runtime.processToolCall('my_tool', args, async (toolArgs) => {
  return handleMyTool(toolArgs);
});

Package Hierarchy

@kya-os/contracts              → Shared types and schemas
    ↓
@kya-os/mcp-i-core             → Platform-agnostic runtime (providers)
    ↓
@kya-os/mcp-i                  → Node.js runtime
@kya-os/mcp-i-cloudflare       → Cloudflare Workers adapter
    ↓
@kya-os/bouncer-middleware      → Express middleware (verification only)

Session Timing

Deployed servers read a session block from the same project config endpoint that serves tool protection (GET /api/v1/bouncer/projects/{projectId}/config, see Tool Protection):

This setting is operator-configurable per project via PUT on the same endpoint. It applies to the deployed KYA-OS server runtime, not to the gateway signature checks described in Enforcement.

Identity Management

Every KYA-OS server has an agent identity: an Ed25519 key pair that produces a DID.

DID Format

did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK

The DID is derived from the agent's public key and serves as its persistent identifier across sessions and services.

Identity Storage

• Dashboard Deploy: Identity is generated during deployment and stored as a GitHub Secret (MCP_IDENTITY_PRIVATE_KEY)
• Self-Host: Identity is stored locally in .mcpi/identity.json (add to .gitignore)

Scaffolding with npx @kya-os/create-mcpi-app (see Option 1: Cloudflare Workers above) generates this identity automatically. To generate a fresh identity (new DID and keys) in an existing scaffolded project, run from the project directory:

npx @kya-os/create-mcpi-app regenerate-identity

For Node.js projects this writes .mcpi/identity.json; for Cloudflare projects it updates wrangler.toml and .dev.vars. Generate Agent Identity covers the full walkthrough, including the programmatic path via the generateIdentity helper.

Well-Known Endpoints

KYA-OS servers expose discovery endpoints:

Reputation (KnowThat.ai)

Agents deployed via the dashboard can optionally register with KnowThat.ai for reputation tracking. Reputation scores (0–100) reflect an agent's trustworthiness based on its history of verified interactions.

Next Steps

• Migrating MCP to KYA-OS: Add KYA-OS to an existing server
• Authentication Methods: Choose how users authorize agents
• Tool Protection: Define per-tool scope requirements
• Consent Flows: Customize the consent experience