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

# Agent configuration

> Every environment variable, file and exit code of the agent.

The agent is configured with environment variables. It has no configuration file and no command-line flags.

## Image

```text theme={"system"}
ghcr.io/usecubit/source-client:0.1.0
```

* Public on GitHub Container Registry. No login needed.
* Built for `linux/amd64` and `linux/arm64`.
* Runs as a non-root user (UID `10001`).
* Exposes no port.
* There is no `latest` tag. Pin a version, or a digest.

### Verify the signature

Each release is signed with [Sigstore cosign](https://docs.sigstore.dev/cosign/), keyless, from the GitHub Actions workflow that builds it:

```bash theme={"system"}
cosign verify ghcr.io/usecubit/source-client:0.1.0 \
  --certificate-identity-regexp '^https://github.com/usecubit/cubit-cloud/\.github/workflows/agent-image\.yml@refs/tags/agent-v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
```

## Environment variables

**DATABASE\_URL** `string` *required*

The database to serve, with a read-only account. Always required.

```text theme={"system"}
postgresql://user:password@host:5432/database
mysql://user:password@host:3306/database
mariadb://user:password@host:3306/database
```

Accepted schemes: `postgresql`, `postgres`, `mysql`, `mariadb`. A driver suffix such as `postgresql+asyncpg` is accepted and ignored. The port defaults to `5432` for PostgreSQL and `3306` for MySQL and MariaDB. URL-encode special characters in the user name and password.

The value never leaves the machine. It appears in no message and no log.

**CUBIT\_ENROLL\_TOKEN** `string`

The single-use token from the dashboard. Required on the first start only. Once enrolled, the agent ignores it.

**CUBIT\_API\_URL** `string`

Required on the first start only. Use `https://api.concatflow.com`. Must be `https://`.

**CUBIT\_DATA\_DIR** `string` (default: /data)

Where the agent stores its credentials. Mount a persistent volume here.

## The data directory

After enrolling, the data directory holds two files, both readable by the agent's user only (`0600`):

| File | Contents |
| - | - |
| `agent.creds` | The agent's credentials: a signed token and the private key the agent generated. |
| `agent.json` | The dataset ID and the broker address. |

During enrollment, a third file, `agent.seed`, holds the private key until enrollment completes. If enrollment is interrupted, the agent reuses it on the next start, with the same token.

> [!WARNING]
>
> `agent.creds` grants access to your dataset's connection. Treat the volume like a secret: do not copy it, and do not share it between agents.

Losing the volume means losing the enrollment. Revoke the old agent and enroll again with a new token.

## Logs

The agent logs to standard output, one line per event:

```text theme={"system"}
2026-10-23 17:48:23,153 INFO source_client enrolled on dataset c8a3728e-582d-4c98-a8ff-de63f9f751a2
2026-10-23 17:48:23,211 INFO source_client serving dataset c8a3728e-582d-4c98-a8ff-de63f9f751a2
```

The agent does not log queries or their results.

## Exit codes

| Code | Meaning |
| - | - |
| `0` | Stopped cleanly after `SIGTERM` or `SIGINT`. |
| `1` | The account can write, or the database is unreachable at startup. |
| `2` | Configuration error: a missing variable, a refused token, or an unwritable data directory. |

## Stopping

On `SIGTERM`, the agent stops taking new requests and gives running ones up to 30 seconds to finish. Docker only waits 10 seconds by default. Add `--stop-timeout 30` to `docker run` to let long queries finish.

## Limits

An agent runs up to 4 queries at a time. Further queries wait their turn. For more capacity, [run a second agent](https://docs.concatflow.com/private-databases/guides/high-availability.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.