Skip to main content
bridge.yaml is the project-local configuration file for Bridge. It tells the CLI what your project is called and which named providers an agent can read from. Bridge keeps the config intentionally small:
  • one file
  • one project name
  • one map of named providers

​
Where Bridge looks for configuration

Bridge reads bridge.yaml from the current working directory. That means:
  • bridge init creates bridge.yaml in the directory where you run it
  • bridge read, bridge ls, bridge status, and bridge connect expect the file to exist in the current directory
  • Bridge does not currently search parent directories for a config file
If bridge.yaml is missing, Bridge returns config_not_found and tells you to run bridge init.

​
Minimal configuration

Running bridge init creates a minimal config like this: 
version: "1"
name: my-project
providers: {}
bridge init uses the current directory name as the default project name. If bridge.yaml already exists, the command does not overwrite it.

​
A real example

Most projects will start with one local provider and one database provider: 
version: "1"
name: my-agent-project
providers:
  files:
    type: filesystem
    uri: file://./docs
  db:
    type: postgres
    uri: ${DATABASE_URL}
In this example:
  • files is a filesystem provider rooted at ./docs
  • db is a Postgres provider whose connection string comes from an environment variable

​
Top-level fields

FieldTypeRequiredWhat it does
versionstringyesConfiguration format version. Bridge currently writes "1".
namestringyesProject name. bridge init defaults this to the current directory name.
providersmapyesNamed provider definitions keyed by provider alias such as files or db.

​
Provider entries

Each entry under providers is keyed by the name you want agents and humans to use at the command line. 
providers:
  files:
    type: filesystem
    uri: file://./docs
The provider name:
  • is chosen by you
  • is what you pass to --from
  • should be short and memorable
Each provider object currently supports these fields:
FieldTypeRequiredWhat it does
typestringyesProvider type such as filesystem or postgres
uristringyesConnection target for that provider
For provider-specific behavior and limitations, see Providers.

​
Supported provider types today

Bridge currently recognizes two provider types:
TypeAccepted URI formsNotes
filesystemfile://./path, file:///absolute/pathMust point to an existing directory
postgrespostgres://..., postgresql://...Used for listing tables and reading rows
If you use bridge connect with a literal URI, Bridge infers the type from the URI scheme automatically. Examples: 
bridge connect file://./docs --as files
bridge connect postgres://localhost:5432/mydb --as db
bridge connect postgresql://localhost:5432/mydb --as db
If you use bridge connect with an environment variable name, Bridge requires --type and writes the placeholder into bridge.yaml for you: 
bridge connect DATABASE_URL --type postgres --as db

​
Filesystem URIs

Filesystem providers use file:// URIs.

​
Relative paths

providers:
  files:
    type: filesystem
    uri: file://./docs
Relative paths are resolved from the current directory when Bridge connects the provider. In normal usage, that means they are relative to the project root where your bridge.yaml lives.

​
Absolute paths

providers:
  files:
    type: filesystem
    uri: file:///Users/alice/project/docs
Bridge expects a filesystem provider to point to an existing directory. If the path does not exist, or if it points to a file instead of a directory, connection will fail.

​
Postgres URIs

Postgres providers use standard connection strings: 
providers:
  db:
    type: postgres
    uri: postgres://localhost:5432/mydb
Or: 
providers:
  db:
    type: postgres
    uri: postgresql://localhost:5432/mydb
For local development, it is usually better to keep credentials out of the file and load them from the environment: 
providers:
  db:
    type: postgres
    uri: ${DATABASE_URL}
You can write that shape manually, or ask Bridge to generate it with: 
bridge connect DATABASE_URL --type postgres --as db

​
Environment variable expansion

Bridge expands environment variables inside strings using the exact ${VAR_NAME} syntax. Bridge writes that ${VAR_NAME} form automatically when you connect with a bare env var name such as DATABASE_URL. Example: 
providers:
  db:
    type: postgres
    uri: postgres://${PGHOST}:${PGPORT}/mydb
This supports:
  • a single variable in a full string like ${DATABASE_URL}
  • multiple variables inside one URI
If a referenced variable is not set, Bridge fails with env_var_not_set.
Use environment variables for secrets and credentials. Keep bridge.yaml safe to commit by avoiding raw passwords in the file when possible.

​
How Bridge updates the file

​
bridge init

  • creates bridge.yaml if it does not exist
  • uses the current directory name as name
  • initializes providers as an empty map
  • returns "already_exists" instead of overwriting an existing file

​
bridge connect

  • loads the existing config
  • accepts either a literal URI or a bare environment variable name as <target>
  • infers the provider type from a literal URI scheme when possible
  • requires --type when <target> is an environment variable name
  • inserts or updates the named provider entry
  • writes the updated bridge.yaml back to disk
If you connect the same name twice, the later value replaces the earlier one.

​
bridge remove

  • deletes the named provider from providers
  • writes the updated file back to disk

​
Common mistakes

If you run a Bridge command in a directory without bridge.yaml, Bridge returns config_not_found. Run bridge init first, or change into the project directory that already contains the config file.
Bridge currently understands file://, postgres://, and postgresql:// schemes. A value like redis://localhost will fail with invalid_uri.
A bridge connect target must be either a full URI such as postgres://localhost:5432/mydb or a bare environment variable name such as DATABASE_URL. Placeholder syntax like ${DATABASE_URL} is for bridge.yaml, not for the CLI input.
If your config references ${DATABASE_URL} and that variable is not set, Bridge fails fast with env_var_not_set rather than guessing or continuing with a partial value.
A filesystem provider must point to an existing directory. If the directory does not exist, or if the path resolves outside the configured root during reads, Bridge returns a provider error.

​
Configuration philosophy

Bridge keeps configuration intentionally narrow:
  • one project-local file
  • explicit named providers
  • URI-based backend selection
  • environment variables for secrets
The goal is to keep agent integrations stable even when your storage setup changes. A provider can move from one URI to another without changing the command shape the agent uses.

​
Next steps

Providers

Learn exactly how the filesystem and Postgres providers behave today.

Quickstart

Start with the minimal Bridge workflow and connect your first provider.

CLI interface

See how Bridge turns configuration into structured JSON commands and output.