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

# Freesona Quickstart: Get Your Bot Online Fast

> Set up a self-hosted Freesona bot from scratch: create a Discord application, configure your .env, and make your first command work.

By the end of this guide, you'll have a Freesona bot online in your Discord server: responding to `~ping`, replying to messages in your designated chat channel, and running on your own infrastructure with your own AI provider key.

<Steps>
  <Step title="Create a Discord Application and Bot">
    Go to the [Discord Developer Portal](https://discord.com/developers/applications) and create a new application.

    1. Click **New Application**, give it a name (this becomes your bot's display name), and save.
    2. In the left sidebar, select **Bot**.
    3. Under **Privileged Gateway Intents**, enable all three required intents:
       * **MESSAGE CONTENT INTENT** — required for prefix commands and reading message text
       * **GUILDS INTENT** — required for server awareness
       * **GUILD MEMBERS INTENT** — required for member-related features and moderation
    4. Click **Reset Token**, confirm, and copy the token somewhere safe. This is your `BOT_TOKEN`.

    **Invite the bot to your server:**

    In the left sidebar, go to **OAuth2 → URL Generator**. Under **Scopes**, select `bot` and `applications.commands`. Under **Bot Permissions**, enable:

    * Send Messages
    * Embed Links
    * Attach Files
    * Read Message History
    * Manage Messages *(required for the moderation module)*

    Copy the generated URL and open it in your browser to add the bot to your server.

    <Tip>
      Create a dedicated `#bot-log` channel in your server and copy its channel ID (right-click the channel → Copy Channel ID with Developer Mode enabled). You'll need this as your `CHANNEL_ID`.
    </Tip>
  </Step>

  <Step title="Clone the Repo and Install Dependencies">
    Clone Freesona and install its Python dependencies:

    ```bash theme={null}
    git clone https://github.com/soquincy/Freesona.git
    cd Freesona
    pip install -r requirements.txt
    ```

    <Note>
      **Windows users:** Python's `zoneinfo` module may lack IANA time zone data on some Windows installs, which breaks `/settimezone` and other `ZoneInfo` lookups. The `tzdata` package is included in `requirements.txt` and installs automatically. If you're adding it to an existing virtual environment manually, run:

      ```powershell theme={null}
      .venv\Scripts\pip.exe install tzdata
      ```
    </Note>
  </Step>

  <Step title="Configure Your .env File">
    Copy the sample environment file and fill in your values:

    ```bash theme={null}
    cp .env.sample .env
    ```

    Open `.env` in a text editor. At minimum, set these values before launching:

    ```dotenv .env theme={null}
    BOT_TOKEN=your_discord_bot_token
    CHANNEL_ID=your_log_channel_id
    AI_PROVIDER=gemini
    GOOGLE_API_KEY=your_gemini_api_key
    MODEL_NAME=gemini-flash-lite-latest
    BOT_NAME=Freesona
    HTTP_PORT=10000
    ```

    | Variable         | What to put here                                                                                      |
    | ---------------- | ----------------------------------------------------------------------------------------------------- |
    | `BOT_TOKEN`      | The bot token you copied from the Developer Portal                                                    |
    | `CHANNEL_ID`     | The numeric ID of your `#bot-log` channel                                                             |
    | `AI_PROVIDER`    | The provider you want to use (`gemini` is the default)                                                |
    | `GOOGLE_API_KEY` | Your Gemini API key (or swap for another provider's key — see [AI Providers](/features/ai-providers)) |
    | `MODEL_NAME`     | The model to use; `gemini-flash-lite-latest` is the default                                           |
    | `BOT_NAME`       | Display name used in startup messages                                                                 |
    | `HTTP_PORT`      | Port for the built-in health check and webhook server                                                 |

    <Tip>
      Using a different AI provider? Only set the key for the provider you've selected in `AI_PROVIDER`. See the full provider key reference in [Configuration](/configuration#ai-provider-keys).
    </Tip>
  </Step>

  <Step title="Launch the Bot">
    **Option A — Direct launch:**

    ```bash theme={null}
    python main.py
    ```

    This starts the Discord bot and the built-in HTTP server (used for webhooks and health checks) as concurrent async tasks.

    ***

    **Option B — Use the local setup scripts (recommended for first-time setup):**

    On Linux or macOS:

    ```bash theme={null}
    bash scripts/setup_local.sh
    ```

    On Windows:

    ```cmd theme={null}
    scripts\setup_local.cmd
    ```

    The setup scripts automate the full local bootstrap process:

    1. Copy `.env.sample` to `.env` if `.env` doesn't exist yet, then prompt you to fill it in.
    2. Validate that `BOT_TOKEN`, `CHANNEL_ID`, and `AI_PROVIDER` are set and not placeholder values.
    3. Verify that the correct API key is present for your chosen `AI_PROVIDER`.
    4. Check that `CHANNEL_ID` is a numeric Discord snowflake.
    5. Create a `.venv` virtual environment if one doesn't exist.
    6. Install dependencies from `requirements.txt`.
    7. Run `scripts/check_project.py` to catch any project-level issues.
    8. Launch `main.py`.

    <Warning>
      The setup scripts are for local and manual self-hosted deployments only. Do not use them in Docker, Railway, Render, or any other automated deployment environment — those platforms manage their own bootstrap process.
    </Warning>

    When the bot is online, it sends a startup message to the channel specified by `CHANNEL_ID`:

    ```text theme={null}
    Heya! Freesona here! Current prefix is `~`. For fresh info, use `search <query>`.
    ```
  </Step>

  <Step title="Confirm the Bot Is Responding">
    In any channel your bot has access to, run:

    ```text theme={null}
    ~ping
    ```

    or

    ```text theme={null}
    /ping
    ```

    The bot should respond with a latency message. If it does, your bot is up and connected.

    From here you can:

    * Set the AI chat channel with `/setchannel` so the bot knows where to respond to general messages.
    * Check loaded modules with `/module list`.
    * Set a persona with `/setpersona`.
  </Step>
</Steps>

<Note>
  For cloud hosting on Railway or Render, the local setup scripts don't apply — those platforms manage environment injection and process launch directly. See the [Hosting guide](/guides/hosting) for platform-specific setup steps, persistent volume configuration, and the `/data/` file paths required to survive redeployments.
</Note>

## What's Next

<CardGroup cols={3}>
  <Card title="Configuration" icon="sliders" href="/configuration">
    Explore every `.env` variable and live `/config` setting.
  </Card>

  <Card title="Persona System" icon="masks-theater" href="/features/persona">
    Give your bot a persona using structured fields.
  </Card>

  <Card title="AI Providers" icon="microchip" href="/features/ai-providers">
    Switch to Ollama, Groq, OpenRouter, or any other supported provider.
  </Card>
</CardGroup>