Get started¶

cautem is a single CLI that runs coding agents in policy-bound sandboxes on Docker or Podman. Install the CLI, make sure a container engine is running and pull a sandbox image — then start the gateway and create your first sandbox.

Install the CLI¶

For a complete platform-specific walkthrough, see macOS or Linux.

with the installer recommended¶

The installer downloads a verified release archive from quarshell-cli, installs the CLI and its helper assets into ~/.local/bin, and starts the local Gateway when that platform release includes it. Windows releases currently include the CLI only. Run:

curl -LsSf https://raw.githubusercontent.com/KLORQ/quarshell-cli/main/install.sh | sh
cautem version
cautem status

cautem status should report Connected. Set CAUTEM_NO_START=1 to skip gateway startup, or CAUTEM_VERSION=vX.Y.Z to pin a release.

If you use Podman, initialize it first and install with CAUTEM_NO_START=1. Then export CAUTEM_GATEWAY_RUNTIME=podman before running cautem gateway ensure; otherwise the installer starts the default Docker backend.

The binaries and helper assets go to ~/.local/bin — make sure it is on your PATH.

To install into another directory:

curl -LsSf https://raw.githubusercontent.com/KLORQ/quarshell-cli/main/install.sh \
  | CAUTEM_INSTALL_DIR=/usr/local/bin sh

from source¶

Build from the workspace checkout if you want the latest published module versions or want to work across modules:

git clone https://github.com/KLORQ/quarshell-workspace.git
cd quarshell-workspace
tools/checkout-modules.sh
task workspace:sync

go build -C quarshell-cli -o cautem ./cmd/cautem
go build -C quarshell-gateway -o quarshell-gateway ./cmd/quarshell-gateway
./cautem install
./cautem version

Start a container engine¶

cautem needs a running compute provider. Docker is the default; Podman works through the same Engine API.

DockerPodman on macOSPodman on Linux

Docker Engine 28.0+ or Docker Desktop. On macOS and Windows prefer the Docker VMM backend.

docker info
cautem doctor
cautem status

podman machine init     # once
podman machine start
export CAUTEM_GATEWAY_RUNTIME=podman
cautem gateway ensure
cautem status

systemctl --user enable --now podman.socket
export CAUTEM_GATEWAY_RUNTIME=podman
cautem gateway ensure
cautem status

cautem status should report that the selected Gateway is connected. Engine details: Docker · Podman.

Get a sandbox image¶

Pull the base image — it has the CLI tooling an agent needs:

docker pull ghcr.io/cautem/cautem/sandboxes/base:latest
export CAUTEM_USE_GHCR=1

Building images yourself

From the workspace root: task runtime:image:cli builds the base image and task docker:agent:cursor the Cursor agent. The full list is in Images.