Architecture

What's stored

Every hosted-mode deployment (including the shared Sahir Venn instance) keeps one file, data/acp.db. It's deliberately narrow — no Discord message content, no copy of anyone's game database, no Docker access, no Steam credentials — and it got narrower still in a recent hardening pass: four things left, down from ten.

Why a Discord Application is required at all

This isn't a design choice we made — it's a Discord platform requirement, and it applies to every Discord bot that has ever existed, including the big ones. Four things are all tied to it:

1. The persistent Gateway connection. Receiving slash commands in real time needs a long-lived connection authenticated with a bot token — and a bot token only exists because an Application minted it.
2. Slash-command registration. /dune ... and its autocomplete are registered against an Application ID.
3. "Add to Server." The invite link is a literal OAuth2 request against one Application's client ID.
4. "Sign in with Discord" on the setup portal. Confirming you actually administer your server before letting you configure it is its own OAuth2 exchange.

So the real question was never "does this need an Application" — it's who owns it: one we run and every server shares, or one you register and own yourself. Both run the exact same code.

Hosted or self-hosted — two real choices

Both are the exact same open-source code. The only difference is whose name is on the Discord Application, and where your adapter token lives.

If you already run your own Discord integration against your console's adapter API, self-hosting Sahir Venn is a drop-in swap — same trust footprint you already have today, more capability. See the self-hosted install guide to get started either way.

End-to-end: "Add to Discord" → /dune server status

Two views of the same system: the components and trust boundaries, then the literal sequence of calls. Both describe the hosted path — self-hosting is the identical diagram narrowed to one server and one Application.

System components

flowchart LR
    subgraph DC["Discord Platform"]
        GW["Gateway
(persistent connection)"]
        OAUTH["OAuth2
(Add to Server / Sign in)"]
        INT["Interactions
(/dune commands)"]
    end

    subgraph BOT["Sahir Venn (Bot Process)"]
        CLIENT["Discord client"]
        SETUP["Setup portal
/setup, /oauth/callback"]
        DB[("SQLite
guilds, guild_roles,
guild_settings")]
        ADAPTERCLIENT["Adapter client"]
    end

    CORE["Your Core Console
Discord adapter API"]

    GW <-->|persistent connection| CLIENT
    OAUTH -->|redirects| SETUP
    INT -->|command payload| CLIENT
    SETUP <-->|reads/writes| DB
    CLIENT --> ADAPTERCLIENT
    ADAPTERCLIENT -->|look up console URL + token| DB
    ADAPTERCLIENT -->|"Bearer adapter token"| CORE
    CORE -->|JSON status/readiness/etc.| ADAPTERCLIENT

Request sequence

sequenceDiagram
    actor You as You
    participant D as Discord
    participant B as Sahir Venn
    participant C as Your Core Console

    You->>D: Click "Add to Discord"
    D->>You: Consent screen — pick a server, review permissions
    You->>D: Approve
    D->>B: Bot joins your server
    B->>You: DM with a link to the setup portal

    Note over You,C: On your own console, separately:
enable the adapter, generate a token file, restart the container

    You->>B: Open the setup link
    B->>D: Sign in with Discord (confirms you administer this server)
    D->>B: Confirmed
    B->>You: Configuration form
    You->>B: Console URL, adapter token, role mapping
    B->>B: Stores your config (adapter token encrypted at rest)
    B->>You: Setup complete

    Note over You,C: --- later, in any channel ---

    You->>D: /dune server status
    D->>B: Command received
    B->>B: Check your role against the configured mapping
    B->>C: Request status (Bearer adapter token)
    C->>B: JSON status
    B->>D: Formatted reply
    D->>You: Response appears in the channel

Everything after "look up console URL + token" happens over a direct connection from wherever the bot runs to wherever your console is reachable — our infrastructure is never in that specific hop, hosted or self-hosted.

FAQ