Run Quarshell on Linux¶

This guide runs the CLI and Gateway on the Linux host and creates a sandbox with Docker Engine. Quarshell APIs are pre-stable and remain in the 0.x series.

Requirements¶

A 64-bit Linux system on x86_64 or arm64.
Docker Engine with a working API socket, or Podman with its API socket.
curl, sh, and a shell with ~/.local/bin on PATH.

The user running quarshell-gateway must be allowed to access the container engine socket. Access to the rootful Docker socket grants root-equivalent control over that host; use a dedicated machine and follow your host's security policy.

1. Install the container engine¶

For Docker, follow the official guide for your distribution, for example Ubuntu. Start the service and make sure the current user can connect to it. Then verify:

docker version
docker info
docker run --rm hello-world

For Podman, follow the official installation instructions. On a systemd user session, start its socket:

systemctl --user enable --now podman.socket
podman info

2. Install the CLI and Gateway¶

curl -fsSL https://raw.githubusercontent.com/KLORQ/quarshell-cli/main/install.sh | CAUTEM_NO_START=1 sh

The installer verifies the SHA-256 checksum and installs cautem, quarshell-gateway, and helper assets into ~/.local/bin. CAUTEM_NO_START=1 lets you select and start the engine before launching Gateway.

If needed, add the install directory to PATH in ~/.profile:

printf '\nexport PATH="$HOME/.local/bin:$PATH"\n' >> ~/.profile
. ~/.profile

Verify the CLI and Gateway:

cautem version

3. Select Docker or Podman¶

The local Gateway defaults to Docker. For Podman, select it before starting the Gateway so the Gateway process inherits the backend setting:

export CAUTEM_GATEWAY_RUNTIME=podman

Keep this variable in the shell used to run cautem. If a healthy local Gateway was started with a different backend, restart it after changing the setting. Confirm engine access as the same user that runs the Gateway:

docker info   # Docker
podman info   # Podman
cautem gateway ensure
cautem status

4. Pull the image and prepare a policy¶

For Docker:

docker pull ghcr.io/cautem/cautem/sandboxes/base:latest

For Podman, run podman pull ghcr.io/cautem/cautem/sandboxes/base:latest. Resolve the base alias to the published image and create a policy file:

export CAUTEM_USE_GHCR=1
mkdir -p ~/.config/cautem
cat > ~/.config/cautem/default-policy.yaml <<'EOF'
version: 1
filesystem_policy:
  include_workdir: true
  read_only:
    - /usr
    - /lib
    - /proc
    - /dev/urandom
    - /app
    - /etc
    - /var/log
    - /AGENTS.md
  read_write:
    - /tmp
    - /dev/null
    - /sandbox
    - /workspace
landlock:
  compatibility: best_effort
network_policies: {}
EOF

5. Create and use a sandbox¶

Run from the project directory you want to upload:

cautem sandbox create \
  --name demo \
  --gateway-workspace default \
  --from base \
  --policy ~/.config/cautem/default-policy.yaml \
  --upload "$PWD"

cautem sandbox list
cautem sandbox exec demo -- uname -a
cautem sandbox connect demo

connect opens a shell; leave it with exit. --upload sends a copy of the directory during creation. It does not mount the live host directory. The policy allows no network destinations until you add explicit rules; see network policy.

Delete the sandbox when finished:

cautem sandbox delete demo

Troubleshooting¶

Gateway health check fails: run cautem gateway ensure and inspect ~/.config/cautem/gateway.log.
docker info or podman info fails: fix engine service/socket access for the same user, then retry.
Image pull fails: verify registry access with the engine's pull command.
Podman is ignored: export CAUTEM_GATEWAY_RUNTIME=podman before starting the Gateway. This guide installs with CAUTEM_NO_START=1, so the installer does not start the default Docker backend first.