> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cogos.natureselect.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get CogOS up and running in 5 minutes.

## 1. Clone the repository

```bash theme={null}
git clone https://github.com/cogos-ai/CogOS.git
cd CogOS
```

## 2. Create environment & install dependencies

```bash theme={null}
# Create and activate a Python 3.10 conda environment
conda create -n cogos python=3.10 -y
conda activate cogos

# Install dependencies
pip install -r requirements.txt

# Install CogOS as a package (registers the `cogos` CLI command)
pip install -e .
```

<Tip>
  For development mode with testing and linting tools, run `pip install -e ".[dev]"` instead.
</Tip>

## 3. Initialize & Configure

```bash theme={null}
# Initialize the project (generates config + template files)
cogos init
```

This creates the files CogOS needs to run:

| File                      | Purpose                                                      |
| ------------------------- | ------------------------------------------------------------ |
| `configs/cogos.yaml`      | **Your config — edit this** to set LLM provider, model, etc. |
| `templates/general.json`  | Built-in general template (editable)                         |
| `templates/roleplay.json` | Built-in roleplay template (editable)                        |

Then configure your LLM provider (pick one):

<Tabs>
  <Tab title="YAML Config">
    Open `configs/cogos.yaml` and set `api_key`, `model`, `base_url`:

    ```yaml theme={null}
    llm:
      api_key: "your-api-key"
      model: "gpt-4o"
      base_url: "https://api.openai.com/v1"
    ```
  </Tab>

  <Tab title="Environment Variables">
    ```bash theme={null}
    cp .env.example .env
    # Edit .env: fill in API_KEY, MODEL, BASE_URL
    ```

    Environment variables override YAML config values.
  </Tab>
</Tabs>

## 4. Verify installation

These examples run without an API key:

```bash theme={null}
# Schema operations
python examples/01_basic_schema.py

# Input converters
python examples/03_converters.py
```

## 5. Run with LLM

Requires a configured API key:

```bash theme={null}
# Full chat with memory
python examples/02_chat_with_memory.py

# Or start the web server
cogos serve
# Open http://localhost:8000

# Or run as a background daemon
cogos serve start
cogos serve status
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Python API" icon="python" href="/usage/python-api">
    Learn how to use CogOS programmatically.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/interfaces/cli">
    Explore the full command-line interface.
  </Card>

  <Card title="Service Management" icon="server" href="/interfaces/service-management">
    Run CogOS as a daemon with auto-start on boot.
  </Card>

  <Card title="Schema Templates" icon="file-code" href="/usage/schema-templates">
    Use preset templates or create your own.
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration">
    Customize LLM provider, persistence, and more.
  </Card>
</CardGroup>