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

# Environment Variables

> Runtime environment variables for the Python SDK.

## Aion Control Plane Settings

These settings control optional integration with the Aion control plane.
When they are not provided, `aion serve` can still start local agent and proxy
processes, and you can invoke agents directly through the local A2A and proxy
endpoints. Without them, the SDK cannot authenticate with or use the Aion control
plane.

For deployments hosted by Aion, the control plane provides these values
automatically. Set them yourself only when running outside Aion-hosted
deployments or when testing local control plane connectivity.

<table
  className={[
"m-0 min-w-full w-full max-w-none table",
"[&_td]:min-w-[150px] [&_th]:text-left",
"[&_td[data-numeric]]:tabular-nums",
].join(" ")}
>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Type</th>
      <th>Required</th>
      <th>Default</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>AION\_CLIENT\_ID</code></td>
      <td>string</td>
      <td>No</td>
      <td>unset</td>
    </tr>

    <tr>
      <td />

      <td colSpan={3}>
        Client ID used with <code>AION\_CLIENT\_SECRET</code> for control plane
        authentication. For *Aion-hosted* deployments this is populated by the
        *Aion control plane*. Set it manually only for self-managed deployments
        or local testing against the control plane.
      </td>
    </tr>

    <tr>
      <td><code>AION\_CLIENT\_SECRET</code></td>
      <td>string</td>
      <td>No</td>
      <td>unset</td>
    </tr>

    <tr>
      <td />

      <td colSpan={3}>
        Secret paired with <code>AION\_CLIENT\_ID</code> for control plane
        authentication. For *Aion-hosted* deployments this is populated by the
        *Aion control plane*. Set it manually only for self-managed deployments
        or local testing against the control plane.
      </td>
    </tr>

    <tr>
      <td><code>AION\_API\_HOST</code></td>
      <td>string</td>
      <td>No</td>
      <td><code>[https://api.aion.to](https://api.aion.to)</code></td>
    </tr>

    <tr>
      <td />

      <td colSpan={3}>
        Base URL for *Aion control plane* HTTP and WebSocket calls. Must start
        with <code>http\://</code> or <code>https\://</code>; invalid values fail
        settings validation during startup.
      </td>
    </tr>

    <tr>
      <td><code>AION\_API\_KEEP\_ALIVE</code></td>
      <td>integer</td>
      <td>No</td>
      <td><code>60</code></td>
    </tr>

    <tr>
      <td />

      <td colSpan={3}>
        Keep-alive interval exposed by SDK settings for control plane
        connections. If unset, the SDK uses the default value.
      </td>
    </tr>
  </tbody>
</table>

## Storage Settings

<table
  className={[
"m-0 min-w-full w-full max-w-none table",
"[&_td]:min-w-[150px] [&_th]:text-left",
"[&_td[data-numeric]]:tabular-nums",
].join(" ")}
>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Type</th>
      <th>Required</th>
      <th>Default</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>POSTGRES\_URL</code></td>
      <td>string</td>
      <td>No</td>
      <td>unset</td>
    </tr>

    <tr>
      <td />

      <td colSpan={3}>
        PostgreSQL DSN for persistence and DB-backed features. If unset, the SDK
        falls back to in-memory storage where supported. If set but unreachable,
        database initialization logs connection or migration errors and durable
        storage features remain unavailable.
      </td>
    </tr>

    <tr>
      <td />

      <td colSpan={3}>
        This database is used for A2A task history and other durable runtime
        data. Framework adapters can also use it for framework-specific
        persistence, such as LangGraph execution state and checkpoint data when
        PostgreSQL-backed checkpointing is enabled.
      </td>
    </tr>

    <tr>
      <td><code>FILE\_STORAGE\_BACKEND</code></td>
      <td>string</td>
      <td>No</td>
      <td>unset</td>
    </tr>

    <tr>
      <td />

      <td colSpan={3}>
        Optional backend for converting inline file parts into URI-based file
        references. When unset, file content is left inline. The only supported
        value today is <code>stub</code>, which is intended for development and
        test flows. Unknown values fail startup when file upload handling is
        initialized.
      </td>
    </tr>

    <tr>
      <td />

      <td colSpan={3}>
        This is used by the ADK artifact service when inline artifact data
        should be uploaded and stored as URI references, and by A2A file parts
        that carry inline file bytes instead of URLs.
      </td>
    </tr>
  </tbody>
</table>

## Logging Settings

<table
  className={[
"m-0 min-w-full w-full max-w-none table",
"[&_td]:min-w-[150px] [&_th]:text-left",
"[&_td[data-numeric]]:tabular-nums",
].join(" ")}
>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Type</th>
      <th>Required</th>
      <th>Default</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>LOG\_LEVEL</code></td>
      <td>string</td>
      <td>No</td>
      <td><code>INFO</code></td>
    </tr>

    <tr>
      <td />

      <td colSpan={3}>
        Allowed: <code>DEBUG</code>, <code>INFO</code>, <code>WARNING</code>,
        <code>ERROR</code>. Invalid values fail settings validation.
      </td>
    </tr>

    <tr>
      <td><code>LOGSTASH\_HOST</code></td>
      <td>string</td>
      <td>No</td>
      <td>unset</td>
    </tr>

    <tr>
      <td />

      <td colSpan={3}>
        Host for centralized log shipping. Must be set together with
        <code>LOGSTASH\_PORT</code>; otherwise remote log shipping remains
        disabled and logs stay on local stream handlers. For *Aion-hosted*
        deployments, the control plane populates this automatically.
      </td>
    </tr>

    <tr>
      <td><code>LOGSTASH\_PORT</code></td>
      <td>integer</td>
      <td>No</td>
      <td>unset</td>
    </tr>

    <tr>
      <td />

      <td colSpan={3}>
        Port for centralized log shipping. Must be set together with
        <code>LOGSTASH\_HOST</code>; otherwise remote log shipping remains
        disabled. For *Aion-hosted* deployments, the control plane populates this
        automatically.
      </td>
    </tr>

    <tr>
      <td><code>NODE\_NAME</code></td>
      <td>string</td>
      <td>No</td>
      <td>unset</td>
    </tr>

    <tr>
      <td />

      <td colSpan={3}>
        Optional deployment node identifier used primarily in log metadata. For
        *Aion-hosted* deployments, the control plane populates this
        automatically. If unset, local logging still works normally.
      </td>
    </tr>

    <tr>
      <td><code>VERSION\_ID</code></td>
      <td>string</td>
      <td>No</td>
      <td>unset</td>
    </tr>

    <tr>
      <td />

      <td colSpan={3}>
        Optional deployment version identifier used primarily in log and
        deployment metadata. For *Aion-hosted* deployments, the control plane
        populates this automatically. If set, the SDK uses this value directly.
        If unset, <code>aion serve</code> attempts to fetch it from the control
        plane; on failure it logs a warning and continues without a version ID.
      </td>
    </tr>
  </tbody>
</table>

## Miscellaneous Settings

<table
  className={[
"m-0 min-w-full w-full max-w-none table",
"[&_td]:min-w-[150px] [&_th]:text-left",
"[&_td[data-numeric]]:tabular-nums",
].join(" ")}
>
  <thead>
    <tr>
      <th>Variable</th>
      <th>Type</th>
      <th>Required</th>
      <th>Default</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>AION\_DOCS\_URL</code></td>
      <td>string</td>
      <td>No</td>
      <td><code>[https://docs.aion.to/](https://docs.aion.to/)</code></td>
    </tr>

    <tr>
      <td />

      <td colSpan={3}>
        Base documentation URL used when the SDK builds agent-card extension
        links. If unset, the default docs URL is used.
      </td>
    </tr>
  </tbody>
</table>

## Loading Behavior

* Variables can be provided through the system environment or a `.env` file in
  the project root.
* If the same variable is set in both places, the system environment value
  wins.
* Variable names are case-insensitive in settings parsing.
* Missing optional variables use defaults or remain unset.
* Variables with explicit format or allowed-value constraints fail validation
  when set to invalid values.

## Example `.env`

```bash theme={null}
# Optional: Aion control plane integration
# For Aion-hosted deployments, these are provided by the control plane.
# Set them yourself only for self-managed deployments or local testing.
AION_CLIENT_ID=your_client_id
AION_CLIENT_SECRET=your_client_secret
AION_API_HOST=https://api.aion.to
AION_API_KEEP_ALIVE=60

# Optional: storage
POSTGRES_URL=postgresql://user:password@localhost:5432/aion_db
AION_FILE_STORAGE_BACKEND=stub

# Optional: logging
LOG_LEVEL=INFO
```