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.

The full template

cargo-ai cdk init <dir> --template full scaffolds a complete, runnable workspace that exercises every resource type and wires them together. For a guided walkthrough that builds and deploys this whole tree, see the End-to-end recipe:

my-workspace/
├── package.json          # scripts: "plan": "cargo-ai cdk plan", "deploy": "cargo-ai cdk deploy"
├── tsconfig.json         # includes .cargo-ai/**/*.d.ts for typed config
├── cargo.state.json      # created on first deploy — 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

Every deploy writes cargo.state.json — the authoritative map from each code resource (kind:slug) to the real uuid Cargo assigned it, plus outputs and a content hash.

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. Lose the file and a re-deploy creates duplicates. Recover a lost link with cargo-ai cdk import <id> <uuid>.

The lock/backup/audit siblings are ephemeral — git-ignore them:

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

Which init do I want?

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

Command	What it does
cargo-ai cdk init <dir>	Scaffold a CDK workspace project (this page).
cargo-ai hosting app init <dir>	Scaffold a hosted Vite app bundle.
cargo-ai hosting worker init <dir>	Scaffold a hosted edge worker bundle.
cargo-ai init	An API call that fetches workspace initialization data — not a local scaffold.

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.