Skip to main content

Package Format

.arcanpkg File Structure​

A plugin is distributed as a .arcanpkg file -- a signed, compressed archive:

postgres-0.1.0.arcanpkg
├── manifest.json           # EngineDescriptor + checksums
├── engine.wasm             # Compiled plugin code (WASM target)
│   — OR —
├── engine.go               # Source code (for Go SDK, compiled by registry)
│   — OR —
├── engine.ts               # Source code (for TS SDK)
│   — OR —
├── engine.py               # Source code (for Python SDK)
├── templates/              # Optional SQL/API templates referenced by code
│   ├── create_role.sql
│   └── revoke_role.sql
└── signature               # Ed25519 signature of manifest.json

The manifest.json contains the full EngineDescriptor along with checksums for all files in the package. The signature file contains an Ed25519 signature of the manifest, used to verify the package's authenticity and integrity.

The templates/ directory is optional and contains SQL or API template files that the engine code references during operations like role creation and revocation.

Package Lifecycle​

1. Author writes engine code using SDK          (10 lines)
2. arcan plugin pack                            → creates .arcanpkg
3. arcan plugin publish                         → uploads to registry, signs
4. User: arcan plugin install postgres           → downloads, verifies, extracts to ~/.arcan/plugins/
5. Core loads manifest, validates capabilities
6. On first request: core loads engine code into sandboxed runtime

Step 1: Author writes engine code​

Using the SDK for their preferred language (Go, TypeScript, or Python), the author implements the engine interface. A minimal engine can be as few as 10 lines of code.

Step 2: Pack​

Running arcan plugin pack creates the .arcanpkg archive from the engine source code, manifest, and any templates.

Step 3: Publish​

Running arcan plugin publish uploads the package to the registry. The registry build service compiles the source (if needed), signs the package with Ed25519, and makes it available for download.

Step 4: Install​

When a user runs arcan plugin install postgres, the core downloads the .arcanpkg from the registry, verifies the checksum and Ed25519 signature, and extracts it to ~/.arcan/plugins/.

Step 5: Discovery​

On startup, the core scans the plugins directory, reads each package's manifest.json, validates SDK version compatibility, and registers the plugin in the engine registry.

Step 6: Loading​

On the first request to that engine type, the core loads the plugin code into the sandboxed runtime. Subsequent requests reuse the loaded runtime instance.