Self-host piclaw

piclaw README

How to install piclaw

PICLAW_WEB_PORT, PUID, PGID, PICLAW_AUTOSTART, PICLAW_TRUST_PROXY, PICLAW_KEYCHAIN_KEY

mkdir -p ./home ./workspace

docker run -d \
  --init \
  --name piclaw \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -e PICLAW_WEB_PORT=8080 \
  -v "$(pwd)/home:/config" \
  -v "$(pwd)/workspace:/workspace" \
  ghcr.io/rcarmo/piclaw:latest

PUID, PGID, PICLAW_WEB_PORT, PICLAW_AUTOSTART, PICLAW_WEB_BIND_HOST, WORKSPACE_PATH

PICLAW_SKIP_BIN_LINK, PICLAW_BIN_DIR

chmod +x piclaw-X.Y.Z-linux-x64.run
./piclaw-X.Y.Z-linux-x64.run --extract ./piclaw-unpacked
./piclaw-unpacked/piclaw-X.Y.Z-linux-x64/bin/piclaw --version

sudo ./piclaw-X.Y.Z-linux-x64.run --install /opt/piclaw

How to configure piclaw

• CPU_LIMITS=2Container CPU limit in the compose deploy resources

  Container CPU limit in the compose deploy resources

• MEMORY_LIMITS=4GContainer memory limit in the compose deploy resources

  Container memory limit in the compose deploy resources

• PGID=1000Container group id remapped by /entrypoint.sh on startup (compose stack)

  Container group id remapped by /entrypoint.sh on startup (compose stack)

• PICLAW_ABORT_SETTLE_TIMEOUT_MS=1000Bounded `0..10000` ms wait for abort cleanup to settle.

  Bounded `0..10000` ms wait for abort cleanup to settle.

  values: `domains.agentControl.abortSettleTimeoutMs`

• PICLAW_ADDON_API_FAILURE_BACKOFF_MS=60000Suppression period for repeated identical add-on API failures.

  Suppression period for repeated identical add-on API failures.

  values: `domains.addons.apiFailureBackoffMs`

• PICLAW_AGENT_TIMEOUT=3600000Max foreground agent turn time (ms), including interactive web chats

  Max foreground agent turn time (ms), including interactive web chats

• PICLAW_ASSISTANT_AVATAR=_(empty)_Avatar URL for the web UI

  Avatar URL for the web UI

• PICLAW_ASSISTANT_NAME=PiClawDisplay name in the web UI

  Display name in the web UI

• PICLAW_AUTOSTART=1Set to `0` to keep the supervisor service idle (run `pi`/`piclaw` manually)

  Set to `0` to keep the supervisor service idle (run `pi`/`piclaw` manually)

• PICLAW_BACKGROUND_AGENT_TIMEOUT=0Max background invocation time (ms; `0` disables and falls back to `PICLAW_AGENT_TIMEOUT`)

  Max background invocation time (ms; `0` disables and falls back to `PICLAW_AGENT_TIMEOUT`)

• PICLAW_BIN_DIRDirectory the portable installer puts launchers in

  Directory the portable installer puts launchers in

• PICLAW_CHAT_JID=web:defaultPer-invocation IPC target fallback. Request payload fields take precedence; this value is intentionally not persisted.

  Per-invocation IPC target fallback. Request payload fields take precedence; this value is intentionally not persisted.

• PICLAW_DATA=/workspace/.piclaw/dataSessions, IPC, chats.json

  Sessions, IPC, chats.json

• PICLAW_DB_IN_MEMORY=0Test/database bootstrap switch (`1` or `true`). Retained env-only because it selects the database before persisted config can safely be read.

  Test/database bootstrap switch (`1` or `true`). Retained env-only because it selects the database before persisted config can safely be read.

• PICLAW_DREAM_AGENT_TIMEOUT_MS=background-agent timeout, or 360000Positive timeout for the out-of-band Dream model turn.

  Positive timeout for the out-of-band Dream model turn.

  values: `domains.dream.agentTimeoutMs`

• PICLAW_DREAM_BACKUP_KEEP=10Number of pre-Dream note backups to retain.

  Number of pre-Dream note backups to retain.

  values: `domains.dream.backupKeep`

