Skip to main content

Workflows

These workflows connect the command surface to real runtime tasks.

Audience: User

Context: Use this page when you need complete task sequences rather than isolated command reference.

Workflow 1: First Workspace​

  1. Start the runtime with caracal up.
  2. Enter either caracal cli or caracal flow.
  3. Create a workspace.
  4. Mark it active.
  5. Confirm that commands resolve the correct workspace config and logs.

In Flow, onboarding handles most of this interactively. In the CLI, the direct path is:

caracal workspace create demo
caracal workspace use demo
caracal workspace current

Workflow 2: Prepare Provider-Scoped Authority​

  1. Add a provider definition to the active workspace.
  2. Test the provider connection.
  3. Confirm that the provider's resources and actions are now part of the workspace catalog.
  4. Use those scopes when creating a policy.

Why this matters:

  • policies and mandates are validated against workspace provider scopes
  • provider setup is part of the authority path, not just an integration detail

Workflow 3: Principal To Policy To Mandate​

  1. Register a principal.
  2. Create an authority policy for that principal.
  3. Issue a mandate within that policy's limits.
  4. Validate or use the mandate in an execution path.

Minimal sequence:

caracal principal register --type agent --name worker-1 --email worker@example.com
caracal policy create ...
caracal authority mandate ...
caracal authority enforce ...

The exact policy and mandate commands depend on provider-scoped resource and action values from the current workspace.

Workflow 4: Delegation​

  1. Start from an active, valid source mandate.
  2. Delegate only a subset of the original scope.
  3. Keep validity within the source mandate's remaining lifetime.
  4. Use graph and ledger views to confirm the resulting path.

Caracal enforces direction rules for delegation. Not every principal-type pair is allowed.

Workflow 5: Backup And Restore​

  1. Export or back up a workspace before destructive operations.
  2. Include secrets only when you also provide a workspace lock key.
  3. Restore into a clean target workspace when needed.

Important behavior:

  • exports may include a PostgreSQL schema dump when the workspace config defines a schema
  • imports can restore the workspace files and database schema together

Workflow 6: Reset Versus Purge​

Use reset when you want to rebuild runtime data volumes but keep the overall installation context.

Use purge only when you want to remove:

  • containers
  • volumes
  • networks
  • images
  • workspace state
  • local Caracal home data

Edge Cases And Constraints​

  • Flow and the CLI share the same underlying workspace and backend modules, so mixing them in one workflow is normal.
  • Some workflows implicitly assume the current workspace exists and is selected. If that is false, commands may fail in ways that look unrelated.
  • Workspace import and export paths behave differently in container runtime mode because host-shared I/O is mounted under /caracal-host-io.
AI tools
On this page