Your first Bahama Cloud project

Give your agent the job

Open Claude Code, Codex, or another coding agent in the workspace and try this:

Build a small, polished Vite app that displays “Hello from Bahama.” Use Bahama
Cloud to deploy it. Handle the setup and commands for me, and let me know when
Bahama asks me to approve a consequential plan.

If you already have an application, replace the first sentence with what you want changed or deployed. The infrastructure workflow stays the same.

Your agent prepares and inspects the application

For a new project, the agent creates the Vite app, installs its dependencies, and confirms that it builds. For an existing project, it starts by understanding what is already there.

It then asks Bahama to inspect the workspace:

bahama inspect --json

Inspection gives the agent non-secret facts: framework signals, package manager, scripts, environment-variable names, and existing Bahama files. It never reads environment-variable values.

The agent should confirm that the detected framework is vite-spa and that the project has a working build script before moving on.

Your agent confirms the provider fit

bahama providers bahama-cloud --format agent

This live provider guide tells the agent what the installed Bahama version can deploy through Bahama Cloud. A Vite SPA is supported; Next.js, Node servers, and Python applications are not.

If the project does not match, the agent should explain the mismatch and ask you how to proceed. It should not quietly reshape the application to fit a provider.

Your agent describes the project to Bahama

bahama init --name hello-bahama --application bahama-cloud --framework vite-spa

The agent runs init to write bahama.yaml and add .bahama/ to .gitignore. This does not contact Bahama Cloud or create a project.

The generated manifest looks like this:

version: 1
project:
  name: hello-bahama
 
application:
  framework: vite-spa
 
environments:
  local:
    provider: local
  production:
    provider: bahama-cloud

The application has one framework and two environments. local represents normal development in this workspace. production is the hosted Bahama Cloud environment.

If the deployable app lives below the repository root, the agent adds its relative path:

application:
  framework: vite-spa
  dir: apps/web

Bahama asks you to sign in if needed

Your agent asks Bahama to compile an infrastructure plan:

bahama plan

If this machine is not connected to a Bahama account, Bahama returns auth required. Your agent can start the login:

bahama auth login bahama-cloud

Your browser opens the Bahama consent flow. This is one of the few steps you complete yourself because the account belongs to you. In a headless or SSH environment, your agent can use --no-browser; Bahama displays a URL and one-time code that you can finish in another browser.

After you finish signing in, the agent runs bahama plan again.

You review the infrastructure plan

For a new project, the plan includes a consequential step to create the Bahama Cloud project. It does not upload or deploy the application yet.

The result will resemble this:

approval required  Plan plan_7f4c9b21a3d0 needs approval.

  ! Create Bahama Cloud project hello-bahama
      creates a resource

  Account: you@example.com

Your agent should summarize the plan in plain language. Check the project name, account, and each ! step. If they match what you intend, tell the agent to approve and continue. You do not need to copy the plan ID yourself.

Your agent applies exactly what you approved

After your approval, the agent uses the exact plan ID Bahama printed:

bahama apply plan_7f4c9b21a3d0 --approved

Bahama creates or adopts the project and verifies it before updating bahama.lock. The agent can then commit the project files if you asked it to:

git add bahama.yaml bahama.lock .gitignore
git commit -m "Configure Bahama deployment"

bahama.yaml records what you want. bahama.lock records which verified live project this repository is connected to.

Your agent validates the application

Before deployment, the agent runs the project’s normal build:

npm run build

Bahama Cloud will install from the checked-in lockfile and run the same build script in an isolated build environment. The build must produce dist/index.html.

You approve the first deployment

Your agent now asks Bahama to deploy the production environment:

bahama deploy production

The first deployment is consequential, so deploy stops and prints a new plan instead of publishing immediately. The agent explains the source directory, framework, account, and deployment step. If they look right, tell it to continue.

The agent applies the exact deployment plan:

bahama apply plan_a91d02e4c6f8 --approved

Bahama packages the current source, uploads it directly, waits for the build and publication job, and verifies the live URL. The operation is not complete until the production page responds successfully.

Ask your agent to ship the next change

Later, you can stay in the same conversational workflow:

Change the heading to “Hello again from Bahama,” test it, and deploy the update.

Your agent edits and tests the application, then runs:

bahama deploy production

Once the environment and provider configuration are established, a code-only redeployment is routine and can apply immediately. If infrastructure or provider configuration changed, Bahama stops with another plan for review.

Ask about the project later

You can ask, “Is this project healthy?” or “What is currently deployed?” Your agent checks with:

bahama status --json

Status compares the committed lock with the live project and reports whether the production environment is ready, not ready, unhealthy, or unknown. It does not change anything.