guide

Connections

Connections are a desktop-app feature. They are not part of the open-source CLI and agent runtime — see Choosing CLI vs Desktop for which side of the product a capability belongs to.

Connections let you manage databases, object storage and cloud accounts once, then assign each to the workspaces where it may be used. The agent only ever sees a connection in the workspaces you authorize, and credentials never enter the conversation.

The three categories

Category Providers Capabilities
Databases SQLite, PostgreSQL, MySQL, Redis schema, sample
Object storage Amazon S3 / compatible, Azure Blob, Google Cloud Storage list, metadata, read
Cloud accounts AWS, Microsoft Azure, Google Cloud identity, inventory

Each connection has a display name, provider, environment, credential source, capability checkboxes, an enable switch and the list of authorized workspaces.

Creating a connection (database example)

Open the Connections view in the desktop app, choose Databases, and click Add connection:

  • Display name — anything readable, e.g. local dev db.
  • Provider — SQLite / PostgreSQL / MySQL / Redis.
  • Environment — development, test, staging or production.
  • Connection details — two modes that stay in sync:
    • Fields: host, port, database, user, and a TLS switch for network databases; SQLite shows a file picker instead.
    • Connection string: paste postgresql://user:pass@host:5432/db, mysql://user:pass@host:3306/db or redis://host:6379/2 and the fields fill themselves.
  • Credential source — system keychain (write-only secret) or an environment variable reference. A password pasted inside a connection string is never stored — the URL is sanitized and you are asked to put the secret in the credential field.
  • Authorized workspaces — none are selected by default: pick the workspaces this connection should appear in (explicit opt-in, so a new connection can never leak into every workspace by accident).
  • Capabilities — the boxes granted to the agent (see the table above).
  • Enabled — makes the connection discoverable in the assigned workspaces.

Click Save, then Test. Databases are probed with a real read-only connection; object storage and cloud accounts check that the configuration and credential are complete. Production connections stay visible but are never usable by the agent.

How the agent uses a connection (the db tool)

Inside an authorized workspace the agent reaches a database through the built-in db tool — you never paste connection details into chat:

Operation: list_connections

returns every usable connection with a stable connection_id and an access status (available, disabled, blocked_production, credential_missing). Then:

Operation: inspect   connection_id: <id>

reads the schema, and

Operation: query     connection_id: <id>
                     sql: "SELECT id, name FROM users LIMIT 5"

runs one read-only statement (SELECT / WITH / VALUES; parameterized with ?1 for SQLite, $1 for PostgreSQL, ? for MySQL). Redis queries go through an allowlisted read-only command set (GET, MGET, HGET, LRANGE, ZRANGE, TYPE, TTL, PTTL, EXISTS, SCAN, HSCAN, SSCAN, ZSCAN, DBSIZE, INFO).

Hard guardrails apply on every call:

  • Production connections are never exposed to the agent. The model can see that the connection exists, but cannot resolve its credential or connect.
  • Read-only: writes and DDL are refused; there is no "move data around" path.
  • Bounded: limit caps rows (default 200 for query, 2000 for inspect, hard max 2000), timeout_ms caps the call (default 15 s, max 60 s). Rows are sanitized for the model; oversized results spill to a <workspace>/.zlogic/cache/db-<call_id>.csv file the model can page through with read_file, while the UI always gets the bounded table.
  • No repeat prompts: the connection was configured by you and already passed non-production / enabled / capability checks, so each query does not pop a confirm dialog.

Security model

  • Credentials live in the OS keyring or an environment variable — never in workspace config or in chat. The model receives only the stable connection_id; it cannot read the secret or the raw connection string.
  • Workspace authorization: the agent only sees a connection in workspaces you assigned (and where it is enabled).
  • Per-call capability checks: even inside an authorized workspace, a connection must grant the capability the operation needs (schema for inspect, sample for query).
  • S3 / Azure / GCS and AWS / Azure / GCP connections store non-secret fields (bucket, region, endpoint, account ids) in the app database and their credentials in the keychain; the agent's object-storage and cloud tools resolve them the same way.

Object storage & cloud accounts

Object storage connections (list / metadata / read) let the agent browse and read buckets/containers you authorized; cloud accounts (identity / inventory) provide identity and inventory operations. Both check config + credential completeness when you click Test, and both follow the same workspace/credential model as databases.

Troubleshooting

Symptom Meaning / fix
Card shows credential_missing No keychain entry or env var set yet — open the connection and add the credential.
Card shows blocked_production The connection is tagged production; the agent is refused by design. Use a non-production replica/export for agent access.
db says the connection is disabled Flip the connection's Enabled switch (it is per-connection).
Connection string rejected Check the scheme matches the provider (postgresql:// for PostgreSQL), includes host + database + user (Redis: host; #/2 index optional), and that no password lives in the URL.