How Bahama works

Bahama fits into the coding-agent workflow you already use. You ask for an outcome in ordinary language, and your agent uses Bahama to choose compatible infrastructure, show you important decisions, and carry out the work safely.

The installed Bahama skill guides the agent from the beginning. It explains how to inspect a project, compare providers, write the manifest, handle approval, and recover from failures. The bahama CLI gives the agent a deterministic way to do that work and verify the result.

You usually do not need to run the commands on this page yourself. They are shown so the workflow remains easy to understand and inspect.

1. You ask for an outcome

For example:

Add Postgres to this application, make it work locally, and deploy it.

Your agent begins by understanding the existing application and reading the capabilities available in the installed Bahama version:

bahama inspect --json
bahama providers --format agent

Inspection reports useful, non-secret facts such as the framework, package manager, scripts, environment-variable names, and existing Bahama files. The provider catalog explains which application and database combinations are actually supported.

This keeps the agent grounded in the real project and live provider guidance instead of relying on a remembered command or guessed integration.

2. Your agent records the intended setup

The agent writes the chosen setup to bahama.yaml. This short file describes the application, its environments, any resources it needs, and how values move between them.

It contains intent that you and future coding agents can review. It does not contain provider project IDs, connection strings, tokens, or other discovered state.

3. Bahama creates a read-only plan

Your agent asks Bahama what it would take to make the live infrastructure match the manifest:

bahama plan

Planning checks the manifest, provider tools, login sessions, selected accounts, and relevant live resources. It returns exact steps without creating, changing, or deploying anything.

Routine steps preserve an established setup. Consequential steps create, adopt, migrate, reconnect, or make another change that deserves your review. Bahama classifies these effects centrally, so a provider cannot mark its own mutation safe.

Infrastructure planning and application deployment remain separate. A plan may prepare a database or configure an environment, but it never publishes source code.

4. You approve consequential work

When a plan needs approval, your agent should explain the important steps and provider accounts in plain language. If everything matches your request, tell the agent to continue.

The agent then applies the exact plan Bahama produced:

bahama apply plan_7f4c9b21a3d0 --approved

You do not need to copy the plan ID or run the command yourself. Approval is bound to that validated plan. If the manifest, lock, migrations, account, or protected provider configuration changes, Bahama refuses to reuse it.

5. Bahama verifies the live result

A successful provider command is not enough. Bahama checks the expected live result—for example, that a project exists under the planned account, a migration was recorded, a variable reached its destination, or a production URL responds.

Only verified work is written to bahama.lock. If an operation is interrupted, the agent can retry the same valid plan; Bahama rechecks completed work and resumes at the first unfinished step.

When the application is ready, your agent deploys it explicitly:

bahama deploy production

The first deployment waits for your approval. Later code-only deployments to the same verified environment can run routinely. If the infrastructure changes, Bahama pauses for another review.

The result is a project another agent can understand

The manifest records what the project needs. The lock records which live resources were verified. A future coding-agent session can read both, check the current provider state, and continue without depending on old chat history or hidden local setup.