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

# Installation

> Set up ClarkOS in your project

## Clone the Repository

The fastest way to get started:

```bash theme={null}
git clone https://github.com/clarkOS/clark my-agent
cd my-agent/example/convex
npm install
```

This gives you a complete project with:

* Convex backend schema and functions
* TypeScript source code
* Terminal UI (React Ink)
* 179 passing tests
* Environment template

## Quick Validation

Run the doctor script to check your setup:

```bash theme={null}
npm run doctor
```

This validates Node version, dependencies, and environment configuration.

## Try Demo Mode

No API keys? No problem. Run with an in-memory backend:

```bash theme={null}
npm run demo
```

This starts the terminal UI with sample data, letting you explore the framework before configuring external services.

## Environment Variables

Copy the template:

```bash theme={null}
cp .env.example .env.local
```

Edit `.env.local`:

```bash theme={null}
# Required for full mode
CONVEX_URL=https://your-project.convex.cloud
OPENROUTER_KEY=your-openrouter-api-key
GEMINI_API_KEY=your-gemini-key

# Optional - auth tokens
TICK_TOKEN=secure-random-token
WRITE_TOKEN=secure-random-token
```

### Getting API Keys

| Service        | Purpose           | URL                                                       |
| -------------- | ----------------- | --------------------------------------------------------- |
| **Convex**     | Backend           | Run `npx convex dev` and copy deployment URL              |
| **OpenRouter** | LLM               | [openrouter.ai](https://openrouter.ai)                    |
| **Gemini**     | Embeddings (free) | [aistudio.google.com](https://aistudio.google.com/apikey) |

## Project Structure

```
clark/
├── README.md
├── docs/                    # Audit documentation
├── scripts/
│   └── doctor.js            # Preflight validation
└── example/
    └── convex/              # Reference implementation
        ├── .env.example     # Environment template
        ├── package.json
        ├── convex/          # Convex backend
        │   ├── schema.ts    # Database schema
        │   ├── http.ts      # HTTP endpoints
        │   ├── state.ts     # State queries/mutations
        │   ├── memories.ts  # Memory operations
        │   ├── knowledge.ts # Knowledge operations
        │   └── logs.ts      # Logging
        ├── src/
        │   ├── cli.tsx      # CLI entry point
        │   ├── core/        # Agent runtime, tick system
        │   ├── memory/      # Memory store, deduplication
        │   ├── knowledge/   # Knowledge base
        │   ├── plugins/     # Plugin system
        │   ├── llm/         # LLM & embedding clients
        │   ├── services/    # Background services
        │   ├── templates/   # Prompt templates
        │   └── ui/          # Terminal UI (Ink + React)
        └── tests/           # Jest tests (179 total)
```

## Verify Installation

Start the development server:

```bash theme={null}
npm run dev
```

You should see the terminal UI with the agent status.

### Check API Endpoints

If using the Convex backend:

```bash theme={null}
# Health check
curl http://localhost:3001/health

# Expected response:
# {"ok":true,"service":"clark-agent","now":...,"lastTick":...}
```

```bash theme={null}
# Agent state
curl http://localhost:3001/state
```

## Run Tests

Validate everything works:

```bash theme={null}
npm test
```

All 179 tests should pass.

## Set Up Your Own Convex Project

To use your own Convex deployment:

```bash theme={null}
# Install Convex CLI
npm install -g convex

# Initialize new project
npx convex init

# Start dev server
npx convex dev
```

Then update `CONVEX_URL` in `.env.local` with your new deployment URL.

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" href="/quickstart">
    Build your first agent
  </Card>

  <Card title="Core Concepts" href="/concepts/agents">
    Understand the architecture
  </Card>
</CardGroup>