New Extension

If the extension needs to display any UI beyond simple notifications, always use the multi-package webview layout (not inline HTML). This is the standard for all production Podman Desktop extensions.

Where to look in the Podman Desktop codebase

When implementing extension features, you may need to look up API details:

Step 1 — Choose layout

Minimal (no UI)

For extensions that only register commands, providers, status bar items, or configuration — no webview needed.

{name}/
├── .gitignore
├── Containerfile
├── LICENSE
├── README.md
├── icon.png
├── package.json
├── tsconfig.json
└── src/
    └── extension.ts

Multi-package with Svelte webview (default for any UI)

Always use this layout when the extension displays content. Do not use inline HTML strings. The frontend is a Svelte app built by Vite into static assets that the backend loads into a webview panel.

{name}/
├── .gitignore
├── Containerfile
├── LICENSE
├── README.md
├── package.json                       # root workspace — runs both packages
├── packages/
│   ├── backend/                       # the extension entry point (Node.js)
│   │   ├── icon.png
│   │   ├── package.json               # has "main": "./dist/extension.js"
│   │   ├── tsconfig.json
│   │   ├── vite.config.ts
│   │   └── src/
│   │       └── extension.ts
│   ├── frontend/                      # Svelte app built into backend/media/
│   │   ├── index.html
│   │   ├── package.json
│   │   ├── svelte.config.js
│   │   ├── tsconfig.json
│   │   ├── vite.config.ts
│   │   └── src/
│   │       ├── main.ts
│   │       └── App.svelte
│   └── shared/                        # (optional) shared types between frontend & backend
│       └── src/
│           └── ...

Step 2 — File contents (multi-package webview)

.gitignore

dist/
media/
node_modules/

media/ is a build artifact (frontend output) — do not commit it.

Root package.json

{
  "name": "{name}",
  "displayName": "{displayName}",
  "description": "{description}",
  "version": "0.0.1",
  "private": true,
  "engines": { "node": ">=22.0.0", "npm": ">=11.0.0" },
  "scripts": {
    "build": "concurrently \"npm run -w packages/frontend build\" \"npm run -w packages/backend build\"",
    "watch": "concurrently \"npm run -w packages/frontend watch\" \"npm run -w packages/backend watch\""
  },
  "devDependencies": {
    "concurrently": "^8.2.2",
    "typescript": "^5.9.3",
    "vite": "^7.0.0"
  },
  "workspaces": ["packages/*"]
}

Vite version constraint: @sveltejs/[email protected] requires Vite 6 or 7. Do not use Vite 8+.

packages/backend/package.json

This is the extension manifest that Podman Desktop reads:

{
  "name": "{name}",
  "displayName": "{displayName}",
  "description": "{description}",
  "version": "0.0.1",
  "icon": "icon.png",
  "publisher": "{publisher}",
  "license": "Apache-2.0",
  "engines": { "podman-desktop": ">=1.26.0" },
  "main": "./dist/extension.js",
  "contributes": {},
  "scripts": {
    "build": "vite build",
    "watch": "vite --mode development build -w"
  },
  "devDependencies": {
    "@podman-desktop/api": "^1.26.1",
    "@types/node": "^22"
  }
}

packages/backend/tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "Node",
    "resolveJsonModule": true,
    "lib": ["ES2020"],
    "sourceMap": true,
    "rootDir": "src",
    "outDir": "dist",
    "skipLibCheck": true,
    "types": ["node"],
    "strict": true,
    "allowSyntheticDefaultImports": true
  },
  "include": ["src"]
}

packages/backend/vite.config.ts

Use .ts for type-safe config. The backend builds as a CJS library entry point with @podman-desktop/api and all Node builtins externalized.

import { join } from 'path';
import { builtinModules } from 'module';
import { defineConfig } from 'vite';

const PACKAGE_ROOT = __dirname;

export default defineConfig({
  mode: process.env.MODE,
  root: PACKAGE_ROOT,
  envDir: process.cwd(),
  resolve: {
    alias: {
      '/@/': join(PACKAGE_ROOT, 'src') + '/',
    },
  },
  build: {
    sourcemap: 'inline',
    target: 'esnext',
    outDir: 'dist',
    assetsDir: '.',
    minify: process.env.MODE === 'production' ? 'esbuild' : false,
    lib: {
      entry: 'src/extension.ts',
      formats: ['cjs'],
    },
    rollupOptions: {
      external: ['@podman-desktop/api', ...builtinModules.flatMap(p => [p, `node:${p}`])],
      output: { entryFileNames: '[name].js' },
    },
    emptyOutDir: true,
    reportCompressedSize: false,
  },
});