• PICLAW_DREAM_CRON=0 1 * * *Cron schedule for AutoDream. Evaluated in the runtime timezone (`TZ` / runtime timing config), so the default is 01:00 local runtime time.

  Cron schedule for AutoDream. Evaluated in the runtime timezone (`TZ` / runtime timing config), so the default is 01:00 local runtime time.

  values: `domains.dream.cron`

• PICLAW_DREAM_CUE_FULL_SLICE_MAX_MESSAGES=50`DREAM_CUES` full-slice cutoff for day message count

  `DREAM_CUES` full-slice cutoff for day message count

• PICLAW_DREAM_CUE_FULL_SLICE_MAX_SESSION_TREES=2`DREAM_CUES` full-slice cutoff for session-tree count

  `DREAM_CUES` full-slice cutoff for session-tree count

• PICLAW_DREAM_CUE_MAX_SNIPPETS=100Global `DREAM_CUES` snippet budget before large trees downgrade from `5+5` to `2+2`

  Global `DREAM_CUES` snippet budget before large trees downgrade from `5+5` to `2+2`

• PICLAW_DREAM_CUE_SMALL_TREE_MAX_MESSAGES=10Per-session-tree cue cutoff under which all messages from that tree are included

  Per-session-tree cue cutoff under which all messages from that tree are included

• PICLAW_DREAM_MODEL=_(unset — inherits session model)_Pin Dream / AutoDream to a specific model label (e.g. `anthropic/claude-sonnet-4-20250514`). The Dream pass applies it to the temporary Dream chat, so it also covers manual `/dream` runs.

  Pin Dream / AutoDream to a specific model label (e.g. `anthropic/claude-sonnet-4-20250514`). The Dream pass applies it to the temporary Dream chat, so it also covers manual `/dream` runs.

  values: `domains.dream.model`

• PICLAW_GITHUB_COPILOT_DYNAMIC_MODELS=1Set to `0`, `false`, or `no` to disable live Copilot model discovery

  Set to `0`, `false`, or `no` to disable live Copilot model discovery

• PICLAW_GITHUB_COPILOT_MODELS_TIMEOUT_MS=3500Timeout for the Copilot `/models` request; values below 500 ms are clamped to 500 ms

  Timeout for the Copilot `/models` request; values below 500 ms are clamped to 500 ms

• PICLAW_KEYCHAIN_KEY=_(empty)_Master key for encrypting/decrypting keychain entries

  Master key for encrypting/decrypting keychain entries

• PICLAW_KEYCHAIN_KEY_FILE=_(empty)_Read master key from a file (trimmed)

  Read master key from a file (trimmed)

• PICLAW_MAIN_SESSION_IDLE_TTL_MS=180000 (3 min)Idle TTL for the main interactive session; `PICLAW_SESSION_IDLE_TTL_MS` overrides the fallback when set

  Idle TTL for the main interactive session; `PICLAW_SESSION_IDLE_TTL_MS` overrides the fallback when set

• PICLAW_MAIN_SESSION_POOL_MAX_SIZE=1Max number of warm main chat sessions kept cached under normal conditions

  Max number of warm main chat sessions kept cached under normal conditions

• PICLAW_MAIN_SESSION_PRESSURE_IDLE_TTL_MS=60000Main-session idle TTL while memory pressure mode is active

  Main-session idle TTL while memory pressure mode is active

• PICLAW_MAIN_SESSION_PRESSURE_POOL_MAX_SIZE=1Max cached main sessions while memory pressure mode is active

  Max cached main sessions while memory pressure mode is active

• PICLAW_MAIN_SESSION_PRESSURE_RSS_BYTES=402653184 (384 MB)RSS threshold that enables memory-pressure session eviction mode

  RSS threshold that enables memory-pressure session eviction mode

• PICLAW_RECORDINGS_DIR=<PICLAW_DATA>/session-recordingsRoot directory for opt-in session trace recordings.

  Root directory for opt-in session trace recordings.

  values: `domains.sessionRecordings.directory`

• PICLAW_SEARCH_MATCH_MODE=orCompatibility alias for `domains.tools.searchMatchMode`; choose `or` (any keyword) or `and` (all keywords) for multi-word FTS queries.

  Compatibility alias for `domains.tools.searchMatchMode`; choose `or` (any keyword) or `and` (all keywords) for multi-word FTS queries.

