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

# Quickstart

> Deploy your first ClarkOS agent in under 5 minutes

## Prerequisites

Before you begin, make sure you have:

* **Node.js 18+** installed
* **npm** package manager
* An **OpenRouter API key** (optional - demo mode works without keys)

<Tip>
  Don't have an OpenRouter key? Try **demo mode** first - it runs with an in-memory backend and sample data, no API keys required.
</Tip>

## Create Your Agent

<Steps>
  <Step title="Clone the repository">
    Clone the ClarkOS SDK:

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

    This gives you a fully-configured project with:

    * Convex backend setup
    * TypeScript configuration
    * Terminal UI (React Ink)
    * 179 passing tests
  </Step>

  <Step title="Install dependencies">
    Install the required packages:

    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Run the doctor (optional)">
    Validate your environment:

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

    This checks Node version, environment variables, and dependencies.
  </Step>

  <Step title="Try demo mode (no keys needed)">
    Start the agent with an in-memory backend:

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

    This runs the terminal UI with sample data. Great for exploring before configuring API keys.
  </Step>

  <Step title="Or configure for full mode">
    Set up your environment variables:

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

    Edit `.env.local` with your API keys:

    ```bash theme={null}
    CONVEX_URL=https://your-project.convex.cloud
    OPENROUTER_KEY=your-openrouter-key
    GEMINI_API_KEY=your-gemini-key
    ```

    Then run:

    ```bash theme={null}
    npm run dev
    ```
  </Step>
</Steps>

## Terminal UI

The SDK includes a terminal-based interface built with React Ink:

```
┌─────────────────────────────────────────────┐
│  CLARK - Autonomous Agent                    │
│  Mood: curious | Health: 78 | Routine: day  │
├─────────────────────────────────────────────┤
│      ╭──────────╮                           │
│      │  ◉    ◉  │                           │
│      │    ──    │                           │
│      ╰──────────╯                           │
└─────────────────────────────────────────────┘
```

### Keyboard Controls

| Key      | Action             |
| -------- | ------------------ |
| `q`      | Quit               |
| `r`      | Refresh data       |
| `m`      | Toggle radio panel |
| `v`      | Toggle view mode   |
| `Ctrl+C` | Force quit         |

## Your First Tick

The **tick** is the heartbeat of your agent. Every tick, your agent:

1. Loads its current state and memories
2. Gathers context (knowledge, recent activity)
3. Calculates routine from current time
4. Executes plugin hooks
5. Updates state (health drift, counters)

To trigger a tick programmatically:

```typescript theme={null}
import { Agent, ConvexBackend } from './src';

const agent = new Agent({
  backend: new ConvexBackend({ url: process.env.CONVEX_URL! }),
});

await agent.tick();
```

## Explore the API

Your agent exposes HTTP endpoints via the Convex backend:

| Endpoint          | Method | Description         |
| ----------------- | ------ | ------------------- |
| `/health`         | GET    | Health check        |
| `/state`          | GET    | Current agent state |
| `/memories`       | GET    | Query memories      |
| `/memories`       | POST   | Store a memory      |
| `/memories/core`  | GET    | Core memories       |
| `/memories/stats` | GET    | Memory statistics   |
| `/knowledge`      | GET    | Knowledge items     |
| `/logs`           | GET    | Activity logs       |

## Add a Plugin

Extend your agent with a plugin:

```typescript theme={null}
// plugins/logger.ts
import type { Plugin } from "./src/plugins";

export const loggerPlugin: Plugin = {
  name: "logger",
  version: "1.0.0",
  description: "Logs tick activity",

  init(agent) {
    console.log("Logger plugin initialized");
  },

  onTick(context) {
    console.log(`Tick executed. Mood: ${context.state.mood}, Health: ${context.state.health}`);
    console.log(`Memories loaded: ${context.memories.length}`);
  }
};
```

Register it in your agent:

```typescript theme={null}
import { Agent } from "./src";
import { ConvexBackend } from "./src/backend";
import { loggerPlugin } from "./plugins/logger";

const agent = new Agent({
  backend: new ConvexBackend({ url: process.env.CONVEX_URL! }),
  plugins: [loggerPlugin]
});

await agent.tick();
```

## Run the Tests

The SDK includes 179 tests:

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Understand Agents" icon="robot" href="/concepts/agents">
    Learn the core agent architecture.
  </Card>

  <Card title="Master Memory" icon="brain" href="/concepts/memory">
    Deep dive into the memory system.
  </Card>

  <Card title="Build Plugins" icon="plug" href="/guides/custom-plugins">
    Create custom agent capabilities.
  </Card>

  <Card title="Explore Examples" icon="code" href="/examples/basic-agent">
    See complete agent implementations.
  </Card>
</CardGroup>

<Note>
  **Need help?** Open an issue on [GitHub](https://github.com/clarkOS/clark/issues).
</Note>