Project layout

How a Cargo workspace is organized as files, how the loader turns them into resources, and how state keeps code and live infra in sync.

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:

my-workspace/
├── package.json          # scripts: "plan": "cargo-ai project plan", "deploy": "cargo-ai project deploy"
├── tsconfig.json         # includes .cargo-ai/**/*.d.ts for typed config
├── cargo.state.json      # written by `project init` — commit it
├── connectors/
│   ├── hubspot.ts        # defineConnector + secret()
│   └── openai.ts         # defineConnector({ adopt: true })
├── folders/crm.ts        # defineFolder (per-kind: model, agent, …)
├── models/contacts.ts    # defineModel — dataset handle + extractSlug + schedule
├── tools/enrich.ts       # defineWorkflow + defineTool
├── agents/
│   ├── enricher.ts       # defineAgent (sub-agent)
│   └── sdr.ts            # defineAgent (models, tools, subAgents, triggers, evaluator)
├── plays/onboarding.ts   # definePlay + per-row defineWorkflow
├── mcp/crm.ts            # defineMcpServer
├── context/              # defineContext + markdown/MDX
├── files/                # defineFile + local content
├── workers/webhook/      # defineWorker → a built bundle
└── apps/dashboard/       # defineApp → a Vite bundle

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.

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:

.cargo-ai/
cargo.state.lock
cargo.state.bak.json
cargo.state.cache.json
cargo.state.audit.jsonl

Each repo gets its own state, so a workspace can hold as many as you have projects. See State & drift for the full model.

Which init do I want?

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

Command	What it does
cargo-ai project init <dir>	Scaffold a GTM repo with the project in infra/ (this page).
cargo-ai project add cookbook/<name>	Install a worked cookbook into a repo you already have.
cargo-ai hosting app init <dir>	Scaffold a hosted Vite app bundle.
cargo-ai hosting worker init <dir>	Scaffold a hosted edge worker bundle.

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.