Your Name
01aa7f3e8f
User hit 'API error 402: ... You requested up to 131072 tokens, but can only afford 4511' on the assist alias: no provider ever sent max_tokens, so OpenRouter's credit pre-check billed the routed model's full worst-case output; user also asked to bound session history to the last 5 requests/responses. Architect decisions: - AI_MAX_TOKENS (num, default 2048): sent as max_tokens on OpenRouter and generationConfig.maxOutputTokens on Gemini — a real per-request cost ceiling. llamacpp unchanged (local/free, no pre-check). - AI_SESSION_TURNS (num, default 40 kept back-compat; messages, 2 per exchange — 10 = last 5 conversations): resolved lazily in session_push because config loads after the hardcoded line-25 default. - Both registered in the bin/pos-ai POS_CONFIG @General section, so they appear in 'pos config ai' with num: validation. Reviewer hardening (CHANGES_REQUIRED -> fixed): unguarded env input could reach jq tonumber (0/-5/010/abc all savable via config-ui's ^-?[0-9]+$) and abort the CLI; both providers and session_push now guard with ^[1-9][0-9]*$ and fall back to the default. Verified: fake-curl shim smoke (16 provider-body + 12 session-window checks incl. the 010-regression proof), make gen idempotent, make check OK, make lint 0 FAIL/0 WARN, make test 17 files / 299 checks / 0 fail (~49s), bash -n clean, git diff --check clean. Reviewer ACCEPT (twice). Tester regression round (permanent provider-body + session-pruning coverage) intentionally not run this cycle — user's call; remains a documented follow-up.
5.4 KiB
pos HOW-TO Guides
Hands-on, copy-paste guides for every pos category. These are the tutorial
layer: flags, examples, configuration, recipes, and troubleshooting. For the
authoritative one-line reference (every command + flag), see
DOC/POS.md.
Quick start — pick your category
| Category | What you can do | Guide |
|---|---|---|
pos ai |
Chat with Google Gemini from CLI or Telegram | ai |
pos network |
IP info, hotspot, scan, port check, aria2 download daemon | network |
pos docker |
Compose services, container dashboards, disposable VMs | docker |
pos media |
Download audio/video via yt-dlp; incremental YouTube channel sync | media |
pos system |
Backups, firewall, health dashboard | system |
pos system schedule |
Scheduled jobs: run a command on a timer, notify on threshold/change/error or silently | schedule |
pos ssh |
Load keys into the agent | ssh |
pos share |
Share USB devices & filesystems over the network (USB, NFS, SMB) | share |
pos communication |
Send Telegram/Matrix messages & alerts, /command listeners, Android mirroring (scrcpy) | communication |
pos entertainment |
Scheduled auto-messages from public APIs | entertainment |
Every tool is bin/pos-<category>-<command>; run pos <category> --help to
list a category, and any tool's --help/--help-style usage for full flags.
Cross-cutting concepts (read once)
These apply to several categories at once.
Config files — ~/.config/linux_post_install/
Runtime tool config lives here as <tool>.env files (chmod 600). Precedence
is always flags > environment > config file. postinstall.sh installs the
templates (without overwriting an existing file):
| File | Used by | Keys |
|---|---|---|
telegram.env |
pos communication telegram sender / listener, everything that alerts |
TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID |
matrix.env |
pos communication matrix sender / listener |
MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN, MATRIX_USER_ID, MATRIX_ROOM_ID |
scrcpy.env |
pos communication scrcpy |
SCRCPY_SERIAL, SCRCPY_MAX_SIZE, SCRCPY_MAX_FPS, SCRCPY_BIT_RATE, SCRCPY_FULLSCREEN, SCRCPY_NEW_DISPLAY, SCRCPY_AUDIO, SCRCPY_RECORD_DIR, SCRCPY_PUSH_TARGET, SCRCPY_EXTRA_FLAGS |
notify.env |
lib/notify.sh (all alerting) |
NOTIFY_PLATFORM (e.g. telegram,matrix) |
system.env |
pos system health, pos system backup |
BACKUP_SERVICE_ROOTS, HEALTH_BACKUP_MAX_AGE_DAYS |
compose.env |
pos docker compose |
TS_AUTHKEY, TZ, DNS_SERVER, SERVICES_BASE |
entertainment.env |
pos entertainment * |
plugin keys (WEATHER_LAT…), ENABLED |
ai.env |
pos ai |
AI_PROVIDER, AI_API_KEY, AI_MODEL, AI_SYSTEM_PROMPT, AI_MAX_TOKENS, AI_SESSION_TURNS, AI_GEMINI_API_KEY, AI_GEMINI_MODEL, OPENROUTER_API_KEY, OPENROUTER_MODEL |
schedule.d/ |
pos system schedule |
one <name>.env per job: INTERVAL, NOTIFY, MSG, RULE, COMMAND |
pos config telegram # set TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID
pos config matrix # set MATRIX_HOMESERVER / MATRIX_ROOM_ID, then:
pos communication matrix sender login --user @you:example.org # fetch an access token
pos entertainment config set WEATHER_LAT=36.51 WEATHER_LON=40.75
The notify system — lib/notify.sh
Any tool that "announces" something calls notify_send, which delivers to every
platform in NOTIFY_PLATFORM (default telegram). It is silent-fail: if no
platform is configured it warns and never breaks the calling tool.
# ~/.config/linux_post_install/notify.env
NOTIFY_PLATFORM=telegram # comma-separated to send to all
Ship with telegram and matrix — add both to NOTIFY_PLATFORM to fan out
alerts (Matrix needs pos config matrix + a login-fetched token first).
Adding another platform = create bin/pos-communication-<p> implementing
send <value> [--markdown] and list it. See
DOC/DEV.md → Alerting for the contract.
Scheduling
- Daily health digest — add a
dailyschedule jobCOMMAND=pos system healthwithNOTIFY=alwaysviapos system schedule config(the oldpos-health.{service,timer}units are gone). See system. - Entertainment auto-triggers — per-plugin
pos entertainment enable <plugin> <interval>, uses systemd user timers (or cron fallback). See entertainment. pos system schedulejobs — run any command on a per-job timer and notify on threshold/change/error/always or silently. See schedule.
Gotcha: run from anywhere
install.sh copies bin/pos* + lib/* to /usr/local/bin, so pos works
after the repo is deleted. After pulling new changes, re-run ./install.sh (or
just copy the changed bin//lib/ files) to refresh the installed copies.
How the guides relate to DOC/POS.md
DOC/POS.md= reference. One table row per command, full flag lists, compose/ScaleTail config strategy. Use it when you need the exact flag.- This guide set = how-to. Examples, recipes, config walk-throughs, and troubleshooting, linking back to POS.md rather than duplicating it.