> ## 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.

# Deployment

> Deploy your ClarkOS agent to production

ClarkOS agents run on [Convex](https://convex.dev) serverless infrastructure. This guide covers deploying your agent backend and optional frontend.

<Card title="Example Agent" icon="github" href="https://github.com/clarkOS/clark/tree/main/example/convex">
  See the reference implementation on GitHub
</Card>

## Quick Deploy

<Steps>
  <Step title="Deploy to Convex">
    ```bash theme={null}
    npx convex deploy
    ```

    You'll get a production URL like `https://your-project.convex.cloud`
  </Step>

  <Step title="Set Environment Variables">
    In the [Convex dashboard](https://dashboard.convex.dev), add your environment variables:

    ```
    OPENROUTER_KEY=sk-or-...
    GEMINI_API_KEY=AIza...
    TICK_TOKEN=your-secure-token
    ```
  </Step>

  <Step title="Verify Deployment">
    Test the health endpoint:

    ```bash theme={null}
    curl https://your-project.convex.cloud/health
    ```
  </Step>
</Steps>

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](https://openrouter.ai)                |
| `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](https://vercel.com):

```bash theme={null}
# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

# Set the Convex URL
vercel env add NEXT_PUBLIC_CONVEX_URL
```

<Note>
  The example agent includes a terminal UI built with [Ink](https://github.com/vadimdemedes/ink). A web frontend is not required—the agent runs autonomously via the Convex backend.
</Note>

## Scheduled Ticks

Crons are defined in `convex/crons.ts` and deploy automatically:

```typescript theme={null}
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:

```bash theme={null}
curl -X POST https://your-project.convex.cloud/tick \
  -H "Authorization: Bearer YOUR_TICK_TOKEN"
```

## Monitoring

View logs and metrics in the [Convex dashboard](https://dashboard.convex.dev):

* **Logs** - Real-time function execution logs
* **Data** - Browse your agent's state, memories, and knowledge
* **Schedules** - Monitor cron job execution

### Health Check

```bash theme={null}
curl https://your-project.convex.cloud/health
```

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Testing" href="/guides/testing">
    Test your agent locally
  </Card>

  <Card title="Custom Plugins" href="/guides/custom-plugins">
    Extend agent capabilities
  </Card>
</CardGroup>