Skip to main content
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