packages/frontend/package.json

{
  "name": "frontend",
  "private": true,
  "type": "module",
  "scripts": {
    "build": "vite build",
    "watch": "vite --mode development build -w"
  },
  "devDependencies": {
    "@sveltejs/vite-plugin-svelte": "^6.1.0",
    "svelte": "^5.53.5"
  }
}

Optionally add @podman-desktop/ui-svelte for native Podman Desktop components (Button, EmptyScreen, etc.), and tailwindcss + autoprefixer + postcss if you want Tailwind styling.

packages/frontend/tsconfig.json

The frontend runs in a browser-like webview environment, so it needs DOM libs and bundler resolution:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "strict": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "allowSyntheticDefaultImports": true,
    "verbatimModuleSyntax": true
  },
  "include": ["src"]
}

packages/frontend/svelte.config.js

Required for Svelte preprocessing (TypeScript in .svelte files):

import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

export default {
  preprocess: [vitePreprocess()],
};

packages/frontend/vite.config.ts

The key: outDir: '../backend/media' — Vite builds the Svelte app into the backend's media/ folder.

import { join } from 'path';
import { svelte } from '@sveltejs/vite-plugin-svelte';
import { defineConfig } from 'vite';
import { fileURLToPath } from 'url';
import path from 'path';

const filename = fileURLToPath(import.meta.url);
const PACKAGE_ROOT = path.dirname(filename);

export default defineConfig({
  mode: process.env.MODE,
  root: PACKAGE_ROOT,
  resolve: {
    alias: { '/@/': join(PACKAGE_ROOT, 'src') + '/' },
  },
  plugins: [svelte()],
  base: '',
  build: {
    sourcemap: true,
    outDir: '../backend/media',
    assetsDir: '.',
    emptyOutDir: true,
    reportCompressedSize: false,
  },
});

packages/frontend/index.html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>{displayName}</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="./src/main.ts"></script>
  </body>
</html>

packages/frontend/src/main.ts

import { mount } from 'svelte';
import App from './App.svelte';

const app = mount(App, { target: document.getElementById('app')! });
export default app;

packages/frontend/src/App.svelte

Write the Svelte component for the extension's UI. Use @podman-desktop/ui-svelte components (Button, EmptyScreen, etc.) for a native look and feel.

Step 3 — Backend loads the built frontend

In packages/backend/src/extension.ts, the backend creates a webview panel and loads the Svelte-built index.html from media/:

import type { ExtensionContext } from '@podman-desktop/api';
import * as extensionApi from '@podman-desktop/api';
import fs from 'node:fs';

export async function activate(extensionContext: ExtensionContext): Promise<void> {
  const panel = extensionApi.window.createWebviewPanel('{name}-panel', '{displayName}', {
    localResourceRoots: [extensionApi.Uri.joinPath(extensionContext.extensionUri, 'media')],
  });
  extensionContext.subscriptions.push(panel);

  const indexHtmlUri = extensionApi.Uri.joinPath(extensionContext.extensionUri, 'media', 'index.html');
  let indexHtml = await fs.promises.readFile(indexHtmlUri.fsPath, 'utf8');

  // Rewrite asset paths so the webview can load them
  const scriptLinks = indexHtml.match(/<script[^>]+src="([^"]+)"/g) ?? [];
  for (const link of scriptLinks) {
    const src = link.match(/src="([^"]+)"/)?.[1];
    if (src) {
      const webviewUri = panel.webview.asWebviewUri(
        extensionApi.Uri.joinPath(extensionContext.extensionUri, 'media', src),
      );
      indexHtml = indexHtml.replace(src, webviewUri.toString());
    }
  }
  const cssLinks = indexHtml.match(/<link[^>]+href="([^"]+)"/g) ?? [];
  for (const link of cssLinks) {
    const href = link.match(/href="([^"]+)"/)?.[1];
    if (href) {
      const webviewUri = panel.webview.asWebviewUri(
        extensionApi.Uri.joinPath(extensionContext.extensionUri, 'media', href),
      );
      indexHtml = indexHtml.replace(href, webviewUri.toString());
    }
  }

  panel.webview.html = indexHtml;
}

