Linux setup

Set up wraptool on a non-Guix Linux distribution: a container engine, the Dev Containers CLI, config location, and a first run.

On a non-Guix Linux distribution (Debian/Ubuntu, Fedora, Arch, …) wraptool up uses the devcontainer runtime. If you’re on Guix System, follow Guix setup instead for the native, no-Docker path.

1. Install a container engine

The devcontainer runtime needs Docker (or a compatible engine such as Podman with a Docker-compatible socket). Install it from your distribution and confirm:

docker version

Add your user to the docker group (or use rootless Docker / Podman) so wraptool up can talk to the daemon without sudo.

2. Install the Dev Containers CLI

wraptool up shells out to the devcontainer command on non-Guix hosts. It ships as an npm package; install Node, then use a user-owned npm prefix so global installs need no sudo:

npm config set prefix ~/.local
export PATH="$HOME/.local/bin:$PATH"   # add to your shell rc to persist
npm install -g @devcontainers/cli
devcontainer --version

3. Install wraptool

Follow Installation — the release script detects linux and installs to ~/.local/bin. Then:

wraptool version

4. Where your config lives on Linux

wraptool follows the XDG base-directory spec. On Linux that is:

~/.config/wraptool/config.yaml

(or $XDG_CONFIG_HOME/wraptool/config.yaml if you set that variable). Override per-run with --config or WRAPTOOL_CONFIG.

On first run wraptool up scaffolds a commented starter there and never clobbers an existing one. Keep the keys exactly as scaffolded — the loader silently ignores unknown keys, so a typo like auth_token (the real key is auth_token_file) fails quietly. A minimal, correct config:

mcp:
  transport: sse
  listen: 127.0.0.1:8717

tools:
  git:
    binary: /usr/bin/git
    timeout: 30s
    allow:
      - subcommand: [push]
        flags: ["--set-upstream"]
        deny_flags: ["--force", "--force-with-lease"]
    deny:
      - subcommand: [remote, set-url]

Leave mcp.listen on loopback — for the devcontainer bridge wraptool up rebinds it to 0.0.0.0 and auto-generates the MCP auth token. Validate before launching:

wraptool config validate

5. Scaffold the devcontainer and launch

Install the harness into the shared pool once (it’s the developer’s toolbox, not the project’s), pick your languages, scaffold, then bring it up:

wraptool harness install claude
wraptool init devcontainer --harness claude --lang go
wraptool up

up starts the shared server, brings up the container via devcontainer up, mounts the pool-installed harness binary in read-only and wires its MCP config to the host, and drops you into a shell. Host credentials are not mounted; privileged git goes through wraptool’s MCP git tool. Stop with wraptool down (--rm to remove).

Next steps

Back to top