• PICLAW_SESSION_AUTO_ROTATE=1Automatically rotate oversized session files before the next prompt

  Automatically rotate oversized session files before the next prompt

• PICLAW_SESSION_IDLE_COMPACTION_MAX_WAIT_MS=300000Max ms to wait for idle when a compaction is in progress

  Max ms to wait for idle when a compaction is in progress

• PICLAW_SESSION_IDLE_MAX_WAIT_MS=10000Max ms to wait for session idle before sending a turn response

  Max ms to wait for session idle before sending a turn response

• PICLAW_SESSION_IDLE_TTL_MS=_(empty)_Shared idle TTL override for main and side sessions when their specific variables are unset

  Shared idle TTL override for main and side sessions when their specific variables are unset

• PICLAW_SESSION_MAX_SIZE_MB=32Session file size threshold (MB) for auto-rotation warnings and pre-prompt rotation

  Session file size threshold (MB) for auto-rotation warnings and pre-prompt rotation

• PICLAW_SIDE_SESSION_IDLE_TTL_MS=60000 (1 min)Idle TTL for side/background sessions; `PICLAW_SESSION_IDLE_TTL_MS` overrides the fallback when set

  Idle TTL for side/background sessions; `PICLAW_SESSION_IDLE_TTL_MS` overrides the fallback when set

• PICLAW_SKEL_DIR=packaged skel/ directoryDeployment/package bootstrap override for the workspace skeleton source. Retained env-only because it is needed before ordinary domain config is available.

  Deployment/package bootstrap override for the workspace skeleton source. Retained env-only because it is needed before ordinary domain config is available.

• PICLAW_SKIP_BIN_LINKSet to 1 to disable launcher installation by the portable installer

  Set to 1 to disable launcher installation by the portable installer

  values: 1

• PICLAW_SMART_COMPACTION_METHOD=selectiveSmart-compaction local processing method: `selective` or `pipelined`

  Smart-compaction local processing method: `selective` or `pipelined`

• PICLAW_SSH_PORT=22SSH port for startup/default remote sessions

  SSH port for startup/default remote sessions

• PICLAW_SSH_TARGET=_(empty)_SSH target as `user@host` or `user@host:/remote/path`

  SSH target as `user@host` or `user@host:/remote/path`

• PICLAW_STORE=/workspace/.piclaw/storeSQLite database location

  SQLite database location

• PICLAW_TOOL_OUTPUT_CLEANUP_INTERVAL_MS=900000 (15 min)Cleanup interval (ms)

  Cleanup interval (ms)

• PICLAW_TOOL_OUTPUT_PREVIEW_LINE_CHARS=200Max characters per preview line in compacted tool-result summaries

  Max characters per preview line in compacted tool-result summaries

• PICLAW_TOOL_OUTPUT_PREVIEW_LINES=8Preview lines shown in compacted tool-result summaries

  Preview lines shown in compacted tool-result summaries

• PICLAW_TOOL_OUTPUT_RETENTION_DAYS=_(legacy)_Days to retain stored tool outputs (deprecated; use `_MS`)

  Days to retain stored tool outputs (deprecated; use `_MS`)

• PICLAW_TOOL_OUTPUT_RETENTION_MS=2592000000 (30 days)Milliseconds to retain stored tool outputs (preferred; overrides `_DAYS`; values are capped at 30 days)

  Milliseconds to retain stored tool outputs (preferred; overrides `_DAYS`; values are capped at 30 days)

• PICLAW_TOOL_OUTPUT_STORE_BYTES=4096Store tool output externally when payload exceeds this byte threshold

  Store tool output externally when payload exceeds this byte threshold

• PICLAW_TOOL_OUTPUT_STORE_LINES=40Store tool output externally when payload exceeds this line threshold

  Store tool output externally when payload exceeds this line threshold

• PICLAW_TOOL_OUTPUT_STORE_THRESHOLDS_BY_TOOL=_(empty)_Optional JSON map of per-tool byte/line thresholds, e.g. `{"proxmox":{"bytes":16384,"lines":200}}`

  Optional JSON map of per-tool byte/line thresholds, e.g. `{"proxmox":{"bytes":16384,"lines":200}}`

