Secrets & environments

How env(), secret() and workspaceEnv() differ, the CARGO_* environment variables the CLI reads, and how to promote the same project code to a second workspace.

Cargo resolves credentials and configuration from your environment — both inside define* resources (env() / secret() / workspaceEnv()) and for the CLI itself (CARGO_* variables). This page covers both, and how to deploy the same code to more than one workspace.

env(), secret() and workspaceEnv()

Three helpers, each with one behaviour. The first two read your local environment; the third reads nothing locally and points at the workspace’s own environment variables:

Helper	Reads	Resolved	In the content hash & deploy state?	Use for
env("NAME")	process.env.NAME	at load time	Yes — the value enters the spec	Non-secret config you want tracked (region, base URL, …)
secret("NAME")	process.env.NAME	at apply time	No — only a reference is stored	A credential this deploy supplies
workspaceEnv("KEY")	nothing locally	at apply time	No — only a pointer is stored	A credential the workspace holds and rotates

connectors/hubspot.ts

import { defineConnector, env, secret, workspaceEnv } from "@cargo-ai/cdk";

export const hubspot = defineConnector("hubspot", {
  integration: "hubspot",
  config: {
    method: "privateApp",
    accessToken: secret("HUBSPOT_API_KEY"), // this deploy's value, never hashed
    region: env("HUBSPOT_REGION"), // tracked in the content hash
  },
});

export const salesforce = defineConnector("salesforce", {
  integration: "salesforce",
  config: {
    // Read from the workspace on every use — rotate it there, no redeploy
    accessToken: workspaceEnv("SALESFORCE_TOKEN"),
  },
});

Always use secret() or workspaceEnv() — never env() — for credentials. Both are excluded from the content hash and from the deploy state; env() bakes the value into the hash, so rotating it reads as drift and the value is written to state.

How each behaves

• env("NAME") reads process.env.NAME when the file is imported and inlines the value into the spec. If the variable is unset it returns a visible ${NAME} placeholder so the gap surfaces in cargo-ai project plan.
• secret("NAME") returns a deferred reference (EncryptionRef). At apply time the project reads process.env.NAME, wraps it in Cargo’s encryption envelope, and sends it to the API. The deploy fails if the variable is not set locally — it does not fall back to the workspace catalog, so a credential’s behaviour never depends on what the deploying machine happened to have exported. Because the reference — not the value — enters the spec, rotating a secret doesn’t register as drift, and a plain deploy won’t push the new value (nothing in the hash changed). Re-apply the resource to roll a rotated secret: make any other change, or run cargo-ai project deploy --refresh.
• workspaceEnv("KEY") returns a deferred pointer (WorkspaceEnvRef). At apply time it becomes a reference to the workspace variable named KEY; the value stays server-side and never reaches the deploying machine. It is read again on every use, so rotating it needs no re-apply at all — see rotating a value. cargo-ai project plan fails if the workspace holds no such variable.

Where each is accepted

The distinction is load-bearing, and the generated types enforce it:

Position	Accepts
Connector and system-of-record config	secret() or workspaceEnv() (typed CredentialRef)
defineWorker, defineApp, defineAgent, defineScript env	env() or secret() (typed EncryptionRef)

workspaceEnv() is deliberately a type error on a resource’s own env, because those runtimes already receive every workspace variable by inheritance — a pointer there could only restate a variable the resource can read anyway. Config is different: a connector’s credential is a single field, so pointing it at the catalog is the only way to make it rotate without a redeploy.

See State & drift for how the content hash drives what a deploy considers changed.

Workspace environment variables

A workspace holds its own set of environment variables, managed under Settings → Environment (or with cargo-ai workspaceManagement envVar). Store a value once there instead of setting it on every worker, app and agent that needs it. Secrets are encrypted at rest and their values are never returned by the API.

Every worker, app and agent in the workspace picks them up automatically — you do not declare them on the resource:

Runtime	What it receives	How to read it
Worker	Every workspace variable, secrets included	c.env.NAME
App	Only non-secret variables whose key starts with VITE_	import.meta.env.VITE_NAME
Agent	Every workspace variable, in the sandbox its shell commands run in	process.env.NAME

An app bundle is served to the browser, which is why a secret is never put in one. Give an app its public configuration under a VITE_ key and keep the credential it must not expose on a worker instead.

A variable set on the resource itself wins over the workspace variable with the same key, so a single worker can override one value without a copy of the rest. That is also what secret("NAME") does at deploy time: the value your shell exports is sent as that resource’s own value for this apply, and the catalog is left untouched.

Rotating a value

A resource never holds a copy of a workspace variable — it inherits it, or holds a workspaceEnv() pointer, resolved each time the value is needed. Rotating the value under Settings → Environment therefore reaches everything that reads it, with no redeploy. When it takes effect depends only on when the resource next reads it:

Resource	A new value takes effect
Connector, native script model	On the next run — immediately
Agent	On the next message
Worker	On its next deployment
App	On its next build

Workers and apps bake their environment into a build artifact, so those two need a redeploy. Nothing else does.

Deleting a variable that a connector still points at breaks it at the next run, not at the next deploy. The failure names the missing variable, but check what references a value before removing it.

A workspaceEnv() pointer is checked at plan time, so a cargo-ai project deploy naming a variable the workspace does not hold fails before it creates anything. That check needs the API; an offline plan skips it.

The one exception is an integration that mints its own credentials during authentication — an OAuth flow that exchanges what you submit for its own tokens, as HubSpot and Slack do. What ends up stored is the provider’s token rather than your variable, so there is nothing left to keep live and rotating the variable has no effect. Reconnect the connector instead.

CLI environment variables

The cargo-ai CLI (and therefore cargo-ai project) reads three environment variables. They take precedence over the saved credentials file (~/.config/cargo-ai/credentials.json):

Variable	Purpose	Default
CARGO_API_TOKEN	API token used to authenticate every request	— (falls back to the saved credentials)
CARGO_WORKSPACE_UUID	The workspace to operate on	— (falls back to the token’s workspace)
CARGO_BASE_URL	Cargo API base URL	https://api.getcargo.io

In CI or an AI coding agent, set these instead of running cargo-ai login:

export CARGO_API_TOKEN=<your-api-token>
export CARGO_WORKSPACE_UUID=<workspace-uuid>   # optional; pins the target workspace
cargo-ai whoami                                # confirms the active token, workspace, and source

whoami reports the source as environment when a CARGO_API_TOKEN is set, or credentials-file when it’s reading the saved login.

Promoting code to a second workspace

The same project code can deploy to multiple workspaces (e.g. staging → production). Two things change per workspace; the code does not:

1. Which workspace you target — set CARGO_WORKSPACE_UUID (or log in to that workspace), so cargo-ai project deploy resolves the right target.
2. The secret values — either export each environment’s secret() values before deploying, or write the code with workspaceEnv("KEY") and store the value once in each workspace’s environment variables. The second is usually what you want for promotion: each workspace holds its own value under the same key, so pointing the same code at production is nothing beyond selecting the workspace.

# Deploy the same repo to the production workspace
export CARGO_WORKSPACE_UUID=<prod-workspace-uuid>
export HUBSPOT_API_KEY=<prod-hubspot-key>
cargo-ai project deploy --dir ./prod   # keep prod's deploy state separate

Each workspace needs its own deploy state — a state records the workspace uuid, and a deploy refuses to run if it belongs to a different workspace than the one selected (it would orphan resources). Keep a separate checkout or --dir per workspace, and run cargo-ai project state create in the second one so the two have different pointers.

Secrets are never copied between environments through Cargo: deploy state records only uuids, hashes, and outputs — never secret values.