Skip to main content

​
cargo.state.json

Every deploy writes cargo.state.json — a map from each code resource (kind:slug) to the real uuid Cargo assigned it, plus its outputs and a content hash: 
{
  "version": 1,
  "workspaceUuid": "fbe3...",
  "resources": {
    "connector:hubspot": { "hash": "sha256:…", "uuid": "9c26…", "outputs": { "uuid": "9c26…", "datasetUuid": "f12c…" } }
  }
}
It’s the authoritative link from code to deployed infra. 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.
Commit cargo.state.json. If you lose it, uuid-only resources orphan and a re-deploy creates duplicates. Recover a lost link with cargo-ai cdk import <id> <uuid>.
It records only uuids, hashes and outputs — never secret values.

​
Lock file

During a deploy/destroy/import the CDK writes sibling files next to cargo.state.json — a cargo.state.lock (serializes concurrent runs), a cargo.state.bak.json (rollback snapshot), and a cargo.state.audit.jsonl (run log). Only cargo.state.json is committed; git-ignore the rest: 
cargo.state.lock
cargo.state.bak.json
cargo.state.audit.jsonl
A lock left by a dead process is reclaimed automatically; --force overrides one you believe is stale.

​
Drift

The CDK compares your code against state. It can also compare against the live workspace to catch changes made outside the CDK (e.g. someone edits an agent in the Cargo UI, or deletes a folder).

​
Detect (read-only)

cargo-ai cdk refresh
Re-reads every state-tracked resource and reports each as unchanged, modified externally, or deleted externally. It changes nothing.

​
Correct

cargo-ai cdk deploy --refresh
Folds the drift into the plan before applying:
  • Modified externally → re-applies your code over it (code wins).
  • Deleted externally → recreates it.
Drift is measured against the state captured at the last deploy, not guessed from code — so it reflects real changes to the live resource. A transient read error is reported as unknown, never as a deletion, so a network blip can’t trigger a mass re-create.

​
Secrets and drift

Because secret() values are excluded from the content hash, rotating a secret does not show as drift and a plain deploy won’t push the new value (nothing changed). To roll a rotated secret, re-apply the resource (make any other change, or use --refresh). Use env() instead if you want a config value tracked in the hash.