Configuration

Argus reads one strict YAML file. Unknown fields and version: 1 are rejected; v2 deliberately starts from a fresh database. Put secrets in /opt/argus/secrets.env and reference them as a complete ${NAME} value.

argus config validate /opt/argus/argus.yaml
argus config show /opt/argus/argus.yaml
argus config apply /opt/argus/argus.yaml --dry-run
argus config apply /opt/argus/argus.yaml --yes
argus config schema --json

Complete v2 examples

Single VPS with SQLite

version: 2
runtime: { role: all }
storage:
  adapter: sqlite
  url: /app/data/argus.db
sources:
  x:
    enabled: true
    endpoint: http://fxembed:8787
    replies:
      enabled: true
      maxPerPost: 50
      maxTrackingHours: 168
      orderBy: likes
  telegram: { enabled: true, adapter: public-web }
  web:
    enabled: true
    searchEndpoint: http://searxng:8080
    searchEndpointTrust: trusted
    userAgent: Argus/0.1
watches:
  - id: screen-news
    enabled: true
    schedule: "*/10 * * * *"
    inputs:
      x:
        accounts: [DiscussingFilm, FilmUpdates]
        queries: ["new movies and TV shows"]
      telegram: { channels: [mcunewsandrumors] }
      web:
        urls: [https://deadline.com/v/tv/]
        feeds: [https://deadline.com/feed/]
        queries: ["new movies and TV shows news"]
    classify:
      keywords: [movie, film, tv, series, trailer, streaming]
api:
  host: 0.0.0.0
  port: 8788
  token: ${ARGUS_API_TOKEN}

Storage

storage.adapter is sqlite or postgres.

• SQLite is the one-command VPS default and requires runtime.role: all.
• PostgreSQL accepts a canonical postgres:// or postgresql:// URL and can support separate api, scheduler, worker, and processor processes.
• A v1 or unversioned database is refused before mutation. Argus does not run a compatibility migration; start v2 with an empty database.

Both adapters implement the same record, revision, media, relation, engagement, conversation, job, checkpoint, artifact, and configuration contracts.

X reply tracking

sources.x.endpoint is the selected FxEmbed origin; VPS onboarding writes http://fxembed:8787. Reply tracking is opt-in in hand-written YAML. The onboarding wizard recommends the Standard profile.

maxPerPost defaults to 50 and is bounded from 1 to 200. Argus retains the top configured number from the replies it actually observed; it never claims the sample is every reply on X. orderBy accepts likes, newest, oldest, replies, reposts, views, or source. Growth temporarily increases refresh frequency. Tracking stops at the configured time horizon even if the retained sample has not reached 50.

Telegram and Web

Telegram v2 supports public announcement channels through adapter: public-web. No bot token, private chat, member-only group, or generic discussion ingestion is implemented.

Direct Web URLs and feeds use the bounded public-Web fetch path. Search queries require searchEndpoint, normally managed SearXNG. External endpoints use searchEndpointTrust: public; only an operator-controlled private service uses trusted.

Watches

A watch needs a lowercase id, a five-field cron schedule, and inputs. Inputs may contain X accounts and queries, Telegram channels, and Web urls, feeds, and queries. classify.keywords adds matching metadata; it does not discard unmatched records.

Intelligence

Intelligence is optional and OpenRouter-only. Scheduled processors create sourced summary artifacts. argus query creates a sourced answer artifact on demand. Supported public image, video, and PDF pointers may be passed directly to a compatible model; Argus never downloads or base64-encodes media.

API and secrets

api.token protects every /v1/* endpoint. The runtime refuses a non-loopback bind without it. The managed Compose topology publishes the selected port, so also use a firewall, private network, or reverse proxy policy.

Use argus secrets set ARGUS_API_TOKEN and argus secrets set OPENROUTER_API_KEY; never place their values in YAML or a shell argument.

PostgreSQL service roles

version: 2
runtime: { role: all }
storage:
  adapter: postgres
  url: postgresql://postgres:5432/argus?sslmode=disable
sources: {}
watches: []
intelligence:
  enabled: true
  provider: openrouter
  apiKey: ${OPENROUTER_API_KEY}
  model: openai/gpt-4.1-mini
  processors: []
api:
  host: 0.0.0.0
  port: 8788
  token: ${ARGUS_API_TOKEN}

Minimal Web-only instance

version: 2
runtime: { role: all }
storage: { adapter: sqlite, url: /app/data/argus.db }
sources:
  web: { enabled: true }
watches:
  - id: public-site
    schedule: "*/15 * * * *"
    inputs:
      web: { urls: [https://example.com/news] }
api:
  host: 0.0.0.0
  port: 8788
  token: ${ARGUS_API_TOKEN}

Consumers and evidence retention

consumers defaults to an empty list. Each consumer has a unique id and its own credential (a literal token or ${ARGUS_CONSUMER_TOKEN} secret reference). A consumer without a credential cannot authenticate. Configuring any consumers requires an operator api.token, including on loopback. Consumer credentials must be distinct from one another and from the operator's api.token.

Per-consumer quotas default to maxWatches: 100, maxJobsPerHour: 60, maxConcurrentJobs: 4, and maxUpstreamRequestsPerHour: 60. minimumRefreshSeconds defaults to 60. Zero quota disables that capacity. An owned watch sets ownerId to its consumer's ID; other consumers cannot mutate it.

retention.recordsDays and retention.revisionsDays each default to 90; retention.eventsDays defaults to 30. All retention periods are positive integers.

argus config export exports the service's applied configuration, including agent-created watches, with credentials removed. Restore secret references before applying an exported configuration. argus config show displays the local file. Configuration apply previews removed watch IDs and owners. The preview's plan ID and base hash bind approval to the current applied configuration; changes after preview invalidate the plan and require a new preview. Cancelling a watch preserves its collected evidence.