quarshell-cli

Agent sandbox CLI
Create, harden, and operate policy-bound sandboxes — Cursor, Claude, Codex, and BYOC.

_{Part of the Quarshell ecosystem}

The quick start contains the supported installation and first-sandbox flow.

quarshell-cli is the user-facing cautem binary for Quarshell: sandbox lifecycle, policy checks, provider attach, gateway selection, live logs, and agent images.

Install the latest CLI release into ~/.local/bin; Linux and macOS archives include the Gateway and runtime helpers, while the current Windows archive includes the CLI:

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

Pin a release with CAUTEM_VERSION=vX.Y.Z, or skip gateway startup with CAUTEM_NO_START=1.

From source in the Quarshell workspace:

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

Requirements: Docker or Podman. Go 1.27+ only if building from source.

Quarshell APIs are pre-stable and remain in the 0.x series. OpenShell behavioral compatibility is still partial. See development and releases and the compatibility status.

./cautem status
./cautem policy check ./policies/default.yaml

./cautem sandbox create --name demo --gateway-workspace default --upload "$PWD" --policy ./policies/default.yaml
./cautem sandbox exec demo -- uname -a
./cautem sandbox rm demo

Create on the selected Gateway compute backend with a published OCI image or a workspace-scoped shared template:

./cautem sandbox template create shared-agent --gateway \
  --image ghcr.io/example/agent:stable --cpu 2 --memory 4Gi --env MODE=fast
./cautem sandbox create --gateway-workspace team \
  --name agent --image ghcr.io/example/agent:stable \
  --cpu 500m --memory 2Gi --gpu 1 --env MODE=fast

Sandbox creation is Gateway managed and follows the OpenShell CreateSandbox contract. Image creates accept CPU, memory, GPU count, environment, labels, providers, policy, restart policy and per-driver config overrides. A shared template owns its workload settings and rejects inline workload overrides. Local bind mounts/builds, display, and local runtime switches are not part of this create path. --upload streams through OpenShell interactive execution.

./cautem sandbox create --name cursor --from cursor --upload "$PWD" \
  --provider cursor --provider gh --policy ./policies/cursor.yaml
./cautem sandbox exec cursor -- agent

Agent Dockerfiles live in docker/agents/. Policies: policies/. Runnable recipes live in examples/.

Apache-2.0 © cautem