[{"data":1,"prerenderedAt":48},["ShallowReactive",2],{"doc:en:plugins\u002Finstaller":3},{"title":4,"lede":5,"html":6,"headings":7},"Installing a plugin","A plugin adds a theme, a harness, a Kanban source, a webhook or tools to Escouade. This page tells how to install one, switch it on project by project, take a permission back, read its journal, update it and uninstall it.","\u003Ch2 id=\"the-view-plugins\">The view Plugins\u003C\u002Fh2>\n\u003Cp>The puzzle-piece icon of the projects’ rail, under the statistics, opens the view Plugins full screen; a second click goes back to the project. Settings › Plugins leads to the same place.\u003C\u002Fp>\n\u003Cp>Its sidebar:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>Store\u003C\u002Fstrong>: the catalog of store.escouade.dev, kept on your machine and searched there (see below).\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Installed\u003C\u002Fstrong>: every plugin, in two groups, “Added” and “Shipped with Escouade”. A line per plugin: its version, “Not verified” or “In development”, the update found, where it comes from, the projects where it is on (a pill per project, a lock for a private project) and its switch for the whole app.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Updates\u003C\u002Fstrong>: the newer versions found, their count in amber.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>In development\u003C\u002Fstrong>: the folders loaded in place.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>The categories\u003C\u002Fstrong>: Harnesses, Kanban sources, Code hosts, Themes, Notifications, Permissions, Tools, Languages, drawn from what each plugin adds.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch2 id=\"installing\">Installing\u003C\u002Fh2>\n\u003Cp>Two buttons at the top of the view:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>From a folder…\u003C\u002Fstrong>: the plugin’s folder, the one of its \u003Ccode class=\"key\">escouade-plugin.json\u003C\u002Fcode>. Escouade copies it into its data (\u003Ccode>~\u002F.escouade\u002Fplugins\u002F<id>\u003C\u002Fcode>), without its git history, and pins it by the SHA-256 fingerprint of its files: a copy changed afterwards loads disabled, and says so.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>From a git repository…\u003C\u002Fstrong>: the repository’s address and a tag (\u003Ccode class=\"key\">v1.2.0\u003C\u002Fcode>). Escouade clones it at that tag alone and pins it by its commit.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>Nothing is installed at once: the plugin is read, set aside, and the install window opens.\u003C\u002Fp>\n\u003Ch2 id=\"from-the-store\">From the store\u003C\u002Fh2>\n\u003Cp>\u003Cstrong>Store\u003C\u002Fstrong>, in the sidebar, shows the catalog of \u003Ca href=\"https:\u002F\u002Fstore.escouade.dev\" rel=\"noopener\">store.escouade.dev\u003C\u002Fa>. Escouade reads it at the start then every 6 hours and keeps it on your machine: the header says when (“catalog read at 10:42”) and, when the store does not answer, shows the catalog kept and says so.\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>The search\u003C\u002Fstrong> runs on your machine, nothing sent: the name, the description, the keywords, the author and the id, case and accents ignored. \u003Cstrong>Verified only\u003C\u002Fstrong> keeps the plugins with the “Verified by Escouade” seal; the chips and the sidebar filter by category.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>For <project>\u003C\u002Fstrong>, at the top: up to three plugins Escouade suggests from what it sees on this machine and in the open project, each with its reason (“vibe is installed on this machine”, “DEM-… keys in this repository’s commits”). Nothing of it is sent. “Not now” puts a suggestion away for a week, “Don’t suggest again” for good.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Each line\u003C\u002Fstrong> says the seal of the version offered or “Not verified”, the author, the installs and what the plugin asks for in one line (“Runs a program”, the hosts, “A secret”, or “No program”).\u003C\u002Fli>\n\u003Cli>\u003Cstrong>A store plugin’s page\u003C\u002Fstrong>: its description, its permissions, its versions (each verified or not, taken back by its author), the review’s summary, where it comes from, and “Report on the store”.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>Escouade offers \u003Cstrong>the last version it can run\u003C\u002Fstrong>: a version written for a newer Escouade is skipped, and so is one its author took back.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>Install\u003C\u002Fstrong> downloads the version, then checks everything before the install window opens: \u003Ccode class=\"key\">version.json\u003C\u002Fcode> against the catalog’s fingerprint, the signature against the public keys Escouade embeds (the store cannot make a seal: it does not have the key), the archive and its module against \u003Ccode class=\"key\">version.json\u003C\u002Fcode>, the manifest against its fingerprint. A gap stops everything and says so (“The archive received is not the one the store published”): nothing is installed. The catalog, the archives and the revocation list go through \u003Cstrong>Settings › Network\u003C\u002Fstrong> (proxy, the system’s certificates).\u003C\u002Fp>\n\u003Cp>The install window then says “Verified by Escouade” and “Signature: checked here, by the app”; for an unverified version, a band: “Nobody has reviewed this version. It comes from the store, its archive is the one its author published, but nothing says what its program does”, and the button “Install anyway”.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>Install verified versions only\u003C\u002Fstrong>, at the top of the installed ones (off by default), refuses any version of the store without a seal, at an install as at an update.\u003C\u002Fp>\n\u003Cp>A plugin installed from a folder or a git repository whose id is on the store says so on its page, with “Move to the store’s v…”: the same window, your choices kept.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>Open in Escouade\u003C\u002Fstrong>, on a plugin’s page of store.escouade.dev, is a link \u003Ccode>escouade:\u002F\u002Fplugin\u002F<id>\u003C\u002Fcode>: it starts Escouade, or brings it to the front if it is open, on the plugin’s page in the view Plugins (its installed page if it already is). \u003Cstrong>A link never installs anything\u003C\u002Fstrong>: installing stays your gesture, from the page, in the window that shows its permissions. A link Escouade cannot read is said (“Escouade can’t read this link, nothing was done”), and so is a plugin the catalog does not have, and nothing else happens. The installer registers the link with the system (Windows, macOS, the \u003Ccode class=\"key\">.deb\u003C\u002Fcode> on Linux); an AppImage registers it itself when it starts.\u003C\u002Fp>\n\u003Cdiv class=\"callout note\">\u003Cp class=\"callout-title\">Note\u003C\u002Fp>\u003Cp>If you accepted the usage statistics, an install from the store is counted on the store (\u003Ccode>POST \u002Fapi\u002Fv1\u002Finstalls\u003C\u002Fcode>: the id, the version, “install” or “update”, nothing else) and in Escouade’s statistics (“plugin installed from the store”, without its name). Without your consent, nothing is sent.\u003C\u002Fp>\n\u003C\u002Fdiv>\n\u003Ch2 id=\"the-install-window\">The install window\u003C\u002Fh2>\n\u003Cp>It tells, before anything is installed:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>who made it\u003C\u002Fstrong>: its name, its author, its version, its license and its id;\u003C\u002Fli>\n\u003Cli>\u003Cstrong>where it comes from\u003C\u002Fstrong>: the folder, or the repository and the tag; its version and its commit; its fingerprint; its signature, “None” outside the store. A plugin from outside the store is \u003Cstrong>not verified\u003C\u002Fstrong>: nobody has reviewed it, and the window says so first;\u003C\u002Fli>\n\u003Cli>\u003Cstrong>what it adds\u003C\u002Fstrong>: its themes, its harnesses, its webhooks, its settings…, and where to find them;\u003C\u002Fli>\n\u003Cli>\u003Cstrong>what it will be able to do\u003C\u002Fstrong>, permission by permission, the strongest first:\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cdiv class=\"table\">\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Permission\u003C\u002Fth>\n\u003Cth>What the window says\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>\u003Ccode class=\"key\">run.command\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>“Runs a program on your computer, with your rights”, in bold\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode class=\"key\">run.js\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>“Runs inside Escouade, isolated”: a program in WASM, with no access to the disk outside its folder\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode class=\"key\">permissions.decide\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>“Decides your agents’ permissions”, in red\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode class=\"key\">permissions.commands\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>“Runs commands”, and which\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode class=\"key\">permissions.events\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>“Gets these events”, and which\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode class=\"key\">permissions.network\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>“Connects to”, and the host: enforced for a \u003Ccode class=\"key\">run.js\u003C\u002Fcode> program and for webhooks, which Escouade only sends to those hosts; only declared for a \u003Ccode class=\"key\">run.command\u003C\u002Fcode> program, whose network Escouade does not filter\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode class=\"key\">permissions.secrets\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>“Keeps a secret:”, and its name\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Cp>“Install anyway” installs the plugin; “Cancel” erases what was set aside. A manifest that does not hold opens no window: the reason shows at the top of the view, field by field (see \u003Ca href=\"\u002Fen\u002Fdocs\u002Fplugins\u002Fmanifest\u002F\">the manifest\u003C\u002Fa>).\u003C\u002Fp>\n\u003Ch2 id=\"the-plugins-shipped-with-escouade\">The plugins shipped with Escouade\u003C\u002Fh2>\n\u003Cp>Some of Escouade’s integrations are plugins, shipped with the app, signed and updated with it: the Plugins view lists them under “Shipped with Escouade”, with the same page as the others (what they add, their permissions, their journal). They are on everywhere from the start, private projects included, as when they were part of the app.\u003C\u002Fp>\n\u003Cdiv class=\"table\">\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Plugin\u003C\u002Fth>\n\u003Cth>What it serves\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>GitHub\u003C\u002Ftd>\n\u003Ctd>The GitHub code host (PRs, CI, reviews, deployments) and the GitHub Issues source, on one account. See \u003Ca href=\"\u002Fen\u002Fdocs\u002Fintegrations\u002F\">integrations\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>GitLab\u003C\u002Ftd>\n\u003Ctd>The GitLab code host, gitlab.com and your instances (merge requests, pipelines, discussions, deployments). GitLab Issues is still part of the app, on the same account.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Bitbucket\u003C\u002Ftd>\n\u003Ctd>The Bitbucket Cloud code host.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Gitea \u002F Forgejo\u003C\u002Ftd>\n\u003Ctd>The code host of Gitea, Forgejo and Codeberg.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Trello\u003C\u002Ftd>\n\u003Ctd>The Trello source of the board.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>ACP\u003C\u002Ftd>\n\u003Ctd>The \u003Ca href=\"\u002Fen\u002Fdocs\u002Fplugins\u002Fharnesses\u002F\">ACP harnesses described\u003C\u002Fa> by a plugin, like Goose.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>isola\u003C\u002Ftd>\n\u003Ctd>The isola launch environment, for \u003Ca href=\"\u002Fen\u002Fdocs\u002Ftesting\u002F\">test launches\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>OpenAI, Groq, Mistral, ElevenLabs, Deepgram\u003C\u002Ftd>\n\u003Ctd>The online voice services (see \u003Ca href=\"\u002Fen\u002Fdocs\u002Fsettings-voice\u002F\">Settings › Voice\u003C\u002Fa>).\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Cul>\n\u003Cli>\u003Cstrong>Switching them off\u003C\u002Fstrong>: their switch, for the whole app, or their Projects tab, for one project. Nothing they did is lost, and your choices are kept for when you switch them back on.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>What shows\u003C\u002Fstrong>: a code host switched off or stopped no longer follows the PRs, and the agent’s card and Settings › Integrations say so; a source switched off stops its sync, which says why; a voice service switched off leaves Settings › Voice, and dictation goes back to local; the agents of an ACP harness stay, marked “Harness missing”.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>No uninstall\u003C\u002Fstrong>, and no update of their own: they change with the app. A plugin by another author cannot take their id (\u003Ccode class=\"key\">dev.escouade.*\u003C\u002Fcode> is reserved); it can serve the same service beside them, and the account says which one serves it.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch2 id=\"switching-on-for-the-app-or-by-project\">Switching on for the app or by project\u003C\u002Fh2>\n\u003Cul>\n\u003Cli>\u003Cstrong>For the whole app\u003C\u002Fstrong>: the switch of its line, or “Switch off” on its page. Switched off, nothing of it runs and no project gets it; its process is stopped.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>By project\u003C\u002Fstrong>: the Projects tab of its page, a line per open project. An installed plugin is on in every project, \u003Cstrong>but the private projects\u003C\u002Fstrong>: a private project is off by default, and the line says so (“nothing reaches it”). Switching it on there is a choice made one by one; the line then reminds that Escouade cannot keep a program from reading the disk.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cdiv class=\"callout note\">\u003Cp class=\"callout-title\">Note\u003C\u002Fp>\u003Cp>A project that recommends a plugin in its \u003Ccode class=\"key\">.escouade.yml\u003C\u002Fcode> never installs or switches it on by itself: it is always the install window, and your consent.\u003C\u002Fp>\n\u003C\u002Fdiv>\n\u003Ch2 id=\"taking-a-permission-back\">Taking a permission back\u003C\u002Fh2>\n\u003Cp>The Permissions tab of its page lists what it can do, with a switch per permission. Taking one back stops its process; the next one starts without it, and the plugin goes on, or stops if it cannot. A secret taken back is no longer given to it: \u003Ccode class=\"key\">secrets\u002Fget\u003C\u002Fcode> answers it an error for that key. The program itself is not taken back: to stop it, switch the plugin off.\u003C\u002Fp>\n\u003Ch2 id=\"its-settings-and-secrets\">Its settings and secrets\u003C\u002Fh2>\n\u003Cp>The Settings tab shows the fields it declares (\u003Ccode class=\"key\">contributes.settings\u003C\u002Fcode>, \u003Ccode class=\"key\">contributes.secrets\u003C\u002Fcode>). A setting is kept with the list of the installed plugins and given to it by \u003Ccode class=\"key\">settings\u002Fget\u003C\u002Fcode>; in a project whose \u003Ca href=\"\u002Fen\u002Fdocs\u002Fescouade-yml\u002F\">\u003Ccode class=\"key\">.escouade.yml\u003C\u002Fcode>\u003C\u002Fa> sets the plugin (\u003Ccode class=\"key\">plugins.<id>\u003C\u002Fcode>), the project’s value goes first. A secret goes to the system’s keychain, under a name of its own (\u003Ccode class=\"key\">plugin:<id>:<key>\u003C\u002Fcode>): the tab only says whether it is kept, and “Forget” erases it.\u003C\u002Fp>\n\u003Ch2 id=\"the-journal\">The journal\u003C\u002Fh2>\n\u003Cp>The Journal tab shows where its process stands (ready, running, restarted after a crash, stopped after three crashes, stopped for its memory…) and the last 500 lines of its journal: its starts, its stops and their reason, its crashes, its standard error, its messages, the calls left unanswered and what it was refused. It is read again every two seconds, filters by kind and copies whole. The secrets it was given are masked there.\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>Start\u003C\u002Fstrong> starts a plugin that has not run yet (it starts by itself at its first activation).\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Restart\u003C\u002Fstrong> starts a stopped plugin again, its crashes forgotten.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>The journal’s file is \u003Ccode>~\u002F.escouade\u002Fplugin-logs\u002F<id>.log\u003C\u002Fcode> (\u003Ca href=\"\u002Fen\u002Fdocs\u002Fplugins\u002Fapi\u002F#the-journal\">the protocol\u003C\u002Fa>).\u003C\u002Fp>\n\u003Ch2 id=\"updates\">Updates\u003C\u002Fh2>\n\u003Cp>When it starts, Escouade looks for a newer version of each plugin: a higher tag of its git repository, a higher version in the folder it was copied from, the last compatible version of the catalog for a plugin of the store (“v1.3.0 · not verified” when it has no seal). What it finds is \u003Cstrong>offered, never installed by itself\u003C\u002Fstrong>: “v1.3.0 available” on its line, “Update to v1.3.0” on its page, the list in Updates, and “Update all” at the top of the installed ones.\u003C\u002Fp>\n\u003Cp>An update goes through the install window, from the installed version to the new one. \u003Cstrong>If it asks for more\u003C\u002Fstrong>, the window says so (“your consent is asked again”) and marks “new” each permission more. Your choices stay: its projects, the permissions taken back, its settings and its secrets. “Update all” opens the window of each, one after the other.\u003C\u002Fp>\n\u003Ch2 id=\"withdrawn-by-escouade\">Withdrawn by Escouade\u003C\u002Fh2>\n\u003Cp>Escouade reads the store’s \u003Cstrong>revocation list\u003C\u002Fstrong> at the start then every 6 hours (or “Read again now”, at the bottom of the installed ones), checks it with its keys and refuses a list older than the last one read; when the store does not answer, it reads its copy on escouade.dev. The last list read applies offline too.\u003C\u002Fp>\n\u003Cul>\n\u003Cli>A \u003Cstrong>withdrawn\u003C\u002Fstrong> version is stopped and switched off; a red band at the top of the installed ones says which, when and why. Escouade deletes nothing: its settings and secrets stay, and “Uninstall” is on its page.\u003C\u002Fli>\n\u003Cli>A version \u003Cstrong>whose seal is withdrawn\u003C\u002Fstrong> keeps running; its page says why it is no longer verified.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>The seal of an installed plugin is checked again on your machine, with the \u003Ccode class=\"key\">version.json\u003C\u002Fcode> and the signature kept at the install: it holds without the store.\u003C\u002Fp>\n\u003Ch2 id=\"uninstalling\">Uninstalling\u003C\u002Fh2>\n\u003Cp>“Uninstall”, on its page, stops its process and erases its folder, its settings, its secrets and its journal. The box “Keep its settings and its secrets for a later install” keeps them: installed again, the plugin finds them. A folder in development stays where it is.\u003C\u002Fp>\n\u003Ch2 id=\"the-developer-mode\">The developer mode\u003C\u002Fh2>\n\u003Cp>In development, “Load a folder…” reads a plugin’s folder where it is, without a copy or a fingerprint, and reads it again as soon as a file changes. Its journal is read live in the Journal tab. See \u003Ca href=\"\u002Fen\u002Fdocs\u002Fplugins\u002Fmanifest\u002F\">the manifest\u003C\u002Fa> and \u003Ca href=\"\u002Fen\u002Fdocs\u002Fplugins\u002Fapi\u002F\">the protocol\u003C\u002Fa> to write one.\u003C\u002Fp>\n",[8,12,15,18,21,24,27,30,33,36,39,42,45],{"id":9,"text":10,"depth":11},"the-view-plugins","The view Plugins",2,{"id":13,"text":14,"depth":11},"installing","Installing",{"id":16,"text":17,"depth":11},"from-the-store","From the store",{"id":19,"text":20,"depth":11},"the-install-window","The install window",{"id":22,"text":23,"depth":11},"the-plugins-shipped-with-escouade","The plugins shipped with Escouade",{"id":25,"text":26,"depth":11},"switching-on-for-the-app-or-by-project","Switching on for the app or by project",{"id":28,"text":29,"depth":11},"taking-a-permission-back","Taking a permission back",{"id":31,"text":32,"depth":11},"its-settings-and-secrets","Its settings and secrets",{"id":34,"text":35,"depth":11},"the-journal","The journal",{"id":37,"text":38,"depth":11},"updates","Updates",{"id":40,"text":41,"depth":11},"withdrawn-by-escouade","Withdrawn by Escouade",{"id":43,"text":44,"depth":11},"uninstalling","Uninstalling",{"id":46,"text":47,"depth":11},"the-developer-mode","The developer mode",1793889382031]