---
title: Stack Commands
description: caracal up, down, and status — start, stop, and probe the local Caracal stack.
pageType: reference
---

Stack commands manage the local Caracal stack. They delegate to `docker compose` and do not require `CARACAL_ADMIN_TOKEN`. In rc or stable mode, the compose file and env file are resolved automatically from the Caracal home — no flags needed. In dev mode, run via `pnpm caracal` from inside the repo, which sets `CARACAL_REPO_ROOT` automatically.

---

## `caracal up`

Start the stack.

```bash
caracal up
```

Equivalent to `docker compose up -d`. In dev mode, passes `--build` to rebuild images before starting. In rc or stable mode, runs without `--build` and injects `CARACAL_VERSION` into the compose environment.

Forwards all `docker compose` output to stdout and exits with the compose exit code.

---

## `caracal down`

Stop and remove stack containers.

```bash
caracal down       # stop containers, preserve volumes
caracal down -v    # stop containers and remove volumes (destroys all persisted data)
```

`-v` is passed directly to `docker compose down`. Use it to reset the stack to a clean state between test runs or when rotating secrets.

---

## `caracal status`

Probe all five services and report their health.

```bash
caracal status
```

Sends `GET /health` to each service in parallel with a 1500 ms timeout:

| Service | Default port | URL probed |
| --- | --- | --- |
| `api` | 3000 | `http://localhost:3000/health` |
| `sts` | 8080 | `http://localhost:8080/health` |
| `gateway` | 8081 | `http://localhost:8081/health` |
| `audit` | 9090 | `http://localhost:9090/health` |
| `coordinator` | 4000 | `http://localhost:4000/health` |

Example output:

```
api            3000  ok      200
sts            8080  ok      200
gateway        8081  down    timeout
audit          9090  ok      200
coordinator    4000  ok      200
```

Exit code is `0` if all services respond, `1` if any is down or unreachable. Use this in scripts to wait for stack readiness:

```bash
caracal up
until caracal status; do sleep 1; done
```

---

## Provisioning a zone and application

The stack starts with an empty database. Use the admin commands to create a zone, register an application, capture the client secret, and author `caracal.toml`:

```bash
caracal zone create --name local
caracal app create --zone <zone-id> --name local-app
# client secret is printed once; save it into caracal.toml
```

See the [Admin commands](./admin/) reference for full flags and the [Configuration File](./config-file/) page for the `caracal.toml` schema and discovery order.
