fmxexpress/pasclaw repository overview

⁠PasClaw

An ultra-lightweight personal AI agent written in Delphi Object Pascal, compiled with Free Pascal. A command-line assistant, an HTTP gateway with an embedded web UI, an OpenAI-compatible API surface, tool calling, MCP integration, scheduled tasks, skills, and channel integrations — in a single ~40 MB image with no runtime to install.

Source: https://github.com/FMXExpress/PasClaw⁠

⁠Quick start

docker pull fmxexpress/pasclaw

The gateway is the default command, so no arguments are needed:

docker run -p 8088:8088 fmxexpress/pasclaw

Open http://localhost:8088⁠. The web UI has a first-boot onboarding wizard — pick a provider and paste a key in the browser, nothing on the command line.

The entrypoint runs pasclaw for you, so pass only the subcommand:

docker run -it fmxexpress/pasclaw agent      # interactive CLI agent
docker run --rm fmxexpress/pasclaw version
docker run --rm fmxexpress/pasclaw --help

⁠Keeping your workspace

Everything lives under $PASCLAW_HOME, which is /home/pasclaw/.pasclaw inside the container — config.json plus workspace/ holding sessions, memory, skills, knowledgebase and cron state. Without a mount it is lost when the container exits.

docker run -p 8088:8088 \
  -v "$HOME/.pasclaw:/home/pasclaw/.pasclaw" \
  fmxexpress/pasclaw

The container runs as the unprivileged user pasclaw (uid 1000), so the mounted directory has to be writable by that uid.

Read-only config with a writable workspace also works:

docker run -p 8088:8088 \
  -v "$HOME/.pasclaw/config.json:/home/pasclaw/.pasclaw/config.json:ro" \
  -v pasclaw-workspace:/home/pasclaw/.pasclaw/workspace \
  fmxexpress/pasclaw

⁠Configuration

Provider keys go in config.json under providers[].api_key, or come from the environment and are referenced as ${VAR} from the config — environment wins when both are set.

docker run -p 8088:8088 \
  -e ANTHROPIC_API_KEY \
  -v "$HOME/.pasclaw:/home/pasclaw/.pasclaw" \
  fmxexpress/pasclaw

The catalog covers roughly 26 providers — Anthropic Messages, OpenAI Chat Completions, Google Gemini, and the many OpenAI-protocol-compatible services (Groq, DeepSeek, Mistral, OpenRouter, Ollama, LM Studio, vLLM and others) — with streaming on all three protocol families, a fallback chain, and an opt-in offline router that sends easy turns to a cheaper model.

⁠Ports and health

EXPOSE 8088, and the default command is gateway --addr 0.0.0.0 --port 8088. The 0.0.0.0 bind matters: PasClaw defaults to 127.0.0.1, which inside a container means container-loopback only and -p would never reach it.

A HEALTHCHECK probes /v1/models every 30s. It returns 200 whenever the gateway is up, even with no providers configured, so docker compose ps and Kubernetes readiness reflect real state.

To listen on a different port inside the container, override the command and the health check — or just remap on the host with -p 9000:8088, which is simpler.

docker run -p 9000:9000 \
  --health-cmd 'curl -fsS http://localhost:9000/v1/models > /dev/null' \
  fmxexpress/pasclaw gateway --addr 0.0.0.0 --port 9000

⁠Tags

Pin a version for anything reproducible; latest moves.

⁠Platform

linux/amd64 only. The Dockerfile is arm64-capable, but the published images are amd64, so Apple Silicon and ARM servers run this under emulation. If you need a native arm64 build, build from source — or use the aarch64 Linux tarball on the GitHub releases page⁠, which is built natively.

⁠What is inside

A multi-stage build: a debian:bookworm stage compiles the binary with Free Pascal 3.2.2, and a debian:bookworm-slim runtime carries the result. OpenSSL 1.0.2 is bundled next to the binary with RPATH=$ORIGIN, because the Indy TLS stack refuses to operate against OpenSSL 1.1+ and every current distro ships 3.x. SQLite is the only other runtime dependency.

⁠A note on the two Dockers

This image runs PasClaw itself in a container. It is unrelated to PasClaw's optional Docker shell backend, which is a separate feature that runs the model's own shell_exec calls inside a throwaway container for a stronger sandbox.

⁠License and docs

Full documentation, configuration reference and build instructions: https://github.com/FMXExpress/PasClaw⁠