export async function deactivate(): Promise<void> {
  console.log('stopping {name} extension');
}

Why this approach? The webview runs in a sandboxed iframe with its own origin. Local file paths don't resolve — you must convert them with panel.webview.asWebviewUri() and set localResourceRoots to grant access to the media/ folder.

Backend-to-frontend messaging

The backend can send messages to the frontend with postMessage, and the frontend listens with window.addEventListener('message', ...):

Backend (in extension.ts):

panel.webview.postMessage({ type: 'status', value: 'running' });

Frontend (in App.svelte):

<script lang="ts">
  let status = $state('idle');

  window.addEventListener('message', (event: MessageEvent) => {
    if (event.data?.type === 'status') {
      status = event.data.value;
    }
  });
</script>

The frontend can also send messages back to the backend using acquirePodmanDesktopApi().postMessage(), and the backend receives them via panel.webview.onDidReceiveMessage. See the full template for a complete RPC implementation using MessageProxy.

Step 4 — Containerfile (multi-package)

FROM scratch AS builder
COPY packages/backend/dist/ /extension/dist
COPY packages/backend/package.json /extension/
COPY packages/backend/media/ /extension/media
COPY packages/backend/icon.png /extension/
COPY LICENSE /extension/
COPY README.md /extension/

FROM scratch

LABEL org.opencontainers.image.title="{displayName}" \
      org.opencontainers.image.description="{description}" \
      org.opencontainers.image.vendor="{publisher}" \
      io.podman-desktop.api.version=">= 1.26.0"

COPY --from=builder /extension /extension

The OCI image copies from packages/backend/ (the extension manifest lives there), plus the media/ folder that contains the built frontend assets.

Step 5 — Build and verify

npm install
npm run build

After building, verify:

• packages/backend/dist/extension.js exists (the backend)
• packages/backend/media/index.html exists (the built frontend)

Step 6 — Test locally in Podman Desktop

1. Open Podman Desktop
2. Go to Settings > Preferences > Extensions and enable Development mode
3. Go to Extensions > Local Extensions tab
4. Click Add a local folder extension... and select the folder containing the extension package.json:
   • Multi-package layout: select packages/backend/ (not the root)
   • Minimal layout: select the repository root
5. Verify the extension appears as ACTIVE
6. Test the extension's functionality

Step 7 — Package and publish (when ready)

npm run build
podman build -t quay.io/{publisher}/{name} .
podman push quay.io/{publisher}/{name}

To add it to the official catalog, open a PR on podman-desktop-catalog adding the extension to static/api/extensions.json.

Minimal extension (no webview)

For extensions without a UI panel, use the single-package layout from Step 1. Same package.json / vite.config.ts patterns as the backend package, minus the media/ loading.

Quick reference — common API patterns

Common pitfalls

Getting the engineId for container operations

Many containerEngine methods (createContainer, startContainer, stopContainer, deleteContainer, inspectContainer) require an engineId string. This is not connection.name from getContainerConnections() — that will produce a "no engine matching this container" error.

The correct way to obtain the engineId:

const connections = extensionApi.provider.getContainerConnections();
const running = connections.filter(c => c.connection.status() === 'started');
if (running.length === 0) {
  throw new Error('No running container engine found');
}
const connection = running[0].connection;

// Use listInfos to get the real engineId
const infos = await extensionApi.containerEngine.listInfos({ provider: connection });
if (infos.length === 0) {
  throw new Error('No engine info available');
}
const engineId = infos[0].engineId;

await extensionApi.containerEngine.createContainer(engineId, {
  /* ... */
});

Alternatively, if you already have containers or images from listContainers() or listImages(), their engineId field can be reused directly.

createContainer auto-starts by default

ContainerCreateOptions.start defaults to true. If you call createContainer followed by startContainer, the second call will fail with HTTP 304 ("container already started"). Either:

• Rely on the default and skip startContainer, or
• Pass start: false in the create options if you need to configure the container before starting it

For the full API surface, see extension-api.d.ts.

Official templates

• Minimal: podman-desktop-extension-minimal-template
• Webview (inline HTML): podman-desktop-extension-webview-template
• Full (Svelte + Tailwind + multi-package): podman-desktop-extension-full-template — this is the recommended starting point for any extension with a UI.