First Protected Call

This walkthrough creates the baseline every later tutorial assumes: a running local stack, one zone, one confidential agent app, one protected resource, one active policy, one runtime profile, and one audited Gateway call.

Complete Install Caracal first.

Start Caracal

caracal up
caracal status --ready

On Windows PowerShell:

caracal up
caracal status --ready

Create product objects only after readiness succeeds. If readiness fails, run:

caracal status --ready --json

The JSON output shows which service is not ready.

Start Demo Upstream

Start a local HTTP upstream on the same Docker network as Caracal:

docker run --rm -d --name caracalDemoUpstream --network caracalData nginx:stable-alpine

On Windows PowerShell:

docker run --rm -d --name caracalDemoUpstream --network caracalData nginx:stable-alpine

Use http://caracalDemoUpstream:80 as the resource upstream URL in guided setup. If you already have an HTTP service that the Gateway container can reach, you can use that URL instead.

Create a Protected Resource

Open the Console:

caracal console

On Windows PowerShell:

caracal console

Choose guided setup and use these first-run choices:

Step	First-run choice
Scenario	Internal HTTP API
Zone	Create a local evaluation zone.
Agent app	Create a confidential app for the workload.
Resource	Use a stable resource ID, required scopes, and the upstream URL you chose.
Provider	Skipped for the internal HTTP API scenario.
Access policy	Let the Console create and activate the starter policy.
Review	Enable write profile files when this machine should receive the runtime profile and secret file.

The result view shows the zone ID, application ID, resource ID, app client secret, active policy set, profile path, secret-file path, generated profile, and first-success commands.

Save the Runtime Profile

Guided setup can write the runtime profile and secret file for you. Enable write profile files when you want the Console to create them on the current machine.

If file writing is disabled, copy the generated TOML profile and one-time app client secret from the result view into the paths the Console shows. Keep the secret file readable only by the owner.

The generated profile is the source of runtime configuration for:

• CARACAL_CONFIG=... caracal run -- <command>
• new Caracal() in TypeScript and Caracal() in Python
• caracal.New() in Go

Always generate a profile from the objects you just created instead of hand-authoring runtime configuration.

Run Your Workload

Use the generated profile path with the command that starts your workload:

CARACAL_CONFIG=/path/to/caracal.toml caracal run -- ./start-agent.sh

On Windows PowerShell:

$env:CARACAL_CONFIG = "C:\path\to\caracal.toml"
caracal run -- .\start-agent.ps1

caracal run exchanges the configured application secret for resource-specific Caracal access tokens and injects them into the environment variables named in the profile. The workload reads those variables and presents the token to the Gateway or protected service.

For SDK-based workloads, the same generated profile is read by the SDK constructors (new Caracal(), Caracal(), caracal.New()).

Call the Gateway

For a Gateway-routed HTTP resource, send the request to the Gateway URL from the result view and include:

Header	Value
Authorization	Bearer <Caracal access token>
X-Caracal-Resource	The resource ID from guided setup.

Run the exact curl or PowerShell command from the Console result view first. It uses the resource ID, protected path, and profile values you just created.

Inspect Audit

Return to the Console:

1. Open audit.
2. Find the request you just made.
3. Press Enter on the event, or open explain and paste its request ID.

The explanation should show the application, resource, requested scopes, policy version, policy set version, Gateway result, and final decision. If the request failed, the explanation identifies whether to fix runtime config, policy, resource routing, or the upstream service.

Clean Up

docker rm -f caracalDemoUpstream
caracal down

On Windows PowerShell:

docker rm -f caracalDemoUpstream
caracal down

Use caracal purge only when you intentionally want to remove local containers, volumes, config, runtime state, examples, and caches.

Next Step

Continue with Add SDK to Your App.