Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.clarkos.dev/llms.txt

Use this file to discover all available pages before exploring further.

ClarkOS agents run on Convex serverless infrastructure. This guide covers deploying your agent backend and optional frontend.

Example Agent

See the reference implementation on GitHub

​
Quick Deploy

1

Deploy to Convex

npx convex deploy
You’ll get a production URL like https://your-project.convex.cloud
2

Set Environment Variables

In the Convex dashboard, add your environment variables:
OPENROUTER_KEY=sk-or-...
GEMINI_API_KEY=AIza...
TICK_TOKEN=your-secure-token
3

Verify Deployment

Test the health endpoint:
curl https://your-project.convex.cloud/health
That’s it. Your agent is now running with scheduled ticks via Convex crons.

​
Environment Variables

​
Required

VariableDescription
OPENROUTER_KEYLLM API key from OpenRouter
TICK_TOKENAuth token for tick endpoint (generate with openssl rand -hex 32)

​
Optional

VariableDefaultDescription
GEMINI_API_KEY-Google AI key for embeddings (free tier)
WRITE_TOKENSame as TICK_TOKENAuth for write operations

​
Frontend Deployment (Optional)

If you build a web frontend for your agent, deploy it to Vercel: 
# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

# Set the Convex URL
vercel env add NEXT_PUBLIC_CONVEX_URL
The example agent includes a terminal UI built with Ink. A web frontend is not required—the agent runs autonomously via the Convex backend.

​
Scheduled Ticks

Crons are defined in convex/crons.ts and deploy automatically: 
import { cronJobs } from "convex/server";
import { api } from "./_generated/api";

const crons = cronJobs();
crons.interval("tick", { minutes: 5 }, api.tick.runTick);

export default crons;
Verify crons are running in the Convex dashboard under Schedules.

​
Manual Tick

Trigger a tick manually: 
curl -X POST https://your-project.convex.cloud/tick \
  -H "Authorization: Bearer YOUR_TICK_TOKEN"

​
Monitoring

View logs and metrics in the Convex dashboard:
  • Logs - Real-time function execution logs
  • Data - Browse your agent’s state, memories, and knowledge
  • Schedules - Monitor cron job execution

​
Health Check

curl https://your-project.convex.cloud/health

{
  "status": "ok",
  "lastTick": 1706400000000,
  "health": 78
}

​
Security

  • Generate secure tokens: openssl rand -hex 32
  • Never commit tokens to git
  • Use Convex environment variables for secrets
  • The /tick endpoint requires TICK_TOKEN authentication

​
Next Steps

Testing

Test your agent locally

Custom Plugins

Extend agent capabilities