---
last_review: "2026-05-07"
last_reviewer: "s.kaviani"
documented_code: [ ]
---

```{tags} advanced-user, reference
```

% Issue: https://gitlab.indiscale.com/caosdb/src/linkahead-docs/-/work_items/103

# PyLinkAhead Configuration Reference

PyLinkAhead is configured using `ini` configuration files. The files are read in the following
order:

1. The file specified in the environment variable `PYLINKAHEADINI` (useful for CI/CD pipelines or
   when switching between multiple configurations)
2. `~/.pylinkahead.ini` (user home directory)
3. `pylinkahead.ini` in the current working directory (if it exists)

Later files override earlier ones. This means you can keep shared settings in `~/.pylinkahead.ini`
and override specific values per project using a local `pylinkahead.ini`. You can download the
[example pylinkahead.ini file](https://gitlab.com/linkahead/linkahead-pylib/-/blob/main/examples/pylinkahead.ini)
as a starting point.

At least, you need to set the `url` and `username` fields.

:::{note}
To try PyLinkAhead against the public demo instance at `https://demo.indiscale.com`, use
`username=admin` with `password_method=plain` and `password=caosdb`.
:::

## Settings

All settings go under the `[Connection]` section of the ini file:

```ini
[Connection]
url=...
username=...
```

`url`
: The URL of the LinkAhead server (e.g. `https://demo.indiscale.com`).

`username`
: The username for authentication.

`password_method`
: Controls how the password is provided. Accepted values:
  - `input`: query the password on demand (default)
  - `pass`: use the [pass](https://www.passwordstore.org) password manager; requires `password_identifier`
  - `keyring`: use the system keyring/wallet (macOS, GNOME, KDE, Windows); requires the
     [keyring](https://pypi.org/project/keyring) package
  - `plain`: read the plain-text password stored in the `password` field of the ini file (strongly
     discouraged)

`password_identifier`
: The identifier within `pass` for the desired password. Only used when `password_method=pass`.

`password`
: The plain-text password. Only used when `password_method=plain`.

`auth_token`
: An authentication token for connecting to the server. Not recommended for regular users.

`cacert`
: Path to the SSL CA certificate file for the connection (e.g. `/path/to/linkahead.ca.pem`).

`ssl_insecure`
: Set to `True` to skip SSL certificate validation. This leaves the connection vulnerable to
  man-in-the-middle attacks. Use with care.

`ssl_version`
: The SSL protocol version to use, given as the name of the corresponding attribute in Python's
  `ssl` module (e.g. `PROTOCOL_TLS`).

`debug`
: Set to `0` to suppress debug output (default). Set to `1` or `2` for verbose output useful for
  debugging or learning about the protocol internals.

`timeout`
: Sets the timeout in seconds for requests to the server.

`socket_proxy`
: Address of a SOCKS4 or SOCKS5 proxy (e.g. `localhost:12345`), for reaching a server behind a
  firewall tunnelled via `ssh -D` or a dedicated proxy server.

For the full list of available options with defaults, see the
[pylinkahead.ini example file](https://gitlab.com/linkahead/linkahead-pylib/-/blob/main/examples/pylinkahead.ini).