Your first project — Nubes Docs

Understand the application

Before writing infrastructure, identify your app’s working directory, package manager, build command, and required environment variables.

Make sure the server listens on 0.0.0.0 and reads its port from the PORT environment variable. Keep development-only configuration separate from the deployed application.

Describe what you need

Create nubes.hcl at the root of your project. You can also keep it in a folder such as .ai/; pass that file’s path to the CLI. This example describes a Node.js application in an api directory.

nubes.hcl

version = 1

app "api" {
  source "nodejs" {
    path            = "./api"
    package_manager = "pnpm"
    build           = "pnpm build"
  }
}

Paths are relative to the configuration directory, or its parent when the file lives in .ai/. No package.json is needed to locate the project.

Run nubes validate to check the file and nubes fmt to format it. Both default to nubes.hcl.

Adapt the path and build command to your own project. Do not add a database or secret unless the app needs one.

Review the plan

With the Nubes CLI available in your environment, generate a plan:

nubes plan nubes.hcl

If you put the file in .ai/, use nubes plan .ai/nubes.hcl instead.

Read the proposed changes before proceeding. If you are working with an agent, ask it to explain the plan and wait for your approval.

Keep iterating

Commit the infrastructure file alongside the application. When your project’s requirements change, update the file and review a fresh plan.