Deployment - ClarkOS

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

Deploy to Convex

npx convex deploy

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

Set Environment Variables

In the Convex dashboard, add your environment variables:

OPENROUTER_KEY=sk-or-...
GEMINI_API_KEY=AIza...
TICK_TOKEN=your-secure-token

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

Variable	Description
`OPENROUTER_KEY`	LLM API key from OpenRouter
`TICK_TOKEN`	Auth token for tick endpoint (generate with `openssl rand -hex 32`)

Optional

Variable	Default	Description
`GEMINI_API_KEY`	-	Google AI key for embeddings (free tier)
`WRITE_TOKEN`	Same as TICK_TOKEN	Auth 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

Example Agent

​Quick Deploy

​Environment Variables

​Required

​Optional

​Frontend Deployment (Optional)

​Scheduled Ticks

​Manual Tick

​Monitoring

​Health Check

​Security

​Next Steps

Testing

Custom Plugins

Quick Deploy

Environment Variables

Required

Optional

Frontend Deployment (Optional)

Scheduled Ticks

Manual Tick

Monitoring

Health Check

Security

Next Steps