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:
| Component | Description |
|---|---|
| GitHub Repository | Private repo with KYA-OS server source code |
| Cloudflare Worker | Edge deployment of your KYA-OS server |
| Agent Identity | Ed25519 key pair with a DID (did:key:z6Mk...) |
| GitHub Secrets | Encrypted API keys and private keys |
| GitHub Actions | Auto-deploy workflow on push to main |
| Dashboard Project | Monitoring for delegations, proofs, sessions |
| KnowThat.ai Profile | Public agent profile (optional) |
Steps
Connect GitHub
GitHub connects inline, the first time you need it — there's no separate integrations settings page:
- Go to your Checkpoint dashboard and open Deploy
- Start a new deployment (see the next step); its Connections panel prompts you to Connect GitHub before it will let you continue
- Install the Checkpoint GitHub App to your account or organization
- 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
- In your dashboard, navigate to Projects → New Project
- Select Govern (KYA-OS Server)
- Click Deploy KYA-OS Server
You'll see the deployment configuration form.
Configure Your Server
Fill in the deployment configuration:
| Field | Required | Description | Example |
|---|---|---|---|
| Project Name | Yes | Becomes GitHub repo name. Lowercase, alphanumeric, hyphens only. | my-ai-assistant |
| Agent Name | Yes | Human-readable display name for the agent | My AI Assistant |
| Agent Description | No | Purpose of the agent (shown in consent screens) | Helps users manage their calendar |
Optional Integrations:
| Field | Required | Description |
|---|---|---|
| Cloudflare API Token | No | For automatic deployment (can add later) |
| Cloudflare Account ID | No | Required 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:
- Verify GitHub — Confirms the GitHub App installation
- Check Repository Name — Confirms the repo name is available
- Create Project — Creates the Checkpoint project for monitoring
- Generate API Key — Creates the encrypted API key for the worker
- Register Identity — Generates the DID and registers it with KnowThat.ai (reports
skippedonly when reputation is opted out or no identity exists; a registration failure with reputation enabled reports an error) - Scaffold Files — Generates KYA-OS server source code
- Create Repository — Creates the private GitHub repository
- Commit Files — Pushes code to the repository
- Add Secrets — Configures GitHub Secrets
- 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:
-
Go to Cloudflare Dashboard
-
Navigate to Your Profile → API Tokens
-
Click Create Token
-
Use the Edit Cloudflare Workers template
-
Copy the token
-
In GitHub, go to your new repository
-
Navigate to Settings → Secrets and variables → Actions
-
Add two secrets:
CLOUDFLARE_API_TOKEN— Your Cloudflare tokenCLOUDFLARE_ACCOUNT_ID— Your Cloudflare account ID (found in dashboard URL)
-
Push a commit or manually trigger the workflow to deploy
Configure Tool Protection
Define which tools require authorization and what scopes they need:
- In your Checkpoint dashboard, select your new project
- Go to Policy → Auth
- Create a protection (an OAuth, credential, or consent-only auth method plus the scopes it grants)
- In the tool coverage table, assign that protection as the owner of each tool it should protect
Example assignments:
| Tool | Owning protection grants | Requires delegation |
|---|---|---|
read_file | files:read | Yes |
send_email | email:send | Yes |
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.jsonTest 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 requiredUnderstanding 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 pushKey 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):
| Secret | Purpose |
|---|---|
MCP_IDENTITY_PRIVATE_KEY | Agent's Ed25519 private key |
AGENTSHIELD_API_KEY | Worker → Checkpoint API |
OAUTH_ENCRYPTION_SECRET | Encrypts stored OAuth tokens |
CLOUDFLARE_API_TOKEN | Deployment (only if you provided your own token) |
Cloudflare worker secrets set during deploy (on the worker itself, not in GitHub):
| Secret | Purpose |
|---|---|
AGENTSHIELD_PROJECT_ID | The worker's Checkpoint project |
KTA_REGISTRATION | Lets the proof service notify the reputation engine |
MCP_SERVER_URL | Worker 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
- Go to Delegations — See active delegations
- Go to Proofs — Monitor proof verification activity
- Go to Analytics — View request patterns
API Health Check
curl https://your-worker.your-account.workers.dev/health
# Should return: OKKnowThat.ai Profile
Visit your agent's public profile:
https://knowthat.ai/agents/your-agent-slugTroubleshooting
Deployment Pipeline Fails
| Step | Common Cause | Fix |
|---|---|---|
| Verify GitHub | App not installed | Reinstall GitHub App |
| Create Repository | Repo name exists | Choose a different name |
| Add Secrets | Insufficient permissions | Check 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.tomlto change worker name
Identity Not Resolving
# Check DID document
curl https://your-worker.your-account.workers.dev/.well-known/did.jsonIf 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
| Goal | Next Cookbook |
|---|---|
| Full control over infrastructure | Self-Host (BYOK) |
| Add to existing MCP server | MCP to KYA-OS Migration |
| Configure auth methods | Auth Methods Reference |
| Understand delegations | Delegations |