• PICLAW_TOOL_RESULT_COMPACTION_ENABLED=1Master runtime gate for tool-result compaction

  Master runtime gate for tool-result compaction

• PICLAW_TOOL_RESULT_COMPACTION_TOOLS=bash,powershell,exec_batchComma-separated or JSON-array allowlist of tools eligible for compaction

  Comma-separated or JSON-array allowlist of tools eligible for compaction

• PICLAW_TOOL_RESULT_SEMANTIC_SUMMARY_ENABLED=1Enable semantic summary generation for compacted tool results

  Enable semantic summary generation for compacted tool results

• PICLAW_TOOL_RESULT_SEMANTIC_SUMMARY_MAX_INPUT_CHARS=12000Max sampled tool-output characters sent to semantic summarizer

  Max sampled tool-output characters sent to semantic summarizer

• PICLAW_TOOL_RESULT_SEMANTIC_SUMMARY_MAX_TOKENS=320Max generated semantic summary tokens

  Max generated semantic summary tokens

• PICLAW_TOOL_RESULT_SEMANTIC_SUMMARY_TIMEOUT_MS=12000Timeout for semantic summary generation before preview fallback

  Timeout for semantic summary generation before preview fallback

• PICLAW_TRUST_PROXY=0Trust `Forwarded` / `X-Forwarded-*` headers from a reverse proxy for origin, host, proto, and client IP handling

  Trust `Forwarded` / `X-Forwarded-*` headers from a reverse proxy for origin, host, proto, and client IP handling

• PICLAW_TURN_MAX_TOOL_EXECUTIONS=64Authoritative per-turn completed tool-execution budget. Settings persists `domains.agent.toolUseMessageBudget`; values are clamped to `8..512`. Legacy `PICLAW_TURN_MAX_TOOL_USE_MESSAGES` and `PICLAW_MID_TURN_TOOL_EXECUTION_HARD_CEILING` are lower-priority compatibility aliases.

  Authoritative per-turn completed tool-execution budget. Settings persists `domains.agent.toolUseMessageBudget`; values are clamped to `8..512`. Legacy `PICLAW_TURN_MAX_TOOL_USE_MESSAGES` and `PICLAW_MID_TURN_TOOL_EXECUTION_HARD_CEILING` are lower-priority compatibility aliases.

• PICLAW_USER_AVATAR=_(empty)_Avatar URL for the human user

  Avatar URL for the human user

• PICLAW_USER_AVATAR_BACKGROUND=_(empty)_CSS background colour for the user avatar circle

  CSS background colour for the user avatar circle

• PICLAW_USER_NAME=_(empty)_Display name for the human user in the web UI

  Display name for the human user in the web UI

• PICLAW_WEB_BIND_HOST=127.0.0.1Host interface the compose port mapping is published on

  Host interface the compose port mapping is published on

• PICLAW_WEB_HOST=0.0.0.0Bind address

  Bind address

• PICLAW_WEB_IDLE_TIMEOUT=0 (disabled)Drop idle clients after this many seconds

  Drop idle clients after this many seconds

• PICLAW_WEB_INTERNAL_SECRET=_(empty)_Shared secret for unattended POST/PATCH calls to `/internal/post`; required when TOTP is enabled and you want automations to keep posting.

  Shared secret for unattended POST/PATCH calls to `/internal/post`; required when TOTP is enabled and you want automations to keep posting.

• PICLAW_WEB_MAX_CONTENT_CHARS=262144Compatibility alias for `domains.web.contentMaxChars`; max message size in characters, with oversized messages truncated with metadata.

  Compatibility alias for `domains.web.contentMaxChars`; max message size in characters, with oversized messages truncated with metadata.

• PICLAW_WEB_NOTIFICATION_DEBUG_LABELS=0Append `[Local]` / `[Web Push]` markers to notification titles for delivery debugging

  Append `[Local]` / `[Web Push]` markers to notification titles for delivery debugging

• PICLAW_WEB_PASSKEY_MODE=totp-fallbackPasskey mode: `totp-fallback`, `passkey-only`, or `totp-only`.

  Passkey mode: `totp-fallback`, `passkey-only`, or `totp-only`.

• PICLAW_WEB_PERSIST_THINKING=0Persist agent reasoning traces into the database so they survive page reloads. See thinking-persistence.md for privacy implications.

  Persist agent reasoning traces into the database so they survive page reloads. See thinking-persistence.md for privacy implications.

• PICLAW_WEB_PERSIST_THINKING_MAX_CHARS=100000Per-turn cap on persisted thinking text (UTF-16 surrogate-safe).

  Per-turn cap on persisted thinking text (UTF-16 surrogate-safe).

• PICLAW_WEB_PORT=8080Web UI port

  Web UI port

• PICLAW_WEB_PREVIEW_CHARS=16000Compatibility alias for `domains.web.contentPreviewChars`; preview threshold, capped at the hard content limit.

  Compatibility alias for `domains.web.contentPreviewChars`; preview threshold, capped at the hard content limit.

• PICLAW_WEB_SESSION_TTL=604800 (7 days)Session cookie lifetime in seconds.

  Session cookie lifetime in seconds.

• PICLAW_WEB_TERMINAL_ENABLED=1 on Linux/macOS, 0 on WindowsEnable or disable the authenticated web terminal backend/pane

  Enable or disable the authenticated web terminal backend/pane

• PICLAW_WEB_TLS_CERT=_(empty)_Path to TLS certificate; enables HTTPS

  Path to TLS certificate; enables HTTPS

• PICLAW_WEB_TLS_KEY=_(empty)_Path to TLS private key; enables HTTPS

  Path to TLS private key; enables HTTPS

• PICLAW_WEB_TOTP_SECRET=_(empty)_Base32 TOTP secret. When set, `/login` requires a 6-digit code before issuing a `piclaw_session` cookie. Prefer keychain/service-environment storage; plaintext JSON remains a legacy compatibility path for the existing `/totp` flow.

  Base32 TOTP secret. When set, `/login` requires a 6-digit code before issuing a `piclaw_session` cookie. Prefer keychain/service-environment storage; plaintext JSON remains a legacy compatibility path for the existing `/totp` flow.

• PICLAW_WEB_TOTP_WINDOW=1TOTP step skew (number of 30s windows to accept on either side).

  TOTP step skew (number of 30s windows to accept on either side).

• PICLAW_WEB_VNC_ALLOW_DIRECT=1 on Linux/macOS/WindowsAllow or disable direct VNC targets supplied at runtime (`PICLAW_VNC_ALLOW_DIRECT` alias)

  Allow or disable direct VNC targets supplied at runtime (`PICLAW_VNC_ALLOW_DIRECT` alias)

• PICLAW_WEB_VNC_TARGETS=_(empty)_JSON allowlist for VNC targets (or use `PICLAW_VNC_TARGETS`). Supports array or object form.

  JSON allowlist for VNC targets (or use `PICLAW_VNC_TARGETS`). Supports array or object form.

• PICLAW_WHATSAPP_PHONE=_(empty)_Alias for `WHATSAPP_PHONE`

  Alias for `WHATSAPP_PHONE`

• PICLAW_WORKSPACE=/workspaceWorking directory for `pi` + `piclaw`

  Working directory for `pi` + `piclaw`

• PUID=1000Container user id remapped by /entrypoint.sh on startup (compose stack)

  Container user id remapped by /entrypoint.sh on startup (compose stack)

• PUSHOVER_APP_TOKENPushover app token for push notifications for scheduled tasks and IPC messages

  Pushover app token for push notifications for scheduled tasks and IPC messages

• PUSHOVER_DEVICEOptional Pushover device name

  Optional Pushover device name

• PUSHOVER_PRIORITYOptional Pushover message priority

  Optional Pushover message priority

• PUSHOVER_SOUNDOptional Pushover notification sound

  Optional Pushover notification sound

• PUSHOVER_USER_KEYPushover user key for push notifications

  Pushover user key for push notifications

• SUPERVISOR_CONF=/workspace/.piclaw/supervisor/supervisord.confSupervisor config path (falls back to `/etc/supervisor/supervisord.conf`)

  Supervisor config path (falls back to `/etc/supervisor/supervisord.conf`)

• WORKSPACE_PATH=./workspacePath bind-mounted as the workspace by docker-compose.yml instead of ./workspace

  Path bind-mounted as the workspace by docker-compose.yml instead of ./workspace