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

# Quickstart

> Get started with the Hive by launching your first Hive experiment in minutes.

By the end of this guide, you'll have a running Hive experiment evolving code from a demo repository.

## Launching your first experiment

<Steps>
  <Step title="Install the CLI">
    The CLI requires [Python](https://www.python.org/downloads/) 3.12 or higher. It can be installed from PyPI using the following command:

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

  <Step title="Initialize and log in">
    Initialize your user configuration:

    ```bash theme={null}
    hive init
    ```

    You will be prompted to input your organisation ID. If you do not know your organisation ID, please contact your organisation administrator.

    Then authenticate with the Hive platform:

    ```bash theme={null}
    hive login
    ```

    This will open up a browser window, where you will log in using your Hiverge credentials.

    <Frame>
      <img src="https://mintcdn.com/hiverge/KMiQig6TmYcmTUNs/images/login.png?fit=max&auto=format&n=KMiQig6TmYcmTUNs&q=85&s=9f0e61f15812f310cbe63988c93e7c7c" width="1150" height="580" data-path="images/login.png" />
    </Frame>

    If you do not have a Hiverge account yet, contact your organisation administrator to help set up an account for you.
  </Step>

  <Step title="Setup the experiment configuration">
    Hive experiments are configured using YAML files. In this quickstart we will launch an experiment using [this](https://github.com/hiverge/demo.git) demo repository. Create a file called `hive.yaml` with the following contents:

    ```yaml title="hive.yaml" theme={null}
    apiversion: v1alpha1
    experiment_name: my-demo-experiment-

    repo:
      source: https://github.com/hiverge/demo.git
      branch: main
      evaluation_script: evaluation.py
      target_code:
        - main.py

    runtime:
      num_agents: 2
      max_runtime_seconds: 1800

    sandbox:
      base_image: python:3.14-slim
      setup_script: |
        pip install -r requirements.txt
      evaluation_timeout: 60
      resources:
        cpu: "2"
        memory: 4Gi
    ```

    <Tip>
      The clone happens client-side. For private repos, consider using SSH (e.g. `git@github.com:<org>/<repo>.git`).
    </Tip>
  </Step>

  <Step title="Launch the experiment">
    You are now ready to launch your first Hive experiment by calling:

    ```bash theme={null}
    hive create exp -c hive.yaml
    ```

    <Tip>
      The `-` suffix on `experiment_name` in the YAML appends a random unique ID. We recommend using this to avoid clashes where two experiments share the same name.
    </Tip>
  </Step>

  <Step title="Manage the experiment">
    To list all Hive experiments currently running:

    ```bash theme={null}
    hive list exp
    ```

    To get details of of a running Hive experiment:

    ```bash theme={null}
    hive get exp my-demo-experiment-abc123
    ```

    You can view more details about Hive experiments by visiting the [dashboard](/gettingstarted/dashboard), which can be accessed using:

    ```bash theme={null}
    hive dashboard
    ```

    To stop a running Hive experiment:

    ```bash theme={null}
    hive stop exp my-demo-experiment-abc123
    ```
  </Step>
</Steps>

## Next steps

<CardGroup cols={1}>
  <Card title="Prepare an experiment" icon="flask-conical" href="/gettingstarted/setup">
    Learn how to prepare your own codebase to run a custom Hive experiment.
  </Card>

  <Card title="Dashboard" icon="chart-line" href="/gettingstarted/dashboard">
    View the progress and results of your running experiments.
  </Card>
</CardGroup>