Configuration & API keys

This page covers the configuration that matters when self-hosting: the backend environment, and the agent’s settings including its provider key and the write opt-in.

Caution

Every value shown here is a placeholder. Never put a real secret in a committed file. Put real keys only in your server’s environment.

Backend environment

The backend reads its configuration from .env. The essentials are the app key, the database connection, and the app URL.

APP_KEY=generate-with-php-artisan-key-generate
APP_URL=https://api.your-domain.example

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_DATABASE=trakli
DB_USERNAME=your-db-user-here
DB_PASSWORD=your-db-password-here

Web UI environment

The frontend needs to know where the backend is.

NUXT_PUBLIC_API_BASE_URL=https://api.your-domain.example

Agent configuration

The agent is built on the eloquent-agents package. Its behaviour is driven by configuration, which is where the safety model is set. The important pieces:

• Provider and model. Which model provider the agent uses, and which model.
• Provider API key. The key for that provider. This is a secret. Keep it in the environment, not in a config file under version control.
• Readable models allowlist. Which data the read tool may query, declared explicitly. Nothing is readable until listed.
• Write opt-in. Whether the agent may create or update data. Off by default.

A typical environment looks like this, with placeholders:

# Which provider and model the agent uses
AGENTS_PROVIDER=your-provider-here
AGENTS_MODEL=your-model-here

# Provider API key. Secret. Server-side only.
AGENTS_API_KEY=your-api-key-here

# Allow the agent to write (create/update). Off by default.
AGENTS_ALLOW_WRITES=false

Note

Exact key names depend on your eloquent-agents configuration. The principle is fixed: the read allowlist starts empty, writes start off, and the provider key is a secret you supply at deploy time.

The safety defaults, restated

If you change nothing, the agent:

• Can read only the data you have declared readable.
• Reads only the acting user’s records.
• Cannot write anything, because writes are off.

To let the agent create and categorise transactions, set the write opt-in to true. To broaden what it can read, add models to the allowlist. Both are deliberate steps. See Permissions and safety.