Powerloom on your laptop. In under two minutes.

What you'll get

One docker compose up brings these into existence on your laptop:

• Postgres 16 + pgvector — state store + vector memory for Alfred and any agents you create.
• Powerloom API — the control plane. Creates org + user + Alfred on first boot, mints a 365-day Personal Access Token, writes it to a host-visible file.
• Alfred — Powerloom's meta-agent, running on claude-opus-4-6. Same brand voice as the SaaS edition. Drives provisioning via natural language.
• Docker-local MCP spawner — Alfred can deploy MCP server containers (echo, files, postgres, slack) on your machine without Terraform or AWS.

Prerequisites

• Docker Desktop or an equivalent Linux docker + compose v2 setup.
• Python 3.11+ on the host — for scratch/home_init.py. Stdlib only; no pip install needed.
• Claude Code — install from anthropic.com/claude-code. Any version released in 2026 works.
• An Anthropic API key — get one at console.anthropic.com. Alfred runs on claude-opus-4-6 by default; expect a few cents per conversation for normal use.
• pip install mcp httpx in whichever Python Claude Code invokes — needed by the powerloom-mcp stdio server CC connects through.

Step 1 — Clone and configure

Clone the repo. Copy the example env file. Change two lines.

git clone https://github.com/shanerlevy-debug/Powerloom.git
cd Powerloom
cp .env.home.example .env.home

Open .env.home in your editor. Set these two lines:

POWERLOOM_HOME_EMAIL=you@example.com
ANTHROPIC_API_KEY=sk-ant-api03-...

The compose file refuses to start without POWERLOOM_HOME_EMAIL — a typo surfaces immediately rather than silently provisioning the wrong user. Everything else has sensible defaults.

Step 2 — Start the stack

docker compose -f docker-compose.home.yml \
    --env-file .env.home \
    up -d --build

Two containers come up: postgres and api. No UI, no pgadmin, no multiplexer — the home stack is lean on purpose.

On first boot the API runs Alembic migrations, then the home-mode bootstrap creates your org + user + Alfred and mints a 365-day PAT. Watch it happen:

docker compose -f docker-compose.home.yml --env-file .env.home \
    logs -f api | grep -E "home_bootstrap|alfred"

You're looking for these lines in order:

home_bootstrap.tenant_created org=... user=... email=you@example.com
alfred.bootstrap_for_org organization=... agent_created=True
home_bootstrap.artifacts_written pat_path=/app/home_data/pat.txt
home_bootstrap.done

Ctrl-C out of the log tail. Your stack is up.

Step 3 — Generate the Claude Code config

python scratch/home_init.py --write

This materializes two files under ./home_data/:

• .mcp.json — the MCP client config block Claude Code reads to connect to your local control plane.
• cc-prompt.md — the first-message prompt, with your specific user / org / Alfred IDs baked in.

While you're at it, stash your Anthropic key into the runtime_credentials store so every CMA agent Alfred provisions shares the key:

python scratch/home_init.py --byok-anthropic sk-ant-api03-...

Step 4 — Wire Claude Code

Copy the contents of ./home_data/.mcp.json into your Claude Code MCP config. Location depends on your CC setup:

• Project-scoped: <project>/.mcp.json in whatever directory you'll run CC from.
• User-wide: ~/.claude/mcp.json — affects every CC session on the machine.

The shape:

{
  "mcpServers": {
    "powerloom-home": {
      "command": "python",
      "args": ["/absolute/path/to/Powerloom/mcp_clients/powerloom_mcp_server.py"],
      "env": {
        "POWERLOOM_PAT": "pat_...",
        "POWERLOOM_API_BASE_URL": "http://localhost:8000"
      }
    }
  }
}

If Claude Code can't see the server, run the MCP script by hand: python <path>/powerloom_mcp_server.py. If it errors on mcp or httpx imports, pip install mcp httpx into whichever Python CC invokes.

Step 5 — Meet Alfred

Open a new Claude Code session. Your first message is the content of ./home_data/cc-prompt.md, with one edit: replace the placeholder in What I want to do: with an actual goal.

Examples that work well as a first turn:

• "Deploy an echo MCP and invoke it to confirm the loop works."
• "Deploy a files MCP pointed at /data/mcp_files and summarize whatever I've dropped there."
• "Create a project called 'ops-weekly' with a thread for each of {a, b, c}. Hold them at priority=high."

CC will call powerloom_whoami and powerloom_list_agents first, then hand off to Alfred via tool calls to actually drive provisioning. Alfred's voice is direct and terse — no chattiness, no emoji, no filler. It's a feature, not a limitation.

Everyday commands

# Check status
docker compose -f docker-compose.home.yml --env-file .env.home ps

# Tail logs
docker compose -f docker-compose.home.yml --env-file .env.home logs -f api

# psql shell (no pgadmin in home mode)
docker compose -f docker-compose.home.yml --env-file .env.home exec postgres \
    psql -U powerloom -d powerloom

# Rotate your PAT (revokes old, mints fresh, rewrites artifacts)
python scratch/home_init.py --rotate --write

# Stop (data persists in ./home_data/postgres)
docker compose -f docker-compose.home.yml --env-file .env.home down

# Start fresh (wipes all local state)
docker compose -f docker-compose.home.yml --env-file .env.home down
rm -rf ./home_data
docker compose -f docker-compose.home.yml --env-file .env.home up -d --build

Security notes

• Localhost-only by default. Postgres and the API bind 0.0.0.0 inside the container but are port-mapped only to localhost. If you expose ports on a LAN, rotate the internal service token and generate a real credential master key. Both documented in .env.home.example.
• Treat ./home_data/ like ~/.aws/credentials. The PAT is reveal-once in the DB but plain-text on disk. The directory is gitignored.
• Docker socket mount. The home compose file bind-mounts /var/run/docker.sock — a root- equivalent mount — so the deploy worker can spawn MCP containers. This is acceptable on a single-user localhost stack and explicitly NOT done in the SaaS / prod deployment.
• Anthropic key lives in .env.home. Every Alfred invocation spends against it. If you hand the stack off, rotate the key via console.anthropic.com.

Troubleshooting

Related

• Download this guide as PDF →
• What Powerloom actually is → — the platform overview (SaaS-focused, but everything applies to home mode).
• Full documentation →
• Repo on GitHub →