Skip to content
Public template

About

A starter template for building your own Termix plugin.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Termix Logo

Termix Plugin Template

A starter template for building your own Termix plugin

OpenSSF Scorecard


Overview

Termix is self-hosted, plugin-based server management, and every feature outside the core is a plugin. This template is a small Hello World plugin you can copy to start your own. It has one of each thing most plugins need, set up the same way as the official plugins.


Features

  • A tab opened from the sidebar
  • Two API routes behind a permission
  • An admin setting
  • A table with migrations for SQLite, PostgreSQL and MySQL
  • Backend and frontend tests
  • A release workflow that builds and publishes your plugin as a GitHub release, ready to submit to the community registry
  • A CI workflow that checks the lockfile and known vulnerabilities, tests, builds and packs the plugin and lints its workflows with zizmor
  • An OpenSSF Scorecard workflow that rates your repo's security practices each week and shows the result on scorecard.dev. Change the badge link at the top of this README to your repo
  • A Dependabot config that keeps npm packages and actions current

Getting Started

You need Node 24 and a Termix server you are an admin on. The full guide is at docs.termix.site/develop.

  1. Click Use this template on GitHub to make your own repo, then clone it.

  2. In manifest.json, change id, name, description, author, repository and docs. The id is lowercase with dashes, like my-plugin. Then search the repo for hello-world, hello_world and Hello World and rename them to match: package.json, locales/en.json, the index name in src/backend/tables.ts, the API paths in src/backend/routes.ts, the tab id in src/frontend/index.tsx and the tests.

  3. Install the packages, then delete migrations/ and write it again for your id:

    npm install
    npm run migrations
  4. In Termix, open Settings, then General, and turn on Plugin developer mode. Then make an API key under Settings, API keys.

  5. Build and install the plugin on your server. It rebuilds and reinstalls every time you save a file:

    npx termix-plugin dev --server http://localhost:30001 --key tmx_your_key
  6. Run the tests and checks before you push:

    npm test
    npm run typecheck
    npm run validate
    npm run build
  7. Using an AI coding tool? It reads AGENTS.md (or CLAUDE.md), which points it to the full plugin guide that ships with the SDK. Keep the About this plugin section in AGENTS.md up to date.

  8. Write your docs in docs/. docs/index.md is the page people see first. Settings, permissions, environment variables and the API reference are added for you from manifest.json and the @openapi comments on your routes.

When you change a table in src/backend/tables.ts, run npm run migrations to write the SQLite, PostgreSQL and MySQL migrations. npm run pack writes <id>-<version>.tmxplug of the built plugin, which you can install from a file in the Plugins tab while developer mode is on.

Releasing

Work happens on a dev-X.Y.Z branch made from main, named after the version it will ship as. main only changes when a release merges a dev branch into it.

Run the Release workflow by hand from the dev branch:

  • beta publishes X.Y.Z-beta.N (N counts up on its own). Termix only offers it to people who turned on Beta versions for this plugin. Run it as often as you like.
  • stable releases X.Y.Z, merges the dev branch into main, deletes the dev branch and removes that version's beta releases. Add a ## X.Y.Z section to CHANGELOG.md first, it becomes the release notes.
  • dry-run builds and packs without publishing anything.

Releases are immutable. A release is made as a draft, gets its files, then is published, and after that its tag and files can never change. A version that already has a release is refused, so a fix always ships as a new version. Turn on immutable releases in your repo settings (Settings, General, Releases).

No secrets are needed. The workflow records GitHub build provenance for the .tmxplug so the community registry can check where it was built. If a dev branch changes files in .github/workflows, add a TERMIX_PAT secret (a token with repo and workflow scopes) so the release can push it to main.

Submitting to the community registry

Once a version is released, you can submit it to the Termix community registry. The Release run's summary shows the sha256 to put in your submission. Every version is reviewed by a person before it is listed. See the guide.

Once it is listed, admins who turn on the community registry in Plugins, Registries can install it from Browse.

Sponsors

For a paid sponsor spot, email mail@termix.site.


Blacksmith     Cloudflare     Akamai     AWS     Rack Genius     Ginernet     Hetzner     Ember Swan

Support

Bugs and ideas for the template go in this repo: report a bug or request a feature.

Problems with Termix itself (login, hosts, credentials, sharing, sync) go in the Termix repo. Not sure where it goes? Open it there and it will be moved.

Add as much detail as you can, in English if possible. For questions about building plugins, join the Discord server.


License

Apache License 2.0. See LICENSE.

About

A starter template for building your own Termix plugin.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Sponsor this project

Used by

Contributors

Languages