heraldesk 1.16.3__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- heraldesk-1.16.3/.gitignore +30 -0
- heraldesk-1.16.3/LICENSE +21 -0
- heraldesk-1.16.3/PKG-INFO +512 -0
- heraldesk-1.16.3/README.md +466 -0
- heraldesk-1.16.3/alembic/env.py +62 -0
- heraldesk-1.16.3/alembic/script.py.mako +24 -0
- heraldesk-1.16.3/alembic/versions/0001_initial_empty.py +26 -0
- heraldesk-1.16.3/alembic/versions/0002_core_domain.py +171 -0
- heraldesk-1.16.3/alembic/versions/0003_agent_runs.py +58 -0
- heraldesk-1.16.3/alembic/versions/0004_content_pipeline.py +153 -0
- heraldesk-1.16.3/alembic/versions/0005_approvals.py +94 -0
- heraldesk-1.16.3/alembic/versions/0006_publisher.py +63 -0
- heraldesk-1.16.3/alembic/versions/0007_telegram.py +123 -0
- heraldesk-1.16.3/alembic/versions/0008_serve.py +42 -0
- heraldesk-1.16.3/alembic/versions/0009_inbox_triage.py +57 -0
- heraldesk-1.16.3/alembic/versions/0010_social_account_label.py +35 -0
- heraldesk-1.16.3/alembic.ini +4 -0
- heraldesk-1.16.3/deploy/README.md +72 -0
- heraldesk-1.16.3/docs/platforms/README.md +74 -0
- heraldesk-1.16.3/examples/README.md +31 -0
- heraldesk-1.16.3/examples/plugin/pyproject.toml +13 -0
- heraldesk-1.16.3/pyproject.toml +113 -0
- heraldesk-1.16.3/src/heraldesk/__init__.py +3 -0
- heraldesk-1.16.3/src/heraldesk/agents/__init__.py +1 -0
- heraldesk-1.16.3/src/heraldesk/agents/analyst.py +1 -0
- heraldesk-1.16.3/src/heraldesk/agents/base.py +53 -0
- heraldesk-1.16.3/src/heraldesk/agents/community.py +1 -0
- heraldesk-1.16.3/src/heraldesk/agents/compliance.py +45 -0
- heraldesk-1.16.3/src/heraldesk/agents/designer.py +1 -0
- heraldesk-1.16.3/src/heraldesk/agents/errors.py +23 -0
- heraldesk-1.16.3/src/heraldesk/agents/prompting.py +152 -0
- heraldesk-1.16.3/src/heraldesk/agents/prompts/.gitkeep +0 -0
- heraldesk-1.16.3/src/heraldesk/agents/prompts/compliance.md +13 -0
- heraldesk-1.16.3/src/heraldesk/agents/prompts/researcher.md +12 -0
- heraldesk-1.16.3/src/heraldesk/agents/prompts/strategist.md +11 -0
- heraldesk-1.16.3/src/heraldesk/agents/prompts/writer.md +24 -0
- heraldesk-1.16.3/src/heraldesk/agents/researcher.py +54 -0
- heraldesk-1.16.3/src/heraldesk/agents/runner.py +365 -0
- heraldesk-1.16.3/src/heraldesk/agents/schemas.py +116 -0
- heraldesk-1.16.3/src/heraldesk/agents/strategist.py +35 -0
- heraldesk-1.16.3/src/heraldesk/agents/writer.py +67 -0
- heraldesk-1.16.3/src/heraldesk/analyst.py +345 -0
- heraldesk-1.16.3/src/heraldesk/api/__init__.py +5 -0
- heraldesk-1.16.3/src/heraldesk/api/app.py +447 -0
- heraldesk-1.16.3/src/heraldesk/cli/__init__.py +1 -0
- heraldesk-1.16.3/src/heraldesk/cli/account.py +351 -0
- heraldesk-1.16.3/src/heraldesk/cli/agent.py +104 -0
- heraldesk-1.16.3/src/heraldesk/cli/backup.py +173 -0
- heraldesk-1.16.3/src/heraldesk/cli/common.py +42 -0
- heraldesk-1.16.3/src/heraldesk/cli/inbox.py +211 -0
- heraldesk-1.16.3/src/heraldesk/cli/main.py +306 -0
- heraldesk-1.16.3/src/heraldesk/cli/plugins.py +63 -0
- heraldesk-1.16.3/src/heraldesk/cli/profile.py +204 -0
- heraldesk-1.16.3/src/heraldesk/cli/publish.py +98 -0
- heraldesk-1.16.3/src/heraldesk/cli/queue.py +257 -0
- heraldesk-1.16.3/src/heraldesk/cli/report.py +55 -0
- heraldesk-1.16.3/src/heraldesk/cli/rotate_key.py +269 -0
- heraldesk-1.16.3/src/heraldesk/cli/run.py +149 -0
- heraldesk-1.16.3/src/heraldesk/cli/runs.py +89 -0
- heraldesk-1.16.3/src/heraldesk/cli/scheduler.py +128 -0
- heraldesk-1.16.3/src/heraldesk/cli/telegram.py +239 -0
- heraldesk-1.16.3/src/heraldesk/cli/upgrade.py +62 -0
- heraldesk-1.16.3/src/heraldesk/community.py +338 -0
- heraldesk-1.16.3/src/heraldesk/config.py +197 -0
- heraldesk-1.16.3/src/heraldesk/core/__init__.py +1 -0
- heraldesk-1.16.3/src/heraldesk/core/audit.py +114 -0
- heraldesk-1.16.3/src/heraldesk/core/backup.py +513 -0
- heraldesk-1.16.3/src/heraldesk/core/bootstrap.py +123 -0
- heraldesk-1.16.3/src/heraldesk/core/crypto.py +177 -0
- heraldesk-1.16.3/src/heraldesk/core/doctor.py +509 -0
- heraldesk-1.16.3/src/heraldesk/core/locks.py +204 -0
- heraldesk-1.16.3/src/heraldesk/core/logging.py +107 -0
- heraldesk-1.16.3/src/heraldesk/core/redact.py +95 -0
- heraldesk-1.16.3/src/heraldesk/db/__init__.py +1 -0
- heraldesk-1.16.3/src/heraldesk/db/base.py +12 -0
- heraldesk-1.16.3/src/heraldesk/db/engine.py +85 -0
- heraldesk-1.16.3/src/heraldesk/db/migrations.py +52 -0
- heraldesk-1.16.3/src/heraldesk/db/models.py +561 -0
- heraldesk-1.16.3/src/heraldesk/db/repositories.py +1359 -0
- heraldesk-1.16.3/src/heraldesk/db/scope.py +27 -0
- heraldesk-1.16.3/src/heraldesk/db/session.py +46 -0
- heraldesk-1.16.3/src/heraldesk/domain/__init__.py +1 -0
- heraldesk-1.16.3/src/heraldesk/domain/accounts.py +246 -0
- heraldesk-1.16.3/src/heraldesk/domain/approvals.py +698 -0
- heraldesk-1.16.3/src/heraldesk/domain/autonomy.py +187 -0
- heraldesk-1.16.3/src/heraldesk/domain/content.py +181 -0
- heraldesk-1.16.3/src/heraldesk/domain/errors.py +63 -0
- heraldesk-1.16.3/src/heraldesk/domain/notifications.py +74 -0
- heraldesk-1.16.3/src/heraldesk/domain/policy.py +195 -0
- heraldesk-1.16.3/src/heraldesk/domain/profiles.py +619 -0
- heraldesk-1.16.3/src/heraldesk/domain/scheduling.py +181 -0
- heraldesk-1.16.3/src/heraldesk/llm/__init__.py +27 -0
- heraldesk-1.16.3/src/heraldesk/llm/budget.py +125 -0
- heraldesk-1.16.3/src/heraldesk/llm/errors.py +32 -0
- heraldesk-1.16.3/src/heraldesk/llm/factory.py +86 -0
- heraldesk-1.16.3/src/heraldesk/llm/fake.py +105 -0
- heraldesk-1.16.3/src/heraldesk/llm/fixtures/compliance.json +5 -0
- heraldesk-1.16.3/src/heraldesk/llm/fixtures/researcher.json +13 -0
- heraldesk-1.16.3/src/heraldesk/llm/fixtures/strategist.json +13 -0
- heraldesk-1.16.3/src/heraldesk/llm/fixtures/writer.json +7 -0
- heraldesk-1.16.3/src/heraldesk/llm/litellm_provider.py +101 -0
- heraldesk-1.16.3/src/heraldesk/llm/types.py +54 -0
- heraldesk-1.16.3/src/heraldesk/paths.py +118 -0
- heraldesk-1.16.3/src/heraldesk/pipelines/__init__.py +1 -0
- heraldesk-1.16.3/src/heraldesk/pipelines/daily_content.py +809 -0
- heraldesk-1.16.3/src/heraldesk/pipelines/onboarding.py +1 -0
- heraldesk-1.16.3/src/heraldesk/pipelines/reply_triage.py +1 -0
- heraldesk-1.16.3/src/heraldesk/pipelines/weekly_report.py +1 -0
- heraldesk-1.16.3/src/heraldesk/platforms/__init__.py +108 -0
- heraldesk-1.16.3/src/heraldesk/platforms/base.py +159 -0
- heraldesk-1.16.3/src/heraldesk/platforms/facebook.py +1 -0
- heraldesk-1.16.3/src/heraldesk/platforms/fake.py +52 -0
- heraldesk-1.16.3/src/heraldesk/platforms/instagram.py +1 -0
- heraldesk-1.16.3/src/heraldesk/platforms/linkedin.py +1 -0
- heraldesk-1.16.3/src/heraldesk/platforms/nostr.py +371 -0
- heraldesk-1.16.3/src/heraldesk/platforms/nostr_keys.py +188 -0
- heraldesk-1.16.3/src/heraldesk/platforms/threads.py +371 -0
- heraldesk-1.16.3/src/heraldesk/platforms/x.py +1 -0
- heraldesk-1.16.3/src/heraldesk/plugins.py +110 -0
- heraldesk-1.16.3/src/heraldesk/publisher/__init__.py +627 -0
- heraldesk-1.16.3/src/heraldesk/py.typed +0 -0
- heraldesk-1.16.3/src/heraldesk/quality/__init__.py +16 -0
- heraldesk-1.16.3/src/heraldesk/quality/lint.py +112 -0
- heraldesk-1.16.3/src/heraldesk/scheduler/__init__.py +1 -0
- heraldesk-1.16.3/src/heraldesk/scheduler/runner.py +256 -0
- heraldesk-1.16.3/src/heraldesk/server/__init__.py +1 -0
- heraldesk-1.16.3/src/heraldesk/server/background.py +225 -0
- heraldesk-1.16.3/src/heraldesk/server/database.py +62 -0
- heraldesk-1.16.3/src/heraldesk/server/run.py +160 -0
- heraldesk-1.16.3/src/heraldesk/telegram/__init__.py +1 -0
- heraldesk-1.16.3/src/heraldesk/telegram/base.py +115 -0
- heraldesk-1.16.3/src/heraldesk/telegram/bot_api.py +106 -0
- heraldesk-1.16.3/src/heraldesk/telegram/credentials.py +125 -0
- heraldesk-1.16.3/src/heraldesk/telegram/fake.py +72 -0
- heraldesk-1.16.3/src/heraldesk/telegram/formatting.py +121 -0
- heraldesk-1.16.3/src/heraldesk/telegram/inbox.py +375 -0
- heraldesk-1.16.3/src/heraldesk/telegram/notifier.py +330 -0
- heraldesk-1.16.3/src/heraldesk/telegram/poller.py +102 -0
- heraldesk-1.16.3/src/heraldesk/telegram/runtime.py +55 -0
- heraldesk-1.16.3/src/heraldesk/tools/__init__.py +25 -0
- heraldesk-1.16.3/src/heraldesk/tools/web_search.py +240 -0
- heraldesk-1.16.3/src/heraldesk/web/__init__.py +1 -0
- heraldesk-1.16.3/src/heraldesk/web/api.py +461 -0
- heraldesk-1.16.3/src/heraldesk/web/auth.py +436 -0
- heraldesk-1.16.3/src/heraldesk/web/context.py +36 -0
- heraldesk-1.16.3/src/heraldesk/web/errors.py +55 -0
- heraldesk-1.16.3/src/heraldesk/web/profile_editor.py +141 -0
- heraldesk-1.16.3/src/heraldesk/web/rendering.py +57 -0
- heraldesk-1.16.3/src/heraldesk/web/service.py +901 -0
- heraldesk-1.16.3/src/heraldesk/web/static/.gitkeep +0 -0
- heraldesk-1.16.3/src/heraldesk/web/static/app.css +241 -0
- heraldesk-1.16.3/src/heraldesk/web/static/app.js +48 -0
- heraldesk-1.16.3/src/heraldesk/web/static/htmx.LICENSE +13 -0
- heraldesk-1.16.3/src/heraldesk/web/static/htmx.min.js +1 -0
- heraldesk-1.16.3/src/heraldesk/web/templates/.gitkeep +0 -0
- heraldesk-1.16.3/src/heraldesk/web/templates/audit.html +43 -0
- heraldesk-1.16.3/src/heraldesk/web/templates/base.html +46 -0
- heraldesk-1.16.3/src/heraldesk/web/templates/calendar.html +39 -0
- heraldesk-1.16.3/src/heraldesk/web/templates/cost.html +52 -0
- heraldesk-1.16.3/src/heraldesk/web/templates/dashboard.html +81 -0
- heraldesk-1.16.3/src/heraldesk/web/templates/error.html +10 -0
- heraldesk-1.16.3/src/heraldesk/web/templates/inbox.html +36 -0
- heraldesk-1.16.3/src/heraldesk/web/templates/login.html +16 -0
- heraldesk-1.16.3/src/heraldesk/web/templates/partials/error_row.html +3 -0
- heraldesk-1.16.3/src/heraldesk/web/templates/partials/inbox_item.html +38 -0
- heraldesk-1.16.3/src/heraldesk/web/templates/partials/queue_row.html +34 -0
- heraldesk-1.16.3/src/heraldesk/web/templates/profile_edit.html +23 -0
- heraldesk-1.16.3/src/heraldesk/web/templates/profiles.html +43 -0
- heraldesk-1.16.3/src/heraldesk/web/templates/queue.html +38 -0
- heraldesk-1.16.3/src/heraldesk/web/templates/queue_detail.html +65 -0
- heraldesk-1.16.3/src/heraldesk/web/templates/report.html +15 -0
- heraldesk-1.16.3/src/heraldesk/web/templates/reports.html +60 -0
- heraldesk-1.16.3/src/heraldesk/web/ui.py +915 -0
- heraldesk-1.16.3/tests/__init__.py +1 -0
- heraldesk-1.16.3/tests/conftest.py +114 -0
- heraldesk-1.16.3/tests/test_accounts.py +313 -0
- heraldesk-1.16.3/tests/test_agent_runner.py +150 -0
- heraldesk-1.16.3/tests/test_agent_writer.py +91 -0
- heraldesk-1.16.3/tests/test_alembic.py +193 -0
- heraldesk-1.16.3/tests/test_analyst.py +253 -0
- heraldesk-1.16.3/tests/test_approvals.py +571 -0
- heraldesk-1.16.3/tests/test_audit.py +140 -0
- heraldesk-1.16.3/tests/test_autonomy.py +192 -0
- heraldesk-1.16.3/tests/test_backup.py +298 -0
- heraldesk-1.16.3/tests/test_cli.py +127 -0
- heraldesk-1.16.3/tests/test_cli_m1.py +304 -0
- heraldesk-1.16.3/tests/test_cli_m10.py +245 -0
- heraldesk-1.16.3/tests/test_cli_m2.py +102 -0
- heraldesk-1.16.3/tests/test_cli_m3.py +102 -0
- heraldesk-1.16.3/tests/test_cli_m4.py +271 -0
- heraldesk-1.16.3/tests/test_cli_m5.py +323 -0
- heraldesk-1.16.3/tests/test_cli_m6.py +135 -0
- heraldesk-1.16.3/tests/test_cli_m8.py +265 -0
- heraldesk-1.16.3/tests/test_cli_m9.py +235 -0
- heraldesk-1.16.3/tests/test_cli_plugins.py +85 -0
- heraldesk-1.16.3/tests/test_cli_rotate_key.py +240 -0
- heraldesk-1.16.3/tests/test_cli_threads_refresh.py +97 -0
- heraldesk-1.16.3/tests/test_cli_upgrade.py +47 -0
- heraldesk-1.16.3/tests/test_community.py +202 -0
- heraldesk-1.16.3/tests/test_config.py +124 -0
- heraldesk-1.16.3/tests/test_content_state_machine.py +106 -0
- heraldesk-1.16.3/tests/test_cost_cap.py +163 -0
- heraldesk-1.16.3/tests/test_crypto.py +64 -0
- heraldesk-1.16.3/tests/test_daily_content.py +448 -0
- heraldesk-1.16.3/tests/test_doctor.py +292 -0
- heraldesk-1.16.3/tests/test_examples.py +47 -0
- heraldesk-1.16.3/tests/test_hardening.py +125 -0
- heraldesk-1.16.3/tests/test_init.py +94 -0
- heraldesk-1.16.3/tests/test_isolation.py +156 -0
- heraldesk-1.16.3/tests/test_killswitch.py +137 -0
- heraldesk-1.16.3/tests/test_llm_layer.py +106 -0
- heraldesk-1.16.3/tests/test_logging.py +65 -0
- heraldesk-1.16.3/tests/test_nostr_adapter.py +283 -0
- heraldesk-1.16.3/tests/test_notifications.py +472 -0
- heraldesk-1.16.3/tests/test_paths.py +81 -0
- heraldesk-1.16.3/tests/test_plugins.py +209 -0
- heraldesk-1.16.3/tests/test_policy.py +138 -0
- heraldesk-1.16.3/tests/test_profiles.py +177 -0
- heraldesk-1.16.3/tests/test_prompting.py +102 -0
- heraldesk-1.16.3/tests/test_publisher.py +458 -0
- heraldesk-1.16.3/tests/test_publisher_nostr.py +267 -0
- heraldesk-1.16.3/tests/test_quality_lint.py +67 -0
- heraldesk-1.16.3/tests/test_research_search.py +72 -0
- heraldesk-1.16.3/tests/test_retention.py +91 -0
- heraldesk-1.16.3/tests/test_scheduler.py +379 -0
- heraldesk-1.16.3/tests/test_scheduling_policy.py +334 -0
- heraldesk-1.16.3/tests/test_secrets.py +145 -0
- heraldesk-1.16.3/tests/test_serve.py +558 -0
- heraldesk-1.16.3/tests/test_server_lock.py +45 -0
- heraldesk-1.16.3/tests/test_telegram_credentials.py +72 -0
- heraldesk-1.16.3/tests/test_telegram_inbox.py +237 -0
- heraldesk-1.16.3/tests/test_telegram_poller.py +93 -0
- heraldesk-1.16.3/tests/test_threads_adapter.py +285 -0
- heraldesk-1.16.3/tests/test_web_api.py +625 -0
- heraldesk-1.16.3/tests/test_web_auth.py +297 -0
- heraldesk-1.16.3/tests/test_web_ui.py +674 -0
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
.venv/
|
|
5
|
+
.pytest_cache/
|
|
6
|
+
.mypy_cache/
|
|
7
|
+
.ruff_cache/
|
|
8
|
+
dist/
|
|
9
|
+
build/
|
|
10
|
+
*.egg-info/
|
|
11
|
+
|
|
12
|
+
# Secrets and local data (NEVER commit)
|
|
13
|
+
.env
|
|
14
|
+
.env.*
|
|
15
|
+
secret.key
|
|
16
|
+
*.db
|
|
17
|
+
*.db-wal
|
|
18
|
+
*.db-shm
|
|
19
|
+
.heraldesk/
|
|
20
|
+
data/
|
|
21
|
+
backups/
|
|
22
|
+
logs/
|
|
23
|
+
reports/
|
|
24
|
+
*.zip
|
|
25
|
+
ANSWERS-BEFORE-M0.md
|
|
26
|
+
|
|
27
|
+
# Editors / OS
|
|
28
|
+
.vscode/
|
|
29
|
+
.idea/
|
|
30
|
+
.DS_Store
|
heraldesk-1.16.3/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Abeng
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,512 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: heraldesk
|
|
3
|
+
Version: 1.16.3
|
|
4
|
+
Summary: Your autonomous social media department. Self-hosted, open source, single-user.
|
|
5
|
+
Project-URL: Homepage, https://github.com/abengkris/heraldesk
|
|
6
|
+
Project-URL: Documentation, https://github.com/abengkris/heraldesk/blob/main/docs/architecture.md
|
|
7
|
+
Project-URL: Repository, https://github.com/abengkris/heraldesk
|
|
8
|
+
Project-URL: Issues, https://github.com/abengkris/heraldesk/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/abengkris/heraldesk/blob/main/CHANGELOG.md
|
|
10
|
+
Author: Abeng
|
|
11
|
+
License-Expression: MIT
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
Keywords: agents,automation,llm,self-hosted,social-media
|
|
14
|
+
Classifier: Development Status :: 4 - Beta
|
|
15
|
+
Classifier: Environment :: Console
|
|
16
|
+
Classifier: Environment :: Web Environment
|
|
17
|
+
Classifier: Framework :: FastAPI
|
|
18
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
19
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
20
|
+
Classifier: Operating System :: MacOS
|
|
21
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
22
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
24
|
+
Classifier: Typing :: Typed
|
|
25
|
+
Requires-Python: <3.13,>=3.12
|
|
26
|
+
Requires-Dist: alembic<2,>=1.14
|
|
27
|
+
Requires-Dist: apscheduler<4,>=3.10
|
|
28
|
+
Requires-Dist: bleach<7,>=6.2
|
|
29
|
+
Requires-Dist: coincurve<22,>=21.0
|
|
30
|
+
Requires-Dist: cryptography<52,>=43
|
|
31
|
+
Requires-Dist: fastapi<1,>=0.115
|
|
32
|
+
Requires-Dist: jinja2<4,>=3.1
|
|
33
|
+
Requires-Dist: litellm<2,>=1.55
|
|
34
|
+
Requires-Dist: markdown<4,>=3.7
|
|
35
|
+
Requires-Dist: pydantic-settings<3,>=2.6
|
|
36
|
+
Requires-Dist: python-dotenv>=1.0
|
|
37
|
+
Requires-Dist: python-multipart<1,>=0.0.20
|
|
38
|
+
Requires-Dist: pyyaml>=6.0.2
|
|
39
|
+
Requires-Dist: rich<16,>=13.9
|
|
40
|
+
Requires-Dist: sqlalchemy<3,>=2.0.36
|
|
41
|
+
Requires-Dist: typer<1,>=0.15
|
|
42
|
+
Requires-Dist: tzdata>=2024.1
|
|
43
|
+
Requires-Dist: uvicorn<1,>=0.30
|
|
44
|
+
Requires-Dist: websockets<18,>=15
|
|
45
|
+
Description-Content-Type: text/markdown
|
|
46
|
+
|
|
47
|
+
# Heraldesk
|
|
48
|
+
|
|
49
|
+
[](https://github.com/abengkris/heraldesk/actions/workflows/ci.yml) [](LICENSE) [](https://github.com/abengkris/heraldesk/releases/tag/v1.16.3)
|
|
50
|
+
|
|
51
|
+
> Your autonomous social media department. Self-hosted, open source, single-user.
|
|
52
|
+
|
|
53
|
+
**Version 1.16.3.** Heraldesk runs four LLM roles (strategist, researcher, writer,
|
|
54
|
+
compliance) plus a deterministic Designer placeholder and manual Community/Analyst
|
|
55
|
+
tooling. They draft, review, queue and schedule social media content for accounts you
|
|
56
|
+
manage. You approve; Heraldesk does the legwork. It runs on your laptop or your own VPS.
|
|
57
|
+
Your keys, your data.
|
|
58
|
+
|
|
59
|
+
Heraldesk is CLI-first and also ships a local Web UI + JSON API since 1.2.0. Threads
|
|
60
|
+
(text) and Nostr are bundled publishers; X/Facebook/Instagram/LinkedIn can be supplied by
|
|
61
|
+
an installed plugin. The fake adapter is the offline publishing path. See
|
|
62
|
+
[Threads publishing](#threads-publishing) and [Nostr publishing](#nostr-publishing).
|
|
63
|
+
|
|
64
|
+
## What works in 1.16.3
|
|
65
|
+
|
|
66
|
+
- Multiple profiles with their own voice, rules and autonomy policy.
|
|
67
|
+
- Draft-first content state machine with lint, Compliance and approval gates.
|
|
68
|
+
- Deterministic `daily_content` pipeline using the fake LLM provider or your own LiteLLM key.
|
|
69
|
+
- CLI approval queue, edits, rejection and manual publishing.
|
|
70
|
+
- Stateless scheduler with durable retries and at-most-once publishing.
|
|
71
|
+
- Profile quiet hours and a local-day post cap gate automatic publishing; explicit publishes override them.
|
|
72
|
+
- Official Threads (text) and Nostr publishers, plus `heraldesk.platforms` adapter plugins.
|
|
73
|
+
- `heraldesk upgrade` takes a credential backup before applying migrations.
|
|
74
|
+
- Docker, Compose, systemd and Caddy deployment examples for a VPS, with SBOM/provenance on release images.
|
|
75
|
+
- Runnable profile and adapter-plugin examples under `examples/`.
|
|
76
|
+
- Telegram notifications, allowlisted commands and a stored inbound inbox.
|
|
77
|
+
- Manual inbox triage: list, show, reply and ignore. No auto-reply and no AI-generated replies.
|
|
78
|
+
- Deterministic weekly and monthly reports, with no LLM calls.
|
|
79
|
+
- Backup and restore, doctor hardening, global and per-profile kill switches.
|
|
80
|
+
- Real Nostr publishing (NIP-01 kind 1 notes) with a throwaway key.
|
|
81
|
+
- Local Web UI and authenticated `/api/v1` for queue (including full-draft detail), calendar, inbox, reports, cost, audit, profiles, run traces, readiness and manual publishing.
|
|
82
|
+
- SQLite only. No Redis, Postgres, Node, telemetry or phone-home.
|
|
83
|
+
|
|
84
|
+
## Requirements
|
|
85
|
+
|
|
86
|
+
- Python 3.12 (`pipx install --python 3.12 ...` if your default interpreter is newer)
|
|
87
|
+
- [`uv`](https://docs.astral.sh/uv/) for the recommended source install
|
|
88
|
+
- A Linux, macOS or Windows machine; the CLI is tested on all three
|
|
89
|
+
|
|
90
|
+
## Install from source
|
|
91
|
+
|
|
92
|
+
The 1.16.3 release is available as a GitHub release wheel and as a repository checkout.
|
|
93
|
+
A tag-triggered workflow builds PyPI and GHCR artifacts; PyPI publishing is enabled after
|
|
94
|
+
the maintainer configures trusted publishing. The exact TestPyPI/PyPI runbook is in
|
|
95
|
+
[docs/releasing.md](docs/releasing.md).
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
# Repository checkout, with the pinned development environment
|
|
99
|
+
git clone https://github.com/abengkris/heraldesk.git
|
|
100
|
+
cd heraldesk
|
|
101
|
+
uv sync
|
|
102
|
+
uv run heraldesk init
|
|
103
|
+
|
|
104
|
+
# Or install the checkout directly into your user environment
|
|
105
|
+
pipx install --python 3.12 .
|
|
106
|
+
# uvx --from . heraldesk init
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
The release wheel is attached to each
|
|
110
|
+
[GitHub release](https://github.com/abengkris/heraldesk/releases); install it with
|
|
111
|
+
`pipx install --python 3.12 ./heraldesk-1.16.3-py3-none-any.whl`.
|
|
112
|
+
|
|
113
|
+
### Docker
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
git clone https://github.com/abengkris/heraldesk.git
|
|
117
|
+
cd heraldesk
|
|
118
|
+
printf 'HERALDESK_ADMIN_TOKEN=%s\n' "$(python -c 'import secrets; print(secrets.token_urlsafe(32))')" > .env
|
|
119
|
+
chmod 600 .env
|
|
120
|
+
docker compose up -d --build
|
|
121
|
+
docker compose exec heraldesk heraldesk init
|
|
122
|
+
docker compose exec heraldesk heraldesk doctor
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Compose binds only `127.0.0.1:8000`; put Caddy or Nginx in front. See
|
|
126
|
+
[deploy/README.md](deploy/README.md) for the VPS runbook, systemd unit and hardening
|
|
127
|
+
checklist.
|
|
128
|
+
|
|
129
|
+
## First run
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
export HERALDESK_HOME="$HOME/.heraldesk" # optional; this is the default
|
|
133
|
+
uv run heraldesk init
|
|
134
|
+
uv run heraldesk doctor
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
`init` creates the data folder, `secret.key` (mode 600), a documented `heraldesk.yaml`
|
|
138
|
+
and the SQLite database. It is safe to run again: it keeps your files and applies pending
|
|
139
|
+
migrations.
|
|
140
|
+
|
|
141
|
+
Put LLM API keys in `$HERALDESK_HOME/.env`, never in `heraldesk.yaml`:
|
|
142
|
+
|
|
143
|
+
```dotenv
|
|
144
|
+
DEEPSEEK_API_KEY=your-key-here
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Then set `llm.default_model` in `heraldesk.yaml`, for example `deepseek/deepseek-chat`,
|
|
148
|
+
or leave it empty to use the offline fake provider for a first run.
|
|
149
|
+
|
|
150
|
+
Create and activate a profile:
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
uv run heraldesk profile new acme --name "Acme" --type company --timezone UTC --languages en
|
|
154
|
+
# edit profiles/acme/soul.md, brief.md, policy.yaml and banned.yaml
|
|
155
|
+
uv run heraldesk profile reload acme
|
|
156
|
+
uv run heraldesk profile resume acme
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Optional account setup with the offline fake adapter:
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
uv run heraldesk account add acme --platform fake --handle @acme -c token=demo
|
|
163
|
+
uv run heraldesk account test acme
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
## Daily workflow
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
# Draft content. --dry-run writes nothing.
|
|
170
|
+
uv run heraldesk run daily acme
|
|
171
|
+
|
|
172
|
+
# Review, approve, reject or edit.
|
|
173
|
+
uv run heraldesk queue list acme
|
|
174
|
+
uv run heraldesk queue show <id> # full draft before deciding
|
|
175
|
+
uv run heraldesk queue approve <id>
|
|
176
|
+
uv run heraldesk queue reject <id> --reason "off voice"
|
|
177
|
+
uv run heraldesk queue edit <id> --body "Replacement text"
|
|
178
|
+
|
|
179
|
+
# Publish one item now, or run the due scheduler sweep.
|
|
180
|
+
uv run heraldesk publish <id>
|
|
181
|
+
uv run heraldesk scheduler run
|
|
182
|
+
|
|
183
|
+
# Run the API, scheduler and Telegram bot in one process.
|
|
184
|
+
uv run heraldesk serve
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
Approvals, publishing and replies obey the global kill switch, the per-profile kill
|
|
188
|
+
switch and the profile status. Automatic publishing is refused inside `quiet_hours` and
|
|
189
|
+
after `max_posts_per_day` has been reached, both in the profile timezone. An explicit
|
|
190
|
+
`heraldesk publish` overrides those two limits and records a `publish.policy_override`
|
|
191
|
+
audit entry. Manual inbox replies are blocked by the kill switches and profile status;
|
|
192
|
+
quiet hours apply to automatic replies only. `heraldesk stop-all` halts everything;
|
|
193
|
+
`heraldesk stop-all --off` clears the global switch. Stop-all does not cancel items that
|
|
194
|
+
are already scheduled; use the queue commands and review scheduled items before clearing it.
|
|
195
|
+
|
|
196
|
+
## Telegram
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
uv run heraldesk telegram test
|
|
200
|
+
uv run heraldesk telegram token set
|
|
201
|
+
uv run heraldesk telegram token status
|
|
202
|
+
uv run heraldesk telegram send acme "manual test"
|
|
203
|
+
uv run heraldesk telegram inbox list acme
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
Bot tokens are encrypted with `secret.key`. Only chat IDs in `telegram.allowed_chat_ids`
|
|
207
|
+
are served. Set `telegram.allowed_user_ids` to restrict which senders may run commands
|
|
208
|
+
(`/approve`, `/reject`, `/queue`).
|
|
209
|
+
|
|
210
|
+
## Nostr publishing
|
|
211
|
+
|
|
212
|
+
Nostr is the first real platform adapter: one NIP-01 **kind 1** text note per approved
|
|
213
|
+
content item, signed locally with BIP-340 Schnorr and broadcast to relays. It needs no
|
|
214
|
+
app review and no username or password.
|
|
215
|
+
|
|
216
|
+
> **Use a throwaway key.** Nostr events are immutable. Once a relay accepts an event it
|
|
217
|
+
> cannot be deleted. Test with a throwaway key, check the event id on a public explorer,
|
|
218
|
+
> then abandon the key.
|
|
219
|
+
>
|
|
220
|
+
> **Never paste an nsec into chat, a GitHub issue, or a screenshot. Type it only in your own terminal via an environment variable.**
|
|
221
|
+
> Keep it in an environment variable or a secure prompt. Heraldesk encrypts it with
|
|
222
|
+
> `secret.key` and never prints it.
|
|
223
|
+
|
|
224
|
+
```bash
|
|
225
|
+
# In your own terminal. The nsec is read from the environment, not the command line.
|
|
226
|
+
export NOSTR_NSEC_THROWAY='<throwaway nsec>'
|
|
227
|
+
uv run heraldesk account add acme --platform nostr \
|
|
228
|
+
--credential-from-env NOSTR_NSEC_THROWAY --label throwaway
|
|
229
|
+
|
|
230
|
+
# The npub is shown masked; the nsec is never shown.
|
|
231
|
+
uv run heraldesk account list acme
|
|
232
|
+
uv run heraldesk account test acme --platform nostr
|
|
233
|
+
|
|
234
|
+
# Draft for real (a dry run writes nothing, so there is nothing to approve).
|
|
235
|
+
uv run heraldesk run daily acme
|
|
236
|
+
uv run heraldesk queue list acme
|
|
237
|
+
uv run heraldesk queue show <id>
|
|
238
|
+
uv run heraldesk queue approve <id>
|
|
239
|
+
uv run heraldesk publish <id>
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
Relays come from `nostr.relays` in `heraldesk.yaml` (defaults: `wss://relay.damus.io`,
|
|
243
|
+
`wss://nos.lol`) or from `--relay` on the account. One relay accepting the event is
|
|
244
|
+
enough; failures use the normal publisher retries. Details and the manual acceptance
|
|
245
|
+
steps are in [docs/platforms/nostr.md](docs/platforms/nostr.md).
|
|
246
|
+
|
|
247
|
+
## Threads publishing
|
|
248
|
+
|
|
249
|
+
The Threads adapter publishes one **text** thread through the official Meta Graph API:
|
|
250
|
+
create a container, wait for it, publish, then read the permalink. It needs a Threads
|
|
251
|
+
user access token and (optionally) the user id.
|
|
252
|
+
|
|
253
|
+
```bash
|
|
254
|
+
# Read the token from the environment; never put it on the command line.
|
|
255
|
+
export THREADS_TOKEN='<long-lived Threads user access token>'
|
|
256
|
+
export THREADS_USER_ID='<threads user id>'
|
|
257
|
+
|
|
258
|
+
uv run heraldesk account add acme --platform threads --handle @acme \
|
|
259
|
+
--credential-from-env THREADS_TOKEN --credential-from-env THREADS_USER_ID
|
|
260
|
+
uv run heraldesk account test acme --platform threads # calls GET /me
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
A long-lived token lasts 60 days. Refresh it with
|
|
264
|
+
`heraldesk account refresh acme --platform threads`; the new token and expiry are encrypted
|
|
265
|
+
and `doctor` warns when expiry is within 7 days. Text is limited to 500 UTF-8 bytes and the platform allows 250 posts per
|
|
266
|
+
rolling 24 hours. CI mocks every HTTP call; the manual acceptance steps and sources are in
|
|
267
|
+
[docs/platforms/threads.md](docs/platforms/threads.md).
|
|
268
|
+
|
|
269
|
+
## Web UI and API
|
|
270
|
+
|
|
271
|
+
M11 adds a server-rendered Web UI and a JSON API for daily operation without the terminal.
|
|
272
|
+
The CLI remains fully supported. One process still serves everything.
|
|
273
|
+
|
|
274
|
+
```bash
|
|
275
|
+
# Set the single admin token in $HERALDESK_HOME/.env, or use the one derived from secret.key.
|
|
276
|
+
# HERALDESK_ADMIN_TOKEN=change-me-to-a-long-random-token
|
|
277
|
+
|
|
278
|
+
uv run heraldesk admin token # source + fingerprint only
|
|
279
|
+
uv run heraldesk serve # http://127.0.0.1:8000
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
Open `http://127.0.0.1:8000/login` and enter the token. The UI has a dashboard, approval
|
|
283
|
+
queue with full-draft detail, edit/publish controls, content calendar, inbox triage, report
|
|
284
|
+
viewer, LLM cost page, audit log, profile list, global kill-switch control and a validated
|
|
285
|
+
profile/policy editor. HTMX and CSS are vendored;
|
|
286
|
+
there is no Node build and no external CDN.
|
|
287
|
+
|
|
288
|
+
The API uses `Authorization: Bearer <token>` only. `GET /api/v1/queue/{approval_id}`
|
|
289
|
+
returns the full redacted draft so scripts can inspect content before deciding:
|
|
290
|
+
|
|
291
|
+
```bash
|
|
292
|
+
curl -H "Authorization: Bearer $HERALDESK_ADMIN_TOKEN" \
|
|
293
|
+
http://127.0.0.1:8000/api/v1/status
|
|
294
|
+
|
|
295
|
+
curl -H "Authorization: Bearer $HERALDESK_ADMIN_TOKEN" \
|
|
296
|
+
http://127.0.0.1:8000/api/v1/queue?status=pending
|
|
297
|
+
|
|
298
|
+
curl -H "Authorization: Bearer $HERALDESK_ADMIN_TOKEN" \
|
|
299
|
+
http://127.0.0.1:8000/api/v1/audit?limit=20
|
|
300
|
+
|
|
301
|
+
curl -H "Authorization: Bearer $HERALDESK_ADMIN_TOKEN" \
|
|
302
|
+
http://127.0.0.1:8000/api/v1/cost
|
|
303
|
+
|
|
304
|
+
curl -H "Authorization: Bearer $HERALDESK_ADMIN_TOKEN" \
|
|
305
|
+
http://127.0.0.1:8000/api/v1/profiles
|
|
306
|
+
|
|
307
|
+
curl -H "Authorization: Bearer $HERALDESK_ADMIN_TOKEN" \
|
|
308
|
+
"http://127.0.0.1:8000/api/v1/runs?profile=acme"
|
|
309
|
+
|
|
310
|
+
curl -H "Authorization: Bearer $HERALDESK_ADMIN_TOKEN" \
|
|
311
|
+
"http://127.0.0.1:8000/api/v1/accounts?profile=acme"
|
|
312
|
+
|
|
313
|
+
# Pagination and filters
|
|
314
|
+
curl -H "Authorization: Bearer $HERALDESK_ADMIN_TOKEN" \
|
|
315
|
+
"http://127.0.0.1:8000/api/v1/queue?status=pending&profile=acme&limit=20&offset=0"
|
|
316
|
+
curl -H "Authorization: Bearer $HERALDESK_ADMIN_TOKEN" \
|
|
317
|
+
"http://127.0.0.1:8000/api/v1/audit?action=auth.login&limit=50&offset=0"
|
|
318
|
+
|
|
319
|
+
# Authenticated machine-readable contract
|
|
320
|
+
curl -H "Authorization: Bearer $HERALDESK_ADMIN_TOKEN" \
|
|
321
|
+
http://127.0.0.1:8000/api/v1/openapi.json
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
`/health` is public liveness/schema readiness and returns 503 when the database is behind the packaged migration. `/api/v1`, `/status` and every UI page require auth. API Bearer failures are limited to 10 per minute per client and return `429` with `Retry-After`.
|
|
325
|
+
Tokens in a URL query string are rejected. Login is rate limited to five failed attempts
|
|
326
|
+
per minute per IP.
|
|
327
|
+
|
|
328
|
+
Server logs rotate in `$HERALDESK_HOME/logs/heraldesk.log` (5 MiB × 3, mode 600) with
|
|
329
|
+
secret redaction. `GET /api/v1/ready` reports schema, scheduler and Telegram readiness.
|
|
330
|
+
|
|
331
|
+
`heraldesk admin rotate-key` creates a credential backup, re-encrypts every account and the persisted Telegram token, revokes sessions, swaps `secret.key` and verifies the result. It reads the token file directly, so an environment or `.env` override is never copied over the persisted token. Session revocation failure aborts before credentials change. Stop `heraldesk serve` first. `heraldesk admin logout-all` rotates the session epoch and invalidates every signed-in browser; the dashboard has the same action. `heraldesk admin token --show` prints the raw token for your own terminal. Never put it in
|
|
332
|
+
chat, a GitHub issue, a screenshot or a shell history you do not control.
|
|
333
|
+
|
|
334
|
+
### VPS hardening (Caddy + HTTPS)
|
|
335
|
+
|
|
336
|
+
The recommended deployment keeps Heraldesk on loopback and puts a TLS reverse proxy in
|
|
337
|
+
front of it:
|
|
338
|
+
|
|
339
|
+
```bash
|
|
340
|
+
# $HERALDESK_HOME/.env
|
|
341
|
+
HERALDESK_ADMIN_TOKEN=<long-random-secret>
|
|
342
|
+
HERALDESK_TRUST_PROXY=1
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
```caddyfile
|
|
346
|
+
desk.example.com {
|
|
347
|
+
reverse_proxy 127.0.0.1:8000
|
|
348
|
+
}
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
Then run `uv run heraldesk serve` without `--host`. Proxy mode makes the session cookie
|
|
352
|
+
`Secure`; the admin token is still required.
|
|
353
|
+
|
|
354
|
+
A non-loopback bind is refused unless all three conditions hold: `--allow-remote`, an
|
|
355
|
+
explicit `HERALDESK_ADMIN_TOKEN`, and `HERALDESK_TRUST_PROXY=1` behind an HTTPS proxy.
|
|
356
|
+
Without proxy mode the server refuses with "Remote mode requires HTTPS via reverse proxy".
|
|
357
|
+
|
|
358
|
+
The default serve port is `8000`; if you change it, use the same value in the reverse
|
|
359
|
+
proxy. **Do not expose the Heraldesk port directly to the internet.** Firewall it and let
|
|
360
|
+
only the reverse proxy reach it. Set `HERALDESK_TELEGRAM_WEBHOOK_SECRET` whenever
|
|
361
|
+
Telegram is enabled on a remote or webhook-mode server; the server refuses to start
|
|
362
|
+
without it so forged `/approve` commands cannot approve content.
|
|
363
|
+
|
|
364
|
+
## Inbox triage
|
|
365
|
+
|
|
366
|
+
The inbox is manual by design. A human reads each stored message and either replies or
|
|
367
|
+
ignores it. There is no auto-reply, sentiment moderation or AI-generated reply.
|
|
368
|
+
|
|
369
|
+
```bash
|
|
370
|
+
uv run heraldesk inbox list
|
|
371
|
+
uv run heraldesk inbox list --status handled --limit 50
|
|
372
|
+
uv run heraldesk inbox show <id>
|
|
373
|
+
uv run heraldesk inbox reply <id> --text "Thanks for the question."
|
|
374
|
+
uv run heraldesk inbox ignore <id> --reason spam
|
|
375
|
+
|
|
376
|
+
# Delete handled/ignored messages older than 30 days (pending is kept).
|
|
377
|
+
# Set telegram.retention_days in heraldesk.yaml for a daily 03:15 UTC job.
|
|
378
|
+
uv run heraldesk inbox prune --days 30
|
|
379
|
+
uv run heraldesk inbox prune --days 30 --dry-run
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
Replies use the configured Telegram adapter and require `telegram.enabled` plus a bot
|
|
383
|
+
token. Tests use the fake adapter. Reply text is redacted before it is sent, stored or
|
|
384
|
+
written to the audit log.
|
|
385
|
+
|
|
386
|
+
## Reports
|
|
387
|
+
|
|
388
|
+
```bash
|
|
389
|
+
uv run heraldesk report weekly
|
|
390
|
+
uv run heraldesk report weekly --week 2026-W47
|
|
391
|
+
uv run heraldesk report monthly
|
|
392
|
+
uv run heraldesk report monthly --month 2026-11
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
Reports are deterministic Markdown files in `$HERALDESK_HOME/reports/`. They contain
|
|
396
|
+
period totals, approval rate, cost, inbox counts, publish failures and the top published
|
|
397
|
+
posts. The same database state produces the same file. A period with no data still
|
|
398
|
+
produces a report with zeros.
|
|
399
|
+
|
|
400
|
+
## Backup and restore
|
|
401
|
+
|
|
402
|
+
Backups are private ZIP archives. By default they contain:
|
|
403
|
+
|
|
404
|
+
```text
|
|
405
|
+
manifest.json
|
|
406
|
+
heraldesk.db # consistent SQLite online-backup snapshot
|
|
407
|
+
heraldesk.yaml
|
|
408
|
+
profiles/**
|
|
409
|
+
agents/** # user prompt overrides
|
|
410
|
+
```
|
|
411
|
+
|
|
412
|
+
They never contain `.env`, logs, generated reports or previous backups. `secret.key` and
|
|
413
|
+
the encrypted `telegram.token` are included only when you ask for credentials:
|
|
414
|
+
|
|
415
|
+
```bash
|
|
416
|
+
# Private archive in $HERALDESK_HOME/backups/
|
|
417
|
+
uv run heraldesk backup
|
|
418
|
+
|
|
419
|
+
# Credential backup needed for a full database restore
|
|
420
|
+
uv run heraldesk backup --with-credentials --output /secure/heraldesk.zip
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
`heraldesk backup-prune --keep 10` deletes older `heraldesk-backup-*.zip` archives;
|
|
424
|
+
`--dry-run` lists them first. Restore refuses while `heraldesk serve` holds `server.lock`.
|
|
425
|
+
|
|
426
|
+
Restore semantics are intentionally strict:
|
|
427
|
+
|
|
428
|
+
- A backup with `secret.key` can restore the database, config, profiles, agents and key.
|
|
429
|
+
- A backup without `secret.key` cannot decrypt social credentials. Restore fails with the
|
|
430
|
+
documented message unless you pass `--without-credentials`.
|
|
431
|
+
- `--without-credentials` restores **config, profiles and agents only**. It does **not**
|
|
432
|
+
restore `heraldesk.db` and does **not** restore `secret.key`. Run `heraldesk init`
|
|
433
|
+
afterwards to create a new database and reload the profiles.
|
|
434
|
+
- `--force` replaces existing data in the target folder. Before replacing anything it
|
|
435
|
+
writes a credential safety backup into `backups/`. Without `--force`, restore refuses
|
|
436
|
+
to overwrite an initialised instance.
|
|
437
|
+
- Restoring a database applies pending Alembic migrations before the server starts and
|
|
438
|
+
rotates the session epoch, invalidating old browser cookies.
|
|
439
|
+
|
|
440
|
+
```bash
|
|
441
|
+
# Full restore from a credential backup
|
|
442
|
+
uv run heraldesk restore /secure/heraldesk.zip --force
|
|
443
|
+
|
|
444
|
+
# Files-only restore into a fresh instance
|
|
445
|
+
uv run heraldesk restore /secure/heraldesk-no-key.zip --without-credentials
|
|
446
|
+
uv run heraldesk init
|
|
447
|
+
uv run heraldesk profile reload
|
|
448
|
+
```
|
|
449
|
+
|
|
450
|
+
Upgrade procedure: install the new version, then run `heraldesk upgrade`. It creates a
|
|
451
|
+
credential backup first, applies Alembic migrations and audits the change. Run
|
|
452
|
+
`heraldesk doctor` afterwards. `heraldesk serve` refuses to start on a stale schema.
|
|
453
|
+
|
|
454
|
+
See [deploy/README.md](deploy/README.md) for Docker, systemd, Caddy and the VPS hardening
|
|
455
|
+
checklist.
|
|
456
|
+
|
|
457
|
+
## Doctor
|
|
458
|
+
|
|
459
|
+
`heraldesk doctor` is offline by default. It checks:
|
|
460
|
+
|
|
461
|
+
- Python version and the data folder being writable;
|
|
462
|
+
- required folders and `secret.key` permissions;
|
|
463
|
+
- SQLite WAL mode and the Alembic revision;
|
|
464
|
+
- whether the database migration is up to date;
|
|
465
|
+
- `heraldesk.yaml` validity and the `.env` permissions if present;
|
|
466
|
+
- a resolvable Telegram token whenever `telegram.enabled` is true;
|
|
467
|
+
- the reports directory, or that it can be created;
|
|
468
|
+
- loopback-only server binding.
|
|
469
|
+
|
|
470
|
+
Only FAIL changes the exit code to 1. `--online` adds three explicit network probes:
|
|
471
|
+
|
|
472
|
+
- the LLM provider, using one minimal completion when a real LiteLLM model is configured
|
|
473
|
+
(the fake provider makes no call);
|
|
474
|
+
- the Telegram Bot API's `getMe`, when `telegram.enabled` is true and a token is present;
|
|
475
|
+
- one Nostr relay WebSocket handshake, only when at least one Nostr account exists. An
|
|
476
|
+
unreachable relay is a WARN, not a failure.
|
|
477
|
+
|
|
478
|
+
Online probes never print an API key, bot token or nsec.
|
|
479
|
+
|
|
480
|
+
## Security notes
|
|
481
|
+
|
|
482
|
+
- `heraldesk.yaml` contains no credentials. LLM keys live in `.env` or the environment.
|
|
483
|
+
- Social account credentials are encrypted at rest with `secret.key` (mode 600).
|
|
484
|
+
- Rotate it with `heraldesk admin rotate-key`; a credential backup is mandatory and the old key remains the restore source if the swap is interrupted.
|
|
485
|
+
- Backups exclude `.env`; they include `telegram.token` with `--with-credentials`.
|
|
486
|
+
Protect credential backups like the original data folder.
|
|
487
|
+
- The server binds to `127.0.0.1` by default. A non-loopback bind requires
|
|
488
|
+
`--allow-remote`, an explicit `HERALDESK_ADMIN_TOKEN` of at least 32 characters and
|
|
489
|
+
`HERALDESK_TRUST_PROXY=1` behind an HTTPS reverse proxy.
|
|
490
|
+
- Audit payloads, reports and CLI output redact credential-shaped values. Full inbox and
|
|
491
|
+
content text is never written to the audit log.
|
|
492
|
+
- No telemetry and no phone-home. Outbound traffic is limited to your configured LLM
|
|
493
|
+
provider, platform APIs, Telegram and Researcher web search.
|
|
494
|
+
- Heraldesk is for accounts you own or are authorized to manage. No fake-account networks,
|
|
495
|
+
impersonation, spam or platform-rule evasion. You are responsible for platform terms and
|
|
496
|
+
local law.
|
|
497
|
+
|
|
498
|
+
## Documentation
|
|
499
|
+
|
|
500
|
+
- [Architecture](docs/architecture.md)
|
|
501
|
+
- [Decisions and milestone notes](docs/decisions.md)
|
|
502
|
+
- [Roadmap](ROADMAP.md)
|
|
503
|
+
- [Releasing](docs/releasing.md)
|
|
504
|
+
- [Contributing](CONTRIBUTING.md)
|
|
505
|
+
- [Security policy](SECURITY.md)
|
|
506
|
+
- [Deployment](deploy/README.md)
|
|
507
|
+
- [Changelog](CHANGELOG.md)
|
|
508
|
+
- Bahasa Indonesia: [docs/id/arsitektur.md](docs/id/arsitektur.md)
|
|
509
|
+
|
|
510
|
+
## License
|
|
511
|
+
|
|
512
|
+
MIT. See [LICENSE](LICENSE).
|