Building Plugins

Plugins are web applications that communicate with Atlas through a local HTTP and WebSocket server. You can build a plugin with any web technology — plain HTML/JS, React, Vue, whatever you prefer.

Plugin Structure

A plugin is a folder containing at minimum a plugin.json manifest file:

my-plugin/
├── plugin.json     # Required: plugin manifest
├── index.html      # Optional: plugin UI
├── main.js         # Your plugin logic
└── ...             # Any other files your plugin needs

The plugin.json Manifest

Every plugin must have a plugin.json file at its root. This is how Atlas discovers and loads your plugin.

{
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "A short description of what this plugin does.",
  "author": "Your Name",
  "entry": "index.html",
  "permissions": [
    "read_vault",
    "ui_components"
  ],
  "settings": {
    "api_key": {
      "type": "string",
      "label": "API Key",
      "description": "Your API key for the external service"
    }
  }
}

Manifest Fields

Field	Required	Description
`name`	Yes	Display name shown in the plugin list
`version`	Yes	Semantic version string (e.g. `1.2.0`)
`description`	Yes	Short description (shown in marketplace listings)
`author`	Yes	Your name or organization
`entry`	No	Path to the main HTML file for plugin UI
`permissions`	Yes	Array of permission strings the plugin needs
`settings`	No	Schema for plugin-specific settings the user can configure

Available Permissions

Request only the permissions your plugin genuinely needs. Users will see this list before enabling your plugin.

Permission	What It Grants
`read_vault`	Read files from the user’s vault
`write_vault`	Create, edit, and delete vault files
`network`	Make outbound HTTP requests to external services
`execute_tools`	Call Atlas agent tools programmatically
`ui_components`	Render a UI panel inside Atlas
`config`	Read Atlas configuration values

Connecting to the Atlas Plugin Server

Atlas runs a local HTTP server (default port 21847) that your plugin communicates with. The server provides endpoints for vault operations, tool execution, and more.

Your plugin receives its API secret as a URL parameter when launched:

http://localhost:21847/plugin/my-plugin/index.html?secret=<plugin_secret>

Include this secret in the X-Plugin-Secret header on all requests to the plugin server.

Example: Reading a Vault File

const secret = new URLSearchParams(window.location.search).get('secret');

const response = await fetch('http://localhost:21847/vault/read', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Plugin-Secret': secret
  },
  body: JSON.stringify({ path: 'daily/2026-02-24.md' })
});

const { content } = await response.json();

Submitting to the Marketplace

Once your plugin is ready to share:

Create a plugin listing through the Atlas developer portal at atlasnotes.io
Fill in the name, description, category, screenshots, and repository URL
Submit for review — the Atlas team reviews all submissions for safety and quality
Once approved, your plugin is published and visible to all users in the marketplace

Review Criteria

The review checks for:

Permissions match what the plugin actually uses
No malicious behavior or hidden data collection
A working plugin.json with accurate metadata
A public repository or download URL

Updating Your Plugin

Increment the version field in plugin.json and submit an update through the developer portal. Updates go through a lighter review than the initial submission.

For an example plugin to reference, check the plugin examples in the Atlas releases repository.