Skip to main content
A Cargo workspace is a directory of TypeScript files. The CLI imports every .ts file under the project root, and each define* call registers a resource as a side effect. There is no manifest — the files are the interface.

A worked layout

A project that exercises every resource type and wires them together looks like this. cargo-ai project init <dir> scaffolds the repo around it — the tree below is what grows inside infra/ as you declare things. For a guided walkthrough that builds and deploys the whole tree, see the End-to-end recipe:

How the loader works

  • Every .ts file is imported. Importing registers whatever define* calls it contains. To add a resource, add a file.
  • Handles create dependencies. define* returns a handle whose outputs (uuid, datasetUuid, …) are deferred tokens. Passing a handle into another builder (e.g. connector: hubspot, or an agent’s uses: [enrich]) both orders the deploy and injects the real uuid. The dependency graph is your variable graph.
  • Bundle directories are skipped. A subdirectory with its own package.json (a worker or app bundle) is treated as content to upload, not a resource file to import.
  • Executions load after the resources. Every .ts file in outputs/, beside cargo.json, is imported once the resource files are, so a defineBatch or defineRun there can import the play or tool it runs. The cargo.json below can name other folders instead. Nothing else outside the project is imported: a scripts/ folder stays untouched.

cargo.json

A cargo.json makes a folder a Cargo project, the way package.json does for an npm package. Every command looks for the nearest one above where it runs, up to the repository root, so it works from any folder in the project: infra/, outputs/, scripts/.
  • resources is the directory every .ts file of which is a resource.
  • executions lists the directories whose .ts files declare executions, in place of the default outputs/. Every file in them is imported, as in resources, so keep only executions there.
Paths are relative to the file and stay inside its folder. That folder is the project’s: cargo.state.json and the default outputs/ sit in it. A repository holding several projects has a cargo.json in each, and a command belongs to the nearest one. cargo-ai project init writes one. A command run where there is none stops and prints the one to add, rather than guessing the project from what the folders hold. A repository scaffolded before cargo.json existed adds it once, beside its cargo.state.json:
If an older version left cargo.state.json inside infra/, commands stop until it is moved beside cargo.json, and say how.

cargo.state.json

Your project’s deploy state is the authoritative map from each code resource (kind:slug) to the real uuid Cargo assigned it, plus outputs and a content hash. It lives in your workspace; cargo.state.json is the pointer to it that project init writes and every later run follows.
Commit cargo.state.json. Connectors and models are slug-addressable and self-heal, but plays, agents, tools, files, and MCP servers have no slug — their stored uuid is the only way to re-find them. Without the pointer a fresh checkout cannot find the state it belongs to — recover it with cargo-ai project state list and cargo-ai project state bind <uuid>, or recover one lost resource with cargo-ai project import <id> <uuid>.
The lock/backup/cache/audit siblings are ephemeral — git-ignore them:
Each repo gets its own state, so a workspace can hold as many as you have projects. See State & drift for the full model.

Adding a project to a repository you already have

Run init inside it — in its own folder (cargo-ai project init cargo) or at the root (cargo-ai project init .). It never replaces a file that is already there: a README or a CI workflow of the same name is kept and listed. An existing package.json only gains the scripts and dependencies the project needs (it is rewritten with two-space indentation), and an existing .gitignore only gains the patterns it lacks. An existing cargo.state.json keeps the state it names. init doesn’t commit or push in a repository that already exists — what else is in progress there is yours. Review what it wrote, commit and push it (after npm install, so package-lock.json matches package.json), then connect the project to the repository:
Connecting deploys the production branch straight away, and every later push to it deploys. Run it once the project is on that branch: pushed to a feature branch, merge it first. A repository made with git init and git remote add rather than cloned doesn’t know its default branch, so name it with --branch <name>.

Which init do I want?

There are several scaffold/init commands — don’t confuse them:

Next steps

Connectors

Start wiring in your data sources.

Deploying

The full reconcile lifecycle and its flags.

State & drift

How state tracks live resources and detects out-of-band changes.