Quickstart
This is the shortest path from a fresh install to a working runtime session.
Audience: User
Context: Use this page after installation when you want first success before reading the full reference.
Practical Usage
Start the runtime:
caracal up
Open the in-container CLI:
caracal cli
Or launch Flow:
caracal flow
Inspect runtime logs from the host:
caracal logs -f
Stop the stack when finished:
caracal down
What To Expect
caracal up starts PostgreSQL, Redis, and the mcp service. It may also build images when a source-based compose file is in use.
caracal cli ensures the stack is up, then opens a restricted interactive Caracal session inside the runtime container. From there, caracal --help shows the operational CLI, not the host orchestrator.
caracal flow starts the terminal UI in its own container session. On first run it takes you through onboarding, workspace setup, and configuration checks.
First Productive Checks
Inside the in-container CLI:
caracal workspace list
caracal workspace create demo
caracal workspace use demo
caracal principal register --type agent --name demo-agent --email demo@example.com
Those commands confirm that the runtime can persist workspace state, write to PostgreSQL, and use the in-container CLI normally.
Internal Behavior
The runtime separates lifecycle commands from product commands:
caracal up,down,logs,reset, andpurgeare host-level orchestrationcaracal workspace ...,principal ...,policy ...,authority ..., and related groups are in-container operations
That separation is deliberate. It prevents the host command surface from exposing the entire operational interface directly.
Edge Cases And Constraints
caracal cliuses themcpcontainer and launches the restricted shell there.caracal flowstarts only the services it needs directly and does not require themcpcontainer to already be running.caracal purge --forceis destructive and removes containers, volumes, networks, images, workspaces, and local state. Do not treat it as a normal stop command.