Checkpoint Docs
Cookbooks

Govern: Dashboard Deploy (Managed)

Deploy a KYA-OS server with one click using Checkpoint managed deployment

Goal

Deploy a fully configured KYA-OS server using Checkpoint's managed deployment pipeline. By the end of this cookbook, you'll have:

  • A GitHub repository with production-ready KYA-OS server code
  • Automatic deployment to Cloudflare Workers
  • Agent identity (DID) registered with KnowThat.ai
  • Dashboard integration for monitoring delegations and proofs

Best for: Teams who want the fastest path to a running KYA-OS server without managing infrastructure setup.

Prerequisites

  • A Checkpoint account
  • A GitHub account with the Checkpoint GitHub App installed
  • A Cloudflare account (free tier works)

Time Estimate

15 minutes


What Gets Created

When you complete this cookbook, Checkpoint will create:

ComponentDescription
GitHub RepositoryPrivate repo with KYA-OS server source code
Cloudflare WorkerEdge deployment of your KYA-OS server
Agent IdentityEd25519 key pair with a DID (did:key:z6Mk...)
GitHub SecretsEncrypted API keys and private keys
GitHub ActionsAuto-deploy workflow on push to main
Dashboard ProjectMonitoring for delegations, proofs, sessions
KnowThat.ai ProfilePublic agent profile (optional)

Steps

Connect GitHub

GitHub connects inline, the first time you need it — there's no separate integrations settings page:

  1. Go to your Checkpoint dashboard and open Deploy
  2. Start a new deployment (see the next step); its Connections panel prompts you to Connect GitHub before it will let you continue
  3. Install the Checkpoint GitHub App to your account or organization
  4. Select which repositories to grant access (or all repositories)

Checkpoint needs repository access to create the KYA-OS server repo and configure secrets.

Start the Deployment Wizard

  1. In your dashboard, navigate to ProjectsNew Project
  2. Select Govern (KYA-OS Server)
  3. Click Deploy KYA-OS Server

You'll see the deployment configuration form.

Configure Your Server

Fill in the deployment configuration:

FieldRequiredDescriptionExample
Project NameYesBecomes GitHub repo name. Lowercase, alphanumeric, hyphens only.my-ai-assistant
Agent NameYesHuman-readable display name for the agentMy AI Assistant
Agent DescriptionNoPurpose of the agent (shown in consent screens)Helps users manage their calendar

Optional Integrations:

FieldRequiredDescription
Cloudflare API TokenNoFor automatic deployment (can add later)
Cloudflare Account IDNoRequired with API token

Don't have Cloudflare credentials yet? Skip them now and add them later as GitHub Secrets.

Watch the Deployment Pipeline

Click Deploy to start the pipeline. You'll see real-time progress through 10 steps:

  1. Verify GitHub — Confirms the GitHub App installation
  2. Check Repository Name — Confirms the repo name is available
  3. Create Project — Creates the Checkpoint project for monitoring
  4. Generate API Key — Creates the encrypted API key for the worker
  5. Register Identity — Generates the DID and registers it with KnowThat.ai (reports skipped only when reputation is opted out or no identity exists; a registration failure with reputation enabled reports an error)
  6. Scaffold Files — Generates KYA-OS server source code
  7. Create Repository — Creates the private GitHub repository
  8. Commit Files — Pushes code to the repository
  9. Add Secrets — Configures GitHub Secrets
  10. Deploy to Cloudflare — Deploys the worker (skipped when Cloudflare credentials aren't connected yet)

Each step shows success/failure status. The entire process takes 1-2 minutes.

Review Your New Server

After successful deployment, you'll see:

Links:

  • GitHub Repository URL — Your new repo with full source code
  • Agent DID — Your agent's decentralized identifier
  • KTA Claim URL — Claim your agent profile on KnowThat.ai

Next Actions:

  • Deploy to Cloudflare — One-click deployment button
  • View Repository — Open GitHub to explore the code

Click Deploy to Cloudflare to deploy the worker, or push a commit to trigger the GitHub Actions workflow.

Add Cloudflare Credentials (if skipped)

If you didn't provide Cloudflare credentials during setup:

  1. Go to Cloudflare Dashboard

  2. Navigate to Your Profile → API Tokens

  3. Click Create Token

  4. Use the Edit Cloudflare Workers template

  5. Copy the token

  6. In GitHub, go to your new repository

  7. Navigate to Settings → Secrets and variables → Actions

  8. Add two secrets:

    • CLOUDFLARE_API_TOKEN — Your Cloudflare token
    • CLOUDFLARE_ACCOUNT_ID — Your Cloudflare account ID (found in dashboard URL)
  9. Push a commit or manually trigger the workflow to deploy

Configure Tool Protection

Define which tools require authorization and what scopes they need:

  1. In your Checkpoint dashboard, select your new project
  2. Go to Policy → Auth
  3. Create a protection (an OAuth, credential, or consent-only auth method plus the scopes it grants)
  4. In the tool coverage table, assign that protection as the owner of each tool it should protect

Example assignments:

ToolOwning protection grantsRequires delegation
read_filefiles:readYes
send_emailemail:sendYes

Tools left unassigned stay open (no delegation required). Tool discovery and manual add/remove remain on the legacy surface at /dashboard/{orgId}/{projectId}/control-access/tools (legacy surface, moving to Access).

Test Your Server

Check the Well-Known Endpoints:

# Get agent DID document
curl https://your-worker.your-account.workers.dev/.well-known/did.json

# Get agent metadata
curl https://your-worker.your-account.workers.dev/.well-known/agent.json

Test Tool Execution (without delegation — should fail):

curl -X POST https://your-worker.your-account.workers.dev/tools/read_file \
  -H "Content-Type: application/json" \
  -d '{"path": "/etc/passwd"}'

# Expected: 401 Unauthorized - Delegation required

Understanding the Generated Code

Your repository contains:

my-ai-assistant/
├── src/
│   ├── index.ts               # Worker entry point (createMCPIApp)
│   ├── agent.ts               # Durable Object agent class (MCPIAgent)
│   ├── mcpi-runtime-config.ts # Runtime config + tool registry
│   └── tools/
│       └── greet.ts           # Example tool definition
├── wrangler.toml              # Cloudflare Workers config (DO + KV bindings)
├── package.json
├── tsconfig.json
├── .dev.vars.example          # Local secrets template
├── .gitignore
├── README.md
└── .github/
    └── workflows/
        └── deploy.yml         # Auto-deploy on push

Key file: src/index.ts

import { createMCPIApp } from '@kya-os/mcp-i-cloudflare';
import { MCPIAgent } from './agent';
import { getRuntimeConfig } from './mcpi-runtime-config';

export default createMCPIApp({
  AgentClass: MCPIAgent,
  getRuntimeConfig,
});

// Export Durable Object class for Cloudflare Workers binding
export { MCPIAgent };
// Separate SQLite audit producer; it does not share authorization/session state.
export { AuditProducer } from '@kya-os/mcp-i-cloudflare';

createMCPIApp builds the whole worker: MCP transport, well-known identity endpoints, consent pages, and delegation checks. src/agent.ts extends MCPICloudflareAgent and registers every tool from the config with automatic proof generation.

Key file: src/mcpi-runtime-config.ts

import { defineConfig, type CloudflareRuntimeConfig } from '@kya-os/mcp-i-cloudflare';
import type { CloudflareEnv } from '@kya-os/mcp-i-cloudflare';
import { greetTool } from './tools/greet';

export function getRuntimeConfig(env: CloudflareEnv): CloudflareRuntimeConfig {
  const environment = (env.MCPI_ENV || env.ENVIRONMENT || 'development') as
    | 'development'
    | 'production';

  const proofingConfig = env.AGENTSHIELD_API_KEY
    ? {
        enabled: true,
        batchQueue: {
          destinations: [
            {
              type: 'agentshield' as const,
              apiKey: env.AGENTSHIELD_API_KEY,
              apiUrl: env.AGENTSHIELD_API_URL || 'https://kya.vouched.id',
            },
          ],
        },
      }
    : undefined;

  return defineConfig({
    environment,
    proofing: proofingConfig,
    vars: {
      ENVIRONMENT: environment,
      AGENTSHIELD_API_KEY: env.AGENTSHIELD_API_KEY,
      AGENTSHIELD_API_URL: env.AGENTSHIELD_API_URL,
      AGENTSHIELD_PROJECT_ID: env.AGENTSHIELD_PROJECT_ID,
    },
  });
}

export function getTools() {
  return [greetTool];
}

GitHub repository secrets created (visible under Settings → Secrets in the generated repo):

SecretPurpose
MCP_IDENTITY_PRIVATE_KEYAgent's Ed25519 private key
AGENTSHIELD_API_KEYWorker → Checkpoint API
OAUTH_ENCRYPTION_SECRETEncrypts stored OAuth tokens
CLOUDFLARE_API_TOKENDeployment (only if you provided your own token)

Cloudflare worker secrets set during deploy (on the worker itself, not in GitHub):

SecretPurpose
AGENTSHIELD_PROJECT_IDThe worker's Checkpoint project
KTA_REGISTRATIONLets the proof service notify the reputation engine
MCP_SERVER_URLWorker URL, used by consent/approval redirects

AGENTSHIELD_API_KEY is the KYA-OS worker naming convention for the same dashboard API key the Checkpoint SDKs read as CHECKPOINT_API_KEY — two env names, one key. See Credentials for where the key comes from and which name each plane reads.


Adding Custom Tools

Extend your server with custom tools:

// src/tools/calendar.ts
import type { ToolDefinition } from '@kya-os/mcp-i-cloudflare';

export const getCalendarEventsTool: ToolDefinition = {
  name: 'get_calendar_events',
  description: 'Retrieves upcoming calendar events',
  inputSchema: {
    type: 'object',
    properties: {
      days: {
        type: 'number',
        description: 'Number of days to look ahead',
        default: 7,
      },
    },
  },
  handler: async (args: { days?: number }) => {
    const { days = 7 } = args;

    // Your calendar API integration
    const events = await fetchCalendarEvents(days);

    return {
      content: [{ type: 'text', text: JSON.stringify(events) }],
    };
  },
};

Register the tool in src/mcpi-runtime-config.ts:

import { getCalendarEventsTool } from './tools/calendar';

export function getTools() {
  return [greetTool, getCalendarEventsTool];
}

Scope requirements (for example calendar:read) are not declared on the tool — assign them in the dashboard under Policy → Auth (see Configure Tool Protection above), and the runtime enforces the delegation before the handler runs.


Verify It's Working

Dashboard Verification

  1. Go to Delegations — See active delegations
  2. Go to Proofs — Monitor proof verification activity
  3. Go to Analytics — View request patterns

API Health Check

curl https://your-worker.your-account.workers.dev/health
# Should return: OK

KnowThat.ai Profile

Visit your agent's public profile:

https://knowthat.ai/agents/your-agent-slug

Troubleshooting

Deployment Pipeline Fails

StepCommon CauseFix
Verify GitHubApp not installedReinstall GitHub App
Create RepositoryRepo name existsChoose a different name
Add SecretsInsufficient permissionsCheck GitHub App permissions

Cloudflare Deployment Fails

  • Invalid API token — Regenerate token with correct permissions
  • Invalid account ID — Check dashboard URL for correct ID
  • Worker name conflict — Edit wrangler.toml to change worker name

Identity Not Resolving

# Check DID document
curl https://your-worker.your-account.workers.dev/.well-known/did.json

If empty or error, check that MCP_IDENTITY_PRIVATE_KEY secret is set correctly.


What You Learned

  • How to deploy a KYA-OS server with managed infrastructure
  • What gets created (repo, worker, identity, secrets)
  • How to configure tool protection
  • How to extend with custom tools
  • How to verify the deployment

Next Steps

GoalNext Cookbook
Full control over infrastructureSelf-Host (BYOK)
Add to existing MCP serverMCP to KYA-OS Migration
Configure auth methodsAuth Methods Reference
Understand delegationsDelegations