diff --git a/.github/workflows/build-images.yml b/.github/workflows/build-images.yml
index fdbdbd38..1b111cd6 100644
--- a/.github/workflows/build-images.yml
+++ b/.github/workflows/build-images.yml
@@ -105,6 +105,20 @@ jobs:
             type=ref,event=tag
             type=raw,value=latest,enable=${{ github.event_name == 'release' && !github.event.release.prerelease }}
 
+      - name: Docker Meta (Cloud)
+        id: meta-cloud
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ github.repository }}/cloud
+          bake-target: cloud
+          flavor: latest=false
+          tags: |
+            type=sha
+            type=ref,event=branch
+            type=ref,event=pr
+            type=ref,event=tag
+            type=raw,value=latest,enable=${{ github.event_name == 'release' && !github.event.release.prerelease }}
+
       - name: Docker Meta (Docs)
         id: meta-docs
         uses: docker/metadata-action@v5
@@ -169,6 +183,7 @@ jobs:
             ${{ steps.meta-nodejs.outputs.bake-file }}
             ${{ steps.meta-docker.outputs.bake-file }}
             ${{ steps.meta-docker-nodejs.outputs.bake-file }}
+            ${{ steps.meta-cloud.outputs.bake-file }}
             ${{ steps.meta-docs.outputs.bake-file }}
             ${{ steps.meta-agent.outputs.bake-file }}
             ${{ steps.meta-manager.outputs.bake-file }}
@@ -182,6 +197,8 @@ jobs:
             docker.cache-to=type=gha,mode=max,scope=docker-${{ github.ref_name }}
             docker-nodejs.cache-from=type=gha,scope=docker-nodejs-${{ github.ref_name }}
             docker-nodejs.cache-to=type=gha,mode=max,scope=docker-nodejs-${{ github.ref_name }}
+            cloud.cache-from=type=gha,scope=cloud-${{ github.ref_name }}
+            cloud.cache-to=type=gha,mode=max,scope=cloud-${{ github.ref_name }}
             docs.cache-from=type=gha,scope=docs-${{ github.ref_name }}
             docs.cache-to=type=gha,mode=max,scope=docs-${{ github.ref_name }}
             agent.cache-from=type=gha,scope=agent-${{ github.ref_name }}
diff --git a/.github/workflows/os-cloud-provider-preview.yml b/.github/workflows/os-cloud-provider-preview.yml
new file mode 100644
index 00000000..4bf61efa
--- /dev/null
+++ b/.github/workflows/os-cloud-provider-preview.yml
@@ -0,0 +1,69 @@
+name: os-cloud-provider preview package
+
+# On every push to a same-repo pull request that touches the provider, publish
+# @mieweb/os-cloud-provider to the GitHub Packages npm registry as
+# `<version>-pr<PR>.<run>` under dist-tag `pr<PR>`, so cross-repo PRs (e.g.
+# @mieweb/cli in mieweb/cloud) can depend on it with a plain semver reference
+# plus `@mieweb:registry=https://npm.pkg.github.com` in .npmrc. Once merged and
+# released to npmjs, consumers switch to the real version and drop that line.
+
+on:
+  pull_request:
+    paths:
+      - 'packages/os-cloud-provider/**'
+      - '.github/workflows/os-cloud-provider-preview.yml'
+
+concurrency:
+  group: os-cloud-provider-preview-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  publish:
+    # GITHUB_TOKEN is read-only on fork PRs.
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/os-cloud-provider
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@v4
+        with:
+          package_json_file: packages/os-cloud-provider/package.json
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: packages/os-cloud-provider/pnpm-lock.yaml
+          registry-url: https://npm.pkg.github.com
+          scope: '@mieweb'
+      - run: pnpm install --frozen-lockfile
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Stamp preview version
+        id: stamp
+        env:
+          SUFFIX: pr${{ github.event.pull_request.number }}.${{ github.run_number }}
+        run: |
+          v=$(node -p 'require("./package.json").version.replace(/-.*$/, "")')-$SUFFIX
+          npm pkg set version="$v"
+          echo "version=$v" >> "$GITHUB_OUTPUT"
+      # Preview builds default to this PR's cloud image (build-images.yml pushes
+      # cloud:pr-<N> on every PR push); `latest` only exists after a release.
+      - name: Default to this PR's cloud image
+        env:
+          TAG: pr-${{ github.event.pull_request.number }}
+        run: |
+          sed -i "s#\(DEFAULT_IMAGE = 'ghcr.io/mieweb/opensource-server/cloud\):latest'#\1:$TAG'#" src/config.ts
+          grep -q "cloud:$TAG'" src/config.ts
+      # prepack builds dist/.
+      - run: pnpm publish --no-git-checks --tag pr${{ github.event.pull_request.number }}
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - run: echo "Published \`@mieweb/os-cloud-provider@${{ steps.stamp.outputs.version }}\` to npm.pkg.github.com" >> "$GITHUB_STEP_SUMMARY"
diff --git a/.github/workflows/os-cloud-provider.yml b/.github/workflows/os-cloud-provider.yml
new file mode 100644
index 00000000..eed3a7d8
--- /dev/null
+++ b/.github/workflows/os-cloud-provider.yml
@@ -0,0 +1,55 @@
+name: os-cloud-provider
+
+# Typecheck + test @mieweb/os-cloud-provider (packages/os-cloud-provider).
+# The regular suite runs against an in-process fake Manager; the live suite
+# (pnpm test:live) needs a running Manager and is not run here.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'packages/os-cloud-provider/**'
+      - 'create-a-container/openapi.v1.yaml'
+      - '.github/workflows/os-cloud-provider.yml'
+  pull_request:
+    paths:
+      - 'packages/os-cloud-provider/**'
+      - 'create-a-container/openapi.v1.yaml'
+      - '.github/workflows/os-cloud-provider.yml'
+
+permissions:
+  contents: read
+  # @mieweb/deploy-contract preview versions come from GitHub Packages.
+  packages: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node: ['22', '24']
+    defaults:
+      run:
+        working-directory: packages/os-cloud-provider
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@v4
+        with:
+          package_json_file: packages/os-cloud-provider/package.json
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: pnpm
+          cache-dependency-path: packages/os-cloud-provider/pnpm-lock.yaml
+          registry-url: https://npm.pkg.github.com
+          scope: '@mieweb'
+      - run: pnpm install --frozen-lockfile
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Generated Manager types are up to date
+        run: pnpm gen:types && git diff --exit-code -- src/generated
+      - run: pnpm typecheck
+      - run: pnpm test
+      - run: pnpm build
diff --git a/agent/src/volumes.ts b/agent/src/volumes.ts
index 7480bfee..29885497 100644
--- a/agent/src/volumes.ts
+++ b/agent/src/volumes.ts
@@ -33,11 +33,12 @@ import fs from 'fs';
 import { log } from './log';
 import type { SiteConfig, SiteVolume, VolumeResult } from './types';
 
-// Mode for created directories. RW volumes get owner/group rwx (the id-mapped
-// container root owns the dir, so it can write); RO volumes are r-x. World bits
-// are left closed so other tenants can't read another container's data.
-const RW_MODE = 0o0770;
-const RO_MODE = 0o0550;
+// Mode for volume roots, like /var/lib: the id-mapped container root owns the
+// dir (rwx for RW, r-x for RO) and non-root service accounts inside the
+// container can traverse it to their own subdirectories. Isolation between
+// tenants comes from each container mounting only its own volume.
+const RW_MODE = 0o0755;
+const RO_MODE = 0o0555;
 
 /**
  * Collect the volumes to provision from the config snapshot (site-level).
diff --git a/create-a-container/client/src/pages/auth/LoginPage.tsx b/create-a-container/client/src/pages/auth/LoginPage.tsx
index 3b5e06f4..b2ffd624 100644
--- a/create-a-container/client/src/pages/auth/LoginPage.tsx
+++ b/create-a-container/client/src/pages/auth/LoginPage.tsx
@@ -45,6 +45,9 @@ function asExternalUrl(target: string): string | null {
     return null;
   }
   if (url.protocol !== 'http:' && url.protocol !== 'https:') return null;
+  // Same-origin server routes (e.g. the CLI login handoff at
+  // /api/v1/auth/cli/callback) aren't SPA pages — they need a real navigation.
+  if (url.origin === window.location.origin && url.pathname.startsWith('/api/')) return url.href;
   // Same-origin targets stay in-app (let react-router handle them as paths).
   if (url.origin === window.location.origin) return null;
   return url.href;
diff --git a/create-a-container/models/dns-service.js b/create-a-container/models/dns-service.js
index 254bfa43..0151ca00 100644
--- a/create-a-container/models/dns-service.js
+++ b/create-a-container/models/dns-service.js
@@ -16,7 +16,8 @@ module.exports = (sequelize, DataTypes) => {
       references: {
         model: 'Services',
         key: 'id'
-      }
+      },
+      onDelete: 'CASCADE'
     },
     recordType: {
       type: DataTypes.ENUM('SRV'),
diff --git a/create-a-container/models/http-service.js b/create-a-container/models/http-service.js
index 7d12e1c4..1455af74 100644
--- a/create-a-container/models/http-service.js
+++ b/create-a-container/models/http-service.js
@@ -17,7 +17,8 @@ module.exports = (sequelize, DataTypes) => {
       references: {
         model: 'Services',
         key: 'id'
-      }
+      },
+      onDelete: 'CASCADE'
     },
     externalHostname: {
       type: DataTypes.STRING(255),
diff --git a/create-a-container/models/transport-service.js b/create-a-container/models/transport-service.js
index 10397805..dfd7a652 100644
--- a/create-a-container/models/transport-service.js
+++ b/create-a-container/models/transport-service.js
@@ -47,7 +47,8 @@ module.exports = (sequelize, DataTypes) => {
       references: {
         model: 'Services',
         key: 'id'
-      }
+      },
+      onDelete: 'CASCADE'
     },
     protocol: {
       type: DataTypes.ENUM('tcp', 'udp'),
diff --git a/create-a-container/openapi.v1.yaml b/create-a-container/openapi.v1.yaml
index 81f6e935..774eadcb 100644
--- a/create-a-container/openapi.v1.yaml
+++ b/create-a-container/openapi.v1.yaml
@@ -621,6 +621,51 @@ paths:
       responses:
         '302': { description: 'Redirect to the post-login destination on success, or /login?oidc_error=<code> on failure' }
         '404': { description: 'OIDC not configured (code: oidc_disabled)' }
+  /auth/cli/callback:
+    get:
+      operationId: cli_login_authorize
+      tags: [Auth]
+      summary: CLI loopback login — browser confirmation page
+      description: >-
+        Browser-facing (HTML), used by `mieweb login`. Without a session, it
+        redirects through the normal sign-in (OIDC or /login) and comes back
+        here. With a session, it renders a confirmation form that POSTs back to
+        this path. A GET never mints a key.
+      security: []
+      parameters:
+        - { in: query, name: port, required: true, schema: { type: integer, minimum: 1024, maximum: 65535 }, description: Loopback port the CLI listens on (host is always 127.0.0.1) }
+        - { in: query, name: state, required: true, schema: { type: string, pattern: '^[A-Za-z0-9_-]{16,128}$' }, description: CLI-generated one-time nonce, echoed back }
+        - { in: query, name: client, schema: { type: string, pattern: '^[A-Za-z0-9._@-]{1,64}$' }, description: Label recorded in the minted key's description }
+      responses:
+        '200': { description: HTML confirmation page }
+        '302': { description: Redirect to sign-in when there is no session }
+        '400': { description: HTML error page for invalid parameters }
+    post:
+      operationId: cli_login_mint
+      tags: [Auth]
+      summary: CLI loopback login — mint an API key and hand it to the loopback listener
+      description: >-
+        Requires a browser session and a CSRF token (`_csrf`). Bearer-only
+        requests are rejected. Mints an API key for the session user and
+        303-redirects to `http://127.0.0.1:<port>/callback#key=…&id=…&user=…&state=…`.
+        The key is in the URL fragment, so it never appears in a request line.
+      security: []
+      requestBody:
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              required: [_csrf, port, state]
+              properties:
+                _csrf: { type: string }
+                port: { type: integer }
+                state: { type: string }
+                client: { type: string }
+      responses:
+        '303': { description: Redirect to the loopback listener with the key in the fragment }
+        '400': { description: HTML error page for invalid parameters }
+        '401': { description: No browser session }
+        '403': { description: Missing/invalid CSRF token }
   /auth/logout:
     post:
       operationId: logout
diff --git a/create-a-container/routers/api/v1/__tests__/cli-auth.test.js b/create-a-container/routers/api/v1/__tests__/cli-auth.test.js
new file mode 100644
index 00000000..5852142f
--- /dev/null
+++ b/create-a-container/routers/api/v1/__tests__/cli-auth.test.js
@@ -0,0 +1,152 @@
+/**
+ * Integration tests for the CLI loopback login handoff (issue #475 §4.3):
+ * GET/POST /api/v1/auth/cli/callback.
+ *
+ * Requests carry a non-localhost X-Forwarded-For so the CSRF guard's
+ * localhost bypass doesn't apply; that way the session + CSRF path is the
+ * real one a browser takes.
+ */
+
+const request = require('supertest');
+const { buildApp, bearer } = require('../../../../tests/helpers/app');
+const { resetDb, closeDb, createUser, createApiKey } = require('../../../../tests/helpers/db');
+const { ApiKey } = require('../../../../models');
+const { parseHandoff } = require('../cli-auth');
+
+const REMOTE = ['X-Forwarded-For', '203.0.113.7'];
+const STATE = 'abcdefghijklmnop0123456789';
+const BASE = '/api/v1/auth/cli/callback';
+
+async function loggedInAgent(app, uid) {
+  const agent = request.agent(app);
+  const csrf = await agent.get('/api/v1/csrf-token').set(...REMOTE);
+  const token = csrf.body.data.csrfToken;
+  const res = await agent
+    .post('/api/v1/auth/login')
+    .set(...REMOTE)
+    .set('X-CSRF-Token', token)
+    .send({ username: uid, password: 'correct horse battery staple' });
+  expect(res.status).toBe(200);
+  return agent;
+}
+
+function csrfFrom(html) {
+  const m = html.match(/name="_csrf" value="([^"]+)"/);
+  return m && m[1];
+}
+
+describe('parseHandoff', () => {
+  test('accepts a valid port/state/client', () => {
+    expect(parseHandoff({ port: '53682', state: STATE, client: 'mieweb-cli@laptop' })).toEqual({
+      port: 53682,
+      state: STATE,
+      client: 'mieweb-cli@laptop',
+    });
+  });
+
+  test.each([
+    [{ port: '80', state: STATE }],
+    [{ port: '70000', state: STATE }],
+    [{ port: '5368a', state: STATE }],
+    [{ port: '053682', state: STATE }],
+    [{ port: '53682', state: 'short' }],
+    [{ port: '53682', state: `${STATE}<script>` }],
+    [{ port: '53682', state: STATE, client: 'evil host/../x' }],
+  ])('rejects %j', (input) => {
+    expect(() => parseHandoff(input)).toThrow();
+  });
+});
+
+describe('/api/v1/auth/cli/callback', () => {
+  let app;
+  let alice;
+
+  beforeAll(async () => {
+    await resetDb();
+    app = buildApp();
+    await createUser({ uid: 'firstadmin' });
+    alice = await createUser({ uid: 'alice' });
+  });
+
+  afterAll(async () => {
+    await closeDb();
+  });
+
+  test('bad params render an error page and never redirect', async () => {
+    const res = await request(app).get(`${BASE}?port=22&state=${STATE}`).set(...REMOTE);
+    expect(res.status).toBe(400);
+    expect(res.type).toBe('text/html');
+    expect(res.headers.location).toBeUndefined();
+  });
+
+  test('unauthenticated GET bounces to the SPA login with a relative return URL', async () => {
+    const res = await request(app)
+      .get(`${BASE}?port=53682&state=${STATE}&client=cli&junk=1`)
+      .set(...REMOTE);
+    expect(res.status).toBe(302);
+    const loc = new URL(res.headers.location, 'http://manager.test');
+    expect(loc.pathname).toBe('/login');
+    const back = loc.searchParams.get('redirect');
+    expect(back).toBe(`${BASE}?port=53682&state=${STATE}&client=cli`);
+  });
+
+  test('authenticated GET shows a confirmation form and mints nothing', async () => {
+    const agent = await loggedInAgent(app, 'alice');
+    const before = await ApiKey.count({ where: { uidNumber: alice.uidNumber } });
+    const res = await agent.get(`${BASE}?port=53682&state=${STATE}`).set(...REMOTE);
+    expect(res.status).toBe(200);
+    expect(res.text).toContain('Authorize command-line access');
+    expect(res.text).toContain('127.0.0.1:53682');
+    expect(csrfFrom(res.text)).toBeTruthy();
+    expect(await ApiKey.count({ where: { uidNumber: alice.uidNumber } })).toBe(before);
+  });
+
+  test('POST without a CSRF token is rejected', async () => {
+    const agent = await loggedInAgent(app, 'alice');
+    const res = await agent
+      .post(BASE)
+      .set(...REMOTE)
+      .type('form')
+      .send({ port: '53682', state: STATE });
+    expect(res.status).toBe(403);
+  });
+
+  test('POST with session + CSRF mints a working key and redirects to the loopback fragment', async () => {
+    const agent = await loggedInAgent(app, 'alice');
+    const form = await agent.get(`${BASE}?port=53682&state=${STATE}&client=cli`).set(...REMOTE);
+    const res = await agent
+      .post(BASE)
+      .set(...REMOTE)
+      .type('form')
+      .send({ _csrf: csrfFrom(form.text), port: '53682', state: STATE, client: 'cli' });
+    expect(res.status).toBe(303);
+    const loc = new URL(res.headers.location);
+    expect(loc.origin).toBe('http://127.0.0.1:53682');
+    expect(loc.pathname).toBe('/callback');
+    expect(loc.search).toBe('');
+    const frag = new URLSearchParams(loc.hash.slice(1));
+    expect(frag.get('state')).toBe(STATE);
+    expect(frag.get('user')).toBe('alice');
+    const key = frag.get('key');
+    expect(key).toBeTruthy();
+
+    const row = await ApiKey.findByPk(frag.get('id'));
+    expect(row.uidNumber).toBe(alice.uidNumber);
+    expect(row.description).toMatch(/^cli \(CLI login/);
+
+    const session = await request(app).get('/api/v1/session').set(...bearer(key));
+    expect(session.status).toBe(200);
+    expect(session.body.data.user).toBe('alice');
+  });
+
+  test('a Bearer key cannot mint another key through the handoff', async () => {
+    const { plainKey } = await createApiKey(alice);
+    const res = await request(app)
+      .post(BASE)
+      .set(...REMOTE)
+      .set(...bearer(plainKey))
+      .type('form')
+      .send({ port: '53682', state: STATE });
+    expect(res.status).toBe(401);
+  });
+});
diff --git a/create-a-container/routers/api/v1/__tests__/containers.self-service.test.js b/create-a-container/routers/api/v1/__tests__/containers.self-service.test.js
new file mode 100644
index 00000000..1f37656c
--- /dev/null
+++ b/create-a-container/routers/api/v1/__tests__/containers.self-service.test.js
@@ -0,0 +1,116 @@
+/**
+ * Self-service (non-admin) deploy path used by @mieweb/os-cloud-provider
+ * (issue #475 §4.4). A regular user must be able to:
+ *   - discover usable external domains via GET /containers/new, without
+ *     seeing the admin-only Cloudflare credentials on those rows;
+ *   - create their own container with one HTTP service, env vars and an rw
+ *     volume;
+ *   - find it by hostname, update it (services/env/restart), and delete it.
+ */
+
+const request = require('supertest');
+const { buildApp, bearer } = require('../../../../tests/helpers/app');
+const { resetDb, closeDb, createUser, createApiKey } = require('../../../../tests/helpers/db');
+const { Site, Node, ExternalDomain, Job, Volume } = require('../../../../models');
+
+describe('non-admin deploy path', () => {
+  let app;
+  let userKey;
+  let site;
+  let domain;
+
+  beforeAll(async () => {
+    await resetDb();
+    app = buildApp();
+    await createUser({ uid: 'firstadmin' }); // absorbs the auto-admin promotion
+    const user = await createUser({ uid: 'deployer' });
+    ({ plainKey: userKey } = await createApiKey(user));
+    site = await Site.create({ name: 's', internalDomain: 'ex.test' });
+    await Node.create({ siteId: site.id, name: 'n', nodeType: 'dummy' });
+    domain = await ExternalDomain.create({
+      name: 'apps.example.test',
+      siteId: site.id,
+      cloudflareApiEmail: 'dns@example.test',
+      cloudflareApiKey: 'super-secret-cf-key',
+    });
+  });
+
+  afterAll(async () => {
+    await closeDb();
+  });
+
+  const api = (method, path) =>
+    request(app)[method](`/api/v1/sites/${site.id}/containers${path}`).set(...bearer(userKey));
+
+  test('GET /containers/new lists domains without Cloudflare credentials', async () => {
+    const res = await api('get', '/new');
+    expect(res.status).toBe(200);
+    expect(res.body.data.externalDomains).toEqual([
+      { id: domain.id, name: 'apps.example.test', siteId: site.id },
+    ]);
+    expect(JSON.stringify(res.body)).not.toContain('super-secret-cf-key');
+  });
+
+  test('create → list by hostname → update → delete', async () => {
+    const create = await api('post', '').send({
+      hostname: 'myapp',
+      template: 'ghcr.io/mieweb/opensource-server/cloud:latest',
+      environmentVars: [{ key: 'PORT', value: '8787' }],
+      volumes: [{ name: 'data', mountPath: '/mnt/data', mode: 'rw' }],
+      services: {
+        http: {
+          type: 'http',
+          internalPort: 8787,
+          externalHostname: 'myapp',
+          externalDomainId: domain.id,
+          authRequired: false,
+        },
+      },
+    });
+    expect(create.status).toBe(201);
+    const { containerId: id, jobId } = create.body.data;
+    expect(await Job.findByPk(jobId)).toBeTruthy();
+    expect(await Volume.count({ where: { containerId: id } })).toBe(1);
+
+    const list = await api('get', '?hostname=myapp');
+    expect(list.status).toBe(200);
+    expect(list.body.data).toHaveLength(1);
+    const c = list.body.data[0];
+    expect(c.id).toBe(id);
+    expect(c.template).toBe('ghcr.io/mieweb/opensource-server/cloud:latest');
+    expect(c.environmentVars).toEqual({ PORT: '8787' });
+    expect(c.httpEntries[0].externalUrl).toBe('https://myapp.apps.example.test');
+    const httpSvc = c.services.find((s) => s.type === 'http');
+
+    // A second create for the same hostname conflicts (the upsert retry path).
+    const dup = await api('post', '').send({ hostname: 'myapp', template: 'debian' });
+    expect(dup.status).toBe(409);
+
+    const update = await api('put', `/${id}`).send({
+      environmentVars: [{ key: 'PORT', value: '9000' }],
+      services: {
+        old: { id: httpSvc.id, deleted: true },
+        http: {
+          type: 'http',
+          internalPort: 9000,
+          externalHostname: 'myapp',
+          externalDomainId: domain.id,
+          authRequired: true,
+        },
+      },
+      restart: true,
+    });
+    expect(update.status).toBe(200);
+    const after = await api('get', `/${id}`);
+    expect(after.body.data.environmentVars).toEqual({ PORT: '9000' });
+    const https = after.body.data.services.filter((s) => s.type === 'http');
+    expect(https).toHaveLength(1);
+    expect(https[0].internalPort).toBe(9000);
+    expect(https[0].httpService.authRequired).toBe(true);
+
+    const del = await api('delete', `/${id}`);
+    expect(del.status).toBe(200);
+    expect(del.body.data.deleted).toBe(true);
+    expect((await api('get', '?hostname=myapp')).body.data).toHaveLength(0);
+  });
+});
diff --git a/create-a-container/routers/api/v1/auth.js b/create-a-container/routers/api/v1/auth.js
index 00f8daec..a51cd44c 100644
--- a/create-a-container/routers/api/v1/auth.js
+++ b/create-a-container/routers/api/v1/auth.js
@@ -379,4 +379,7 @@ router.post(
   }),
 );
 
+// /api/v1/auth/cli/* — loopback login handoff for `mieweb login` (issue #475).
+router.use('/cli', require('./cli-auth'));
+
 module.exports = router;
diff --git a/create-a-container/routers/api/v1/cli-auth.js b/create-a-container/routers/api/v1/cli-auth.js
new file mode 100644
index 00000000..7c2e1231
--- /dev/null
+++ b/create-a-container/routers/api/v1/cli-auth.js
@@ -0,0 +1,156 @@
+/**
+ * /api/v1/auth/cli — loopback login handoff for command-line clients (issue #475 §4.3).
+ *
+ * `mieweb login --target mieweb` (the @mieweb/os-cloud-provider package) starts a
+ * temporary HTTP listener on 127.0.0.1:<port> and opens the browser at
+ *
+ *   GET /api/v1/auth/cli/callback?port=<port>&state=<nonce>[&client=<label>]
+ *
+ * 1. With no browser session, this route sends the user through the normal
+ *    sign-in (OIDC or the SPA password form) and returns here afterwards. It
+ *    passes its own URL as a *relative* `redirect`, which the existing
+ *    `safeRedirectUrl` allowlist already accepts.
+ * 2. With a session, it shows a confirmation page. A GET never mints a key, so
+ *    a link or <img> can't create keys silently.
+ * 3. The confirmation form POSTs back here (session + CSRF protected). The route
+ *    mints an API key for the session user and 303-redirects to
+ *    http://127.0.0.1:<port>/callback#key=…&id=…&user=…&state=…
+ *
+ * Loopback safety: this route does NOT use `safeRedirectUrl`. Only a port is
+ * accepted from the client; the redirect host is hard-coded to 127.0.0.1. The
+ * CLI-generated `state` nonce is echoed back so the CLI can reject a handoff
+ * it didn't start. The key travels in the URL *fragment*, so browsers never
+ * send it in a request line, Referer header, or proxy log.
+ */
+
+const express = require('express');
+const { isOidcEnabled } = require('../../../utils/oidc');
+const { generateCsrfToken, asyncHandler } = require('../../../middlewares/api');
+const apiKeys = require('../../../resources/apikeys/service');
+
+const router = express.Router();
+
+const STATE_RE = /^[A-Za-z0-9_-]{16,128}$/;
+const CLIENT_RE = /^[A-Za-z0-9._@-]{1,64}$/;
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, (c) => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+  })[c]);
+}
+
+/**
+ * Validate the CLI handoff params. Returns `{ port, state, client }` or throws
+ * a string describing the problem (rendered as an HTML error page).
+ */
+function parseHandoff(src) {
+  const port = Number.parseInt(String(src.port ?? ''), 10);
+  if (!Number.isInteger(port) || String(port) !== String(src.port) || port < 1024 || port > 65535) {
+    throw 'Invalid or missing loopback port.';
+  }
+  const state = String(src.state ?? '');
+  if (!STATE_RE.test(state)) throw 'Invalid or missing state parameter.';
+  const rawClient = src.client === undefined || src.client === '' ? null : String(src.client);
+  if (rawClient !== null && !CLIENT_RE.test(rawClient)) throw 'Invalid client label.';
+  return { port, state, client: rawClient };
+}
+
+function page(res, status, title, body) {
+  res
+    .status(status)
+    .set('Cache-Control', 'no-store')
+    .set('Content-Security-Policy', "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'")
+    .set('X-Frame-Options', 'DENY')
+    .type('html')
+    .send(`<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<style>
+  body{font-family:system-ui,sans-serif;max-width:32rem;margin:4rem auto;padding:0 1rem;color:#1f2937}
+  h1{font-size:1.4rem} code{background:#f3f4f6;padding:.1rem .3rem;border-radius:.2rem}
+  .actions{display:flex;gap:.75rem;margin-top:1.5rem}
+  button,a.btn{font:inherit;padding:.5rem 1rem;border-radius:.375rem;border:1px solid #d1d5db;background:#fff;color:inherit;text-decoration:none;cursor:pointer}
+  button.primary{background:#2563eb;border-color:#2563eb;color:#fff}
+</style></head><body>${body}</body></html>`);
+}
+
+function errorPage(res, message) {
+  return page(res, 400, 'CLI sign-in failed', `<h1>CLI sign-in failed</h1><p>${escapeHtml(message)}</p>
+<p>Re-run <code>mieweb login</code> to start over.</p>`);
+}
+
+// GET — confirmation page, or bounce through sign-in first.
+router.get('/callback', asyncHandler(async (req, res) => {
+  let handoff;
+  try {
+    handoff = parseHandoff(req.query);
+  } catch (msg) {
+    return errorPage(res, msg);
+  }
+
+  if (!req.session?.user) {
+    // Only the validated params go into the return URL; anything else in the
+    // query string is dropped.
+    const params = new URLSearchParams({ port: String(handoff.port), state: handoff.state });
+    if (handoff.client) params.set('client', handoff.client);
+    const self = `${req.baseUrl}/callback?${params.toString()}`;
+    const target = isOidcEnabled()
+      ? `/api/v1/auth/oidc/login?redirect=${encodeURIComponent(self)}`
+      : `/login?redirect=${encodeURIComponent(self)}`;
+    return res.redirect(302, target);
+  }
+
+  const csrfToken = generateCsrfToken(req);
+  const label = handoff.client || 'mieweb-cli';
+  return page(res, 200, 'Authorize command-line access', `
+<h1>Authorize command-line access</h1>
+<p>Signed in as <strong>${escapeHtml(req.session.user)}</strong>.</p>
+<p>A command-line client (<code>${escapeHtml(label)}</code>) is asking for an API key for your
+account. The key will be sent to a program listening on <code>127.0.0.1:${handoff.port}</code>
+on <em>this</em> computer.</p>
+<p>Only continue if you just ran <code>mieweb login</code>.</p>
+<form method="post" action="${escapeHtml(`${req.baseUrl}/callback`)}">
+  <input type="hidden" name="_csrf" value="${escapeHtml(csrfToken)}">
+  <input type="hidden" name="port" value="${handoff.port}">
+  <input type="hidden" name="state" value="${escapeHtml(handoff.state)}">
+  ${handoff.client ? `<input type="hidden" name="client" value="${escapeHtml(handoff.client)}">` : ''}
+  <div class="actions">
+    <button class="primary" type="submit">Authorize</button>
+    <a class="btn" href="/">Cancel</a>
+  </div>
+</form>`);
+}));
+
+// POST — mint a key for the session user and hand it to the loopback listener.
+// csrfGuard (mounted above /auth) has already validated `_csrf` for this
+// session-cookie request. Bearer-only callers are rejected: the handoff exists
+// to turn a *browser session* into a key, not to let a key mint more keys.
+router.post('/callback', asyncHandler(async (req, res) => {
+  const bearerOnly = (req.get('Authorization') || '').startsWith('Bearer ');
+  if (!req.session?.user || bearerOnly) {
+    return page(res, 401, 'Not signed in', '<h1>Not signed in</h1><p>Sign in and re-run <code>mieweb login</code>.</p>');
+  }
+
+  let handoff;
+  try {
+    handoff = parseHandoff(req.body || {});
+  } catch (msg) {
+    return errorPage(res, msg);
+  }
+
+  const description = `${handoff.client || 'mieweb-cli'} (CLI login ${new Date().toISOString().slice(0, 10)})`;
+  const { key, plainKey } = await apiKeys.createKey(req.session.user, { description });
+
+  const fragment = new URLSearchParams({
+    key: plainKey,
+    id: key.id,
+    user: req.session.user,
+    state: handoff.state,
+  });
+  res.set('Cache-Control', 'no-store');
+  res.set('Referrer-Policy', 'no-referrer');
+  return res.redirect(303, `http://127.0.0.1:${handoff.port}/callback#${fragment.toString()}`);
+}));
+
+module.exports = router;
+module.exports.parseHandoff = parseHandoff;
diff --git a/create-a-container/routers/api/v1/containers.js b/create-a-container/routers/api/v1/containers.js
index 97b243d0..f1a5bf74 100644
--- a/create-a-container/routers/api/v1/containers.js
+++ b/create-a-container/routers/api/v1/containers.js
@@ -445,7 +445,14 @@ router.get(
   '/new',
   asyncHandler(async (req, res) => {
     const site = await loadSite(req.params.siteId);
-    const externalDomains = await site.getSortedExternalDomains();
+    // Any container creator (not just admins) can call this, so return only
+    // the public fields. Full ExternalDomain rows include the Cloudflare
+    // DNS-challenge credentials (cloudflareApiEmail/cloudflareApiKey).
+    const externalDomains = (await site.getSortedExternalDomains()).map((d) => ({
+      id: d.id,
+      name: d.name,
+      siteId: d.siteId ?? null,
+    }));
     const nvidiaAvailable =
       (await Node.count({ where: { siteId: site.id, nvidiaAvailable: true } })) > 0;
     return ok(res, { siteId: site.id, externalDomains, nvidiaAvailable });
diff --git a/images/base/Dockerfile b/images/base/Dockerfile
index d0d7a97c..e463c9dc 100644
--- a/images/base/Dockerfile
+++ b/images/base/Dockerfile
@@ -17,8 +17,10 @@ COPY --from=builder /rootfs /
 # fetch a user's email from the internal LDAP server on first interactive login.
 # sssd-tools provides sss_ssh_authorizedkeys, used by sshd to serve users' SSH
 # public keys (stored on the LDAP sshPublicKey attribute).
+# build-essential (gcc, g++, make) lets npm/pip native modules compile in
+# every image built on base.
 RUN apt-get update && \
-    apt-get install -y sssd sssd-tools sudo tmux curl gnupg git jq ldap-utils unattended-upgrades locales && \
+    apt-get install -y sssd sssd-tools sudo tmux curl gnupg git jq ldap-utils unattended-upgrades locales build-essential && \
     echo 'en_US.UTF-8 UTF-8' >> /etc/locale.gen && \
     locale-gen && \
     update-locale LANG=en_US.UTF-8 && \
diff --git a/images/cloud/Dockerfile b/images/cloud/Dockerfile
new file mode 100644
index 00000000..c6557a50
--- /dev/null
+++ b/images/cloud/Dockerfile
@@ -0,0 +1,78 @@
+# syntax=docker/dockerfile:1
+# Converged app image for `mieweb deploy --target mieweb` (issue #475 §4.1).
+#
+# One container per app: the app plus the three datastores the @mieweb/cloud
+# `mieweb` target binds to, co-located and bound to 127.0.0.1:
+#
+#   minio.service    S3 (R2)           127.0.0.1:9000
+#   libsqld.service  libSQL (D1/Vec)   127.0.0.1:8080
+#   valkey.service   KV + Queues       127.0.0.1:6379
+#   app.service      the deployed app  0.0.0.0:$PORT  (After= the three above)
+#
+# Everything is a systemd unit (the base image boots /sbin/init). No
+# s6/supervisord. Datastore state lives on the persistent volume at /mnt/data
+# (#421), so it survives delete + recreate on the same hostname. Credentials
+# come from the container's environment at deploy time; the image bakes none.
+#
+# Built FROM the `nodejs` image (base + Node 24) because app.service runs a
+# Node app.
+
+# --- MinIO -------------------------------------------------------------------
+# MinIO no longer publishes community binaries or images (dl.min.io returns
+# 410; the Docker Hub/Quay images are gone), so build the pinned release from
+# source. MinIO is AGPL-3.0; it's shipped unmodified.
+FROM golang:1.24-trixie AS minio
+ARG MINIO_RELEASE=RELEASE.2025-10-15T17-29-55Z
+RUN git clone --depth 1 --branch "$MINIO_RELEASE" https://github.com/minio/minio.git /src
+WORKDIR /src
+RUN CGO_ENABLED=0 go build -tags kqueue -trimpath \
+      -ldflags "$(go run buildscripts/gen-ldflags.go)" \
+      -o /out/minio . && \
+    /out/minio --version
+
+# --- libSQL server (sqld) ----------------------------------------------------
+FROM debian:13 AS libsqld
+ARG LIBSQL_VERSION=0.24.32
+ARG LIBSQL_SHA256=71720fc8648c19efef416efebd47145ef59b62e198770533530a858e1336879f
+RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates xz-utils && \
+    curl -fsSL --retry 5 -o /tmp/sqld.tar.xz \
+      "https://github.com/tursodatabase/libsql/releases/download/libsql-server-v${LIBSQL_VERSION}/libsql-server-x86_64-unknown-linux-gnu.tar.xz" && \
+    echo "${LIBSQL_SHA256}  /tmp/sqld.tar.xz" | sha256sum -c - && \
+    tar -xJf /tmp/sqld.tar.xz -C /tmp && \
+    install -m 0755 /tmp/libsql-server-x86_64-unknown-linux-gnu/sqld /out-sqld
+
+# --- Final image -------------------------------------------------------------
+FROM nodejs
+
+# Valkey is packaged in Debian 13. Use our own valkey.service (bound to
+# loopback, data on /mnt/data) and disable the packaged unit.
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends valkey-server && \
+    systemctl disable valkey-server.service && \
+    systemctl mask valkey-server.service && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY --from=minio /out/minio /usr/local/bin/minio
+COPY --from=libsqld /out-sqld /usr/local/bin/sqld
+
+# Unprivileged service account that owns datastore state and runs the app.
+# The deploy provider streams the app into /opt/app/src over SSH (sudo tar).
+RUN useradd --system --home-dir /opt/app --shell /usr/sbin/nologin mieweb && \
+    install -d -o mieweb -g mieweb /opt/app /opt/app/src
+
+COPY --chmod=0755 mieweb-data-dir.sh /usr/local/bin/mieweb-data-dir
+COPY --chmod=0755 mieweb-app-start.sh /usr/local/bin/mieweb-app-start
+COPY minio.service libsqld.service valkey.service app.service /etc/systemd/system/
+# environment.service (from base) copies PID 1's environment, where the
+# Manager puts the container's env vars, into /etc/environment. The units read
+# that file, so enable it explicitly instead of relying on first-boot presets.
+RUN systemctl enable environment.service minio.service libsqld.service valkey.service app.service
+
+# The persistent volume (#421) mounts here; the directory also exists in the
+# image so the units still work (without persistence) if no volume is attached.
+RUN install -d /mnt/data
+
+# Default port for the app's HTTP service (read by the manager UI).
+LABEL org.mieweb.opensource-server.services.http.default-port=8787
+EXPOSE 8787
diff --git a/images/cloud/app.service b/images/cloud/app.service
new file mode 100644
index 00000000..0a476fd1
--- /dev/null
+++ b/images/cloud/app.service
@@ -0,0 +1,29 @@
+[Unit]
+Description=Deployed @mieweb/cloud app
+Wants=network-online.target minio.service libsqld.service valkey.service
+After=network-online.target environment.service minio.service libsqld.service valkey.service
+# Nothing to run until the first `mieweb deploy` has synced the code (the
+# provider restarts this unit after every sync).
+ConditionPathExists=/opt/app/src/package.json
+
+[Service]
+Type=simple
+User=mieweb
+Group=mieweb
+WorkingDirectory=/opt/app/src
+Environment=HOME=/opt/app
+# PORT, MIEWEB_APP_START and the datastore endpoints/credentials are set by
+# the deploy provider.
+EnvironmentFile=-/etc/environment
+# Install + build run as ExecStartPre so `systemctl restart` (which deploy
+# runs) blocks until they finish and fails if they fail. The app itself is
+# the main process.
+ExecStartPre=/usr/local/bin/mieweb-app-start prepare
+ExecStart=/usr/local/bin/mieweb-app-start run
+# npm install / build can be slow on a cold cache.
+TimeoutStartSec=30min
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
diff --git a/images/cloud/libsqld.service b/images/cloud/libsqld.service
new file mode 100644
index 00000000..5767a6dc
--- /dev/null
+++ b/images/cloud/libsqld.service
@@ -0,0 +1,16 @@
+[Unit]
+Description=libSQL server (D1 / Vectorize binding backend)
+After=network.target environment.service
+
+[Service]
+Type=simple
+User=mieweb
+Group=mieweb
+EnvironmentFile=-/etc/environment
+ExecStartPre=+/usr/local/bin/mieweb-data-dir libsql
+ExecStart=/usr/local/bin/sqld --no-welcome --db-path /mnt/data/libsql/data.sqld --http-listen-addr 127.0.0.1:8080
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=multi-user.target
diff --git a/images/cloud/mieweb-app-start.sh b/images/cloud/mieweb-app-start.sh
new file mode 100644
index 00000000..bdecf4f1
--- /dev/null
+++ b/images/cloud/mieweb-app-start.sh
@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# app.service helper.
+#   prepare  install dependencies (only when package.json or the lockfile
+#            changed) and run the `build` script if present (ExecStartPre)
+#   run      start the app (ExecStart)
+#
+# `mieweb deploy` copies the app's worktree into /opt/app/src over SSH and then
+# restarts this unit, waiting for `prepare` to finish. Environment (set by the
+# deploy provider):
+#   MIEWEB_APP_START  start command (default: `npm start`); must listen on $PORT
+#   PORT              HTTP port the app listens on (default 8787)
+set -euo pipefail
+
+APP_DIR=/opt/app/src
+DEPS_STAMP=/opt/app/.deps-stamp
+export PORT="${PORT:-8787}"
+cd "$APP_DIR"
+
+if [[ -f pnpm-lock.yaml ]]; then
+  install=(corepack pnpm install --frozen-lockfile); run=(corepack pnpm run)
+elif [[ -f yarn.lock ]]; then
+  install=(corepack yarn install --immutable); run=(corepack yarn run)
+elif [[ -f package-lock.json ]]; then
+  install=(npm ci); run=(npm run)
+else
+  install=(npm install); run=(npm run)
+fi
+
+case "${1:-}" in
+  prepare)
+    # (Missing lockfiles are expected; don't let `cat` fail the script.)
+    deps="$({ cat package.json pnpm-lock.yaml yarn.lock package-lock.json 2>/dev/null || true; } | sha256sum | cut -d' ' -f1)"
+    if [[ ! -d node_modules || "$(cat "$DEPS_STAMP" 2>/dev/null || true)" != "$deps" ]]; then
+      echo "Installing dependencies: ${install[*]}"
+      rm -f "$DEPS_STAMP"
+      "${install[@]}"
+      echo "$deps" >"$DEPS_STAMP"
+    fi
+    if [[ "$(npm pkg get scripts.build)" != "{}" ]]; then
+      echo "Building: ${run[*]} build"
+      "${run[@]}" build
+    fi
+    ;;
+  run)
+    echo "Starting app on port $PORT"
+    exec bash -c "${MIEWEB_APP_START:-npm start}"
+    ;;
+  *)
+    echo "usage: $0 prepare|run" >&2
+    exit 2
+    ;;
+esac
diff --git a/images/cloud/mieweb-data-dir.sh b/images/cloud/mieweb-data-dir.sh
new file mode 100644
index 00000000..cafc3523
--- /dev/null
+++ b/images/cloud/mieweb-data-dir.sh
@@ -0,0 +1,8 @@
+#!/bin/sh
+# Ensure /mnt/data/<name> exists and is owned by the service account.
+# Runs as root (ExecStartPre=+). The #421 volume at /mnt/data is chowned to the
+# container's root by the site agent, so the per-service subdirectory has to be
+# created and handed to `mieweb` here.
+set -eu
+dir="/mnt/data/$1"
+install -d -m 0750 -o mieweb -g mieweb "$dir"
diff --git a/images/cloud/minio.service b/images/cloud/minio.service
new file mode 100644
index 00000000..806597c6
--- /dev/null
+++ b/images/cloud/minio.service
@@ -0,0 +1,18 @@
+[Unit]
+Description=MinIO object storage (R2 binding backend)
+After=network.target environment.service
+
+[Service]
+Type=simple
+User=mieweb
+Group=mieweb
+# MINIO_ROOT_USER / MINIO_ROOT_PASSWORD are set by the deploy provider.
+EnvironmentFile=-/etc/environment
+ExecStartPre=+/usr/local/bin/mieweb-data-dir minio
+ExecStart=/usr/local/bin/minio server --quiet --address 127.0.0.1:9000 --console-address 127.0.0.1:9001 /mnt/data/minio
+Restart=always
+RestartSec=2
+LimitNOFILE=65536
+
+[Install]
+WantedBy=multi-user.target
diff --git a/images/cloud/valkey.service b/images/cloud/valkey.service
new file mode 100644
index 00000000..93bc5672
--- /dev/null
+++ b/images/cloud/valkey.service
@@ -0,0 +1,16 @@
+[Unit]
+Description=Valkey (KV / Queue binding backend)
+After=network.target environment.service
+
+[Service]
+Type=notify
+User=mieweb
+Group=mieweb
+EnvironmentFile=-/etc/environment
+ExecStartPre=+/usr/local/bin/mieweb-data-dir valkey
+ExecStart=/usr/bin/valkey-server --bind 127.0.0.1 --port 6379 --protected-mode yes --dir /mnt/data/valkey --appendonly yes --daemonize no --supervised systemd
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=multi-user.target
diff --git a/images/docker-bake.hcl b/images/docker-bake.hcl
index fc7bc549..70cbe27a 100644
--- a/images/docker-bake.hcl
+++ b/images/docker-bake.hcl
@@ -1,5 +1,5 @@
 group "default" {
-    targets = ["base", "nodejs", "docker", "docker-nodejs", "docs", "agent", "manager", "proxmox-ve"]
+    targets = ["base", "nodejs", "docker", "docker-nodejs", "cloud", "docs", "agent", "manager", "proxmox-ve"]
 }
 
 target "base" {
@@ -31,6 +31,15 @@ target "docker-nodejs" {
     }
 }
 
+# Converged app image for `mieweb deploy --target mieweb` (issue #475): the
+# NodeJS image plus MinIO, libSQL server and Valkey as systemd units.
+target "cloud" {
+    context = "./cloud"
+    contexts = {
+        nodejs = "target:nodejs"
+    }
+}
+
 # Builds the Debian packages consumed by the other images.
 target "builder" {
     context = "../"
diff --git a/mie-opensource-landing/docs/developers/docker-images.md b/mie-opensource-landing/docs/developers/docker-images.md
index f6077319..c2078ad4 100644
--- a/mie-opensource-landing/docs/developers/docker-images.md
+++ b/mie-opensource-landing/docs/developers/docker-images.md
@@ -12,7 +12,7 @@ OCI container images automatically built and published to GitHub Container Regis
 
 ### Debian 13 (`base`)
 
-Debian 13 with systemd (PID 1), SSSD for LDAP authentication, and PAM auto-homedir. Environment variables stored in `/etc/environment`.
+Debian 13 with systemd (PID 1), SSSD for LDAP authentication, PAM auto-homedir, and `build-essential` (gcc, g++, make) so native npm/pip modules can compile. Environment variables stored in `/etc/environment`.
 
 **Registry:** `ghcr.io/mieweb/opensource-server/base` · **Source:** [`images/base/`](https://github.com/mieweb/opensource-server/tree/main/images/base)
 
@@ -34,6 +34,12 @@ The same Dockerfile as `docker`, built on top of the `nodejs` image instead of t
 
 **Registry:** `ghcr.io/mieweb/opensource-server/docker-nodejs` · **Source:** [`images/docker/`](https://github.com/mieweb/opensource-server/tree/main/images/docker)
 
+### Converged app (`cloud`)
+
+Extends nodejs for `mieweb deploy --target mieweb` ([Deploying with the mieweb CLI](../users/mieweb-cli-deploy.md)). One container per app runs the app plus its datastores as systemd units, each bound to `127.0.0.1`: MinIO (`:9000`, R2), libSQL server `sqld` (`:8080`, D1/Vectorize), and Valkey (`:6379`, KV/Queues). Their data lives under the persistent `/mnt/data` [volume](../admins/core-concepts/volumes.md). `mieweb deploy` syncs the app's worktree into `/opt/app/src` over the container's SSH port and restarts `app.service`, which installs dependencies (only when `package.json` or the lockfile changed), runs the `build` script if present, and starts `MIEWEB_APP_START` (default `npm start`) on `$PORT`. Until the first sync, `app.service` is skipped. MinIO is built from source at a pinned release (MinIO no longer publishes binaries), and `sqld` is a checksum-verified release download.
+
+**Registry:** `ghcr.io/mieweb/opensource-server/cloud` · **Source:** [`images/cloud/`](https://github.com/mieweb/opensource-server/tree/main/images/cloud)
+
 ### Agent (`agent`)
 
 Extends nodejs with the `opensource-agent` package (check-in agent, nginx, dnsmasq) and [acme.sh](https://github.com/acmesh-official/acme.sh) for ACME certificate management. Used as the networking layer for each site — handles reverse proxy, DNS, and TLS. See [Deploying Agents](../admins/deploying-agents.md).
@@ -61,6 +67,8 @@ images/
 │   └── ldapusers
 ├── nodejs/
 │   └── Dockerfile           # Extends base image
+├── cloud/
+│   └── Dockerfile           # Extends nodejs (MinIO + sqld + Valkey + app units)
 ├── builder/
 │   └── Dockerfile           # Builds the .deb packages (artifact-only image)
 ├── docs/
diff --git a/mie-opensource-landing/docs/users/mieweb-cli-deploy.md b/mie-opensource-landing/docs/users/mieweb-cli-deploy.md
new file mode 100644
index 00000000..bb609c99
--- /dev/null
+++ b/mie-opensource-landing/docs/users/mieweb-cli-deploy.md
@@ -0,0 +1,121 @@
+# Deploying with the mieweb CLI
+
+`mieweb deploy --target mieweb` deploys a [`@mieweb/cloud`](https://github.com/mieweb/cloud) app (a Cloudflare-Workers-style app described by `wrangler.jsonc`) to an opensource-server site such as os.mieweb.org. The CLI drives the [`@mieweb/os-cloud-provider`](https://github.com/mieweb/opensource-server/tree/main/packages/os-cloud-provider) package, which creates or updates one container per app through the Manager API.
+
+## What gets deployed
+
+Each app gets **one container** on the site, named after `wrangler.jsonc` `name` (it must be a valid DNS label). The container runs the [`cloud` image](../developers/docker-images.md#converged-app-cloud):
+
+- your app, copied from your local worktree and started with `npm start` on `$PORT` (default `8787`)
+- MinIO, libSQL (`sqld`) and Valkey on `127.0.0.1`, backing the R2, D1/Vectorize and KV/Queue bindings
+- a persistent read-write [volume](../admins/core-concepts/volumes.md) at `/mnt/data` for all datastore state
+
+The app is exposed through one HTTP service at `https://<name>.<domain>`; the site's nginx terminates TLS in front of it. The container also publishes SSH (port 22) on a site port, which `deploy` uses to copy your code.
+
+### What `deploy` does
+
+1. **Converge the container** through the Manager API. The first deploy creates it and waits for it to be provisioned. Later deploys change the container only when its configuration differs (services, environment variables, the data volume); otherwise this step makes no changes. If the image (or the GPU requirement) changes, the container is deleted and recreated. `/mnt/data` is kept across that recreate, so datastore contents survive.
+2. **Wait for SSH** (retrying for up to 60 s while a new or rebuilt container finishes booting), then **sync your worktree** into `/opt/app/src` in the container (rsync-style: only changed files are sent):
+   - Files are sent exactly as they are on disk. Whether a file is committed, staged, or untracked doesn't matter.
+   - `.gitignore` rules are honored (including nested `.gitignore` files) and `.git/` is skipped. `.git/info/exclude` and your global git excludes are **not** applied.
+   - Files you deleted locally are deleted in the container. Ignored paths in the container, such as `node_modules` and build output, are left alone.
+3. **Restart the app** over the same SSH connection and **wait for it**. Dependencies are installed if `package.json` or the lockfile changed, then the `build` script runs if there is one, and their output is shown as it happens. Then the start command runs. `deploy` fails, showing the app's recent logs, if the install or build fails, or if the app stops within 5 seconds of starting.
+
+So a code-only redeploy is just a file sync and a restart.
+
+### SSH credentials
+
+The sync uses a built-in SSH client, so you don't need `ssh` or `rsync` installed. It logs in as your Manager username (override with `targets.mieweb.sshUser` or `MIEWEB_OS_SSH_USER`) and tries your local credentials in this order:
+
+1. your ssh-agent (`SSH_AUTH_SOCK`, or Pageant on Windows)
+2. `~/.ssh/id_ed25519`, `id_ecdsa` and `id_rsa`, asking for the passphrase if a key is encrypted
+3. your password, asked for in the terminal
+
+Keys work when the public key is on your account. The whole sync uses one connection, so you're asked for a password at most once. With no terminal (e.g. in CI), password login is skipped and deploy fails with a hint unless a key or agent works.
+
+The container's host key is trusted on first connection and pinned in `~/.mieweb/known_hosts`. A changed key is an error, except that the pin is cleared when `deploy` itself recreates the container.
+
+## Setup
+
+Install the provider in your app:
+
+```sh
+pnpm add -D @mieweb/os-cloud-provider
+```
+
+Point the `mieweb` target at it in `mieweb.jsonc`:
+
+```jsonc
+{
+  "targets": {
+    "mieweb": {
+      "provider": "@mieweb/os-cloud-provider",
+      "siteId": 1,                              // required: the Manager site to deploy into
+      "instanceUrl": "https://os.mieweb.org",   // optional (default)
+      // Everything below is optional.
+      "image": "ghcr.io/mieweb/opensource-server/cloud:latest", // e.g. a :<branch>/:sha-<sha> tag to test
+      "port": 8787,                  // port the app listens on ($PORT)
+      "domain": "os.mieweb.org",     // external domain (name or id); default: the site's first
+      "externalHostname": "my-app",  // default: wrangler.jsonc `name`
+      "authRequired": false,         // put the site's auth proxy in front of the app
+      "start": "npm start",          // start command inside the container
+      "sshUser": "alice",            // default: your Manager username
+      "sshHost": "203.0.113.10",     // default: the container's published SSH host
+      "sync": true,                  // false: converge the container only, don't copy code
+      "services": [{ "type": "tcp", "internalPort": 22 }] // extra tcp/udp/srv services
+    }
+  }
+}
+```
+
+`mieweb.jsonc` holds **no secrets**.
+
+## Authentication
+
+Either set a token in the environment (CI):
+
+```sh
+export MIEWEB_OS_TOKEN=<API key>          # create one under API Keys in the web UI
+export MIEWEB_OS_URL=https://os.mieweb.org # optional; overrides instanceUrl
+mieweb deploy --target mieweb
+```
+
+or log in interactively:
+
+```sh
+mieweb login --target mieweb [--instance https://os.mieweb.org]
+```
+
+`login` opens your browser to the Manager. After you sign in and confirm, the Manager creates an API key and hands it back to the CLI through a one-time listener on `127.0.0.1`. The key is stored in `~/.mieweb/os.json` (mode `0600`), keyed by instance, so you can stay logged in to several instances at once. `mieweb logout --target mieweb` revokes the key and removes it from that file. `mieweb whoami --target mieweb` shows who you are signed in as.
+
+`MIEWEB_OS_TOKEN` always takes precedence over the stored login.
+
+## Environment variables in the container
+
+The container's environment is replaced on every deploy with:
+
+| Source | Variables |
+| --- | --- |
+| `wrangler.jsonc` `vars` | as declared (non-string values are JSON-encoded) |
+| `MIEWEB_OS_SECRET_<NAME>` in the deploying shell | `<NAME>` (for secrets, e.g. `MIEWEB_OS_SECRET_API_KEY` → `API_KEY`) |
+| Provider-managed | `PORT`, `MIEWEB_TARGET`, `MIEWEB_APP_START`, `MINIO_ROOT_USER`, `MINIO_ROOT_PASSWORD`, `MIEWEB_S3_ENDPOINT`, `MIEWEB_S3_ACCESS_KEY_ID`, `MIEWEB_S3_SECRET_ACCESS_KEY`, `MIEWEB_LIBSQL_URL`, `MIEWEB_VALKEY_URL` |
+
+The MinIO password is generated on the first deploy and reused after that. Variables added to the container through the web UI are removed on the next deploy.
+
+## Other commands
+
+| Command | Behavior |
+| --- | --- |
+| `mieweb destroy --target mieweb` | Deletes the container. The `/mnt/data` directory is retained on the node and reattached if you deploy the same name again. |
+| `mieweb dev --target mieweb` | Not provided by this provider (there's no remote dev mode). Use the local host harness. |
+| `mieweb tail --target mieweb` | Streams the app's logs (`journalctl -u app.service`) over the same SSH connection deploy uses, so the same credentials apply. Shows the last 100 lines and keeps following until Ctrl-C. Options: `-n`/`--lines N`, `--no-follow`, and `--since <time>` (e.g. `-1h`, `"2026-10-01 12:00"`). |
+
+## Testing against a local Manager
+
+`make dev` runs the Manager at `http://localhost:3000` on SQLite with a simulated hypervisor and a seeded `localhost` site (id `1`). Create an API key in its UI, then:
+
+```sh
+MIEWEB_OS_URL=http://localhost:3000 MIEWEB_OS_TOKEN=<key> mieweb deploy --target mieweb
+```
+
+The simulated hypervisor has no real SSH endpoint, so set `"sync": false` for this loop. The provider's live test suite (`pnpm test:live` in `packages/os-cloud-provider`) runs the same loop.
diff --git a/mie-opensource-landing/zensical.toml b/mie-opensource-landing/zensical.toml
index 6461d144..33100bf8 100644
--- a/mie-opensource-landing/zensical.toml
+++ b/mie-opensource-landing/zensical.toml
@@ -28,6 +28,7 @@ nav = [
       ] },
       { "VS Code Setup" = "users/vscode-setup.md" },
       { "MCP Server" = "users/mcp-server.md" },
+      { "Deploying with the mieweb CLI" = "users/mieweb-cli-deploy.md" },
     ] },
     { "Admins" = [
       { "Overview" = "admins/index.md" },
diff --git a/packages/os-cloud-provider/.gitignore b/packages/os-cloud-provider/.gitignore
new file mode 100644
index 00000000..b9470778
--- /dev/null
+++ b/packages/os-cloud-provider/.gitignore
@@ -0,0 +1,2 @@
+node_modules/
+dist/
diff --git a/packages/os-cloud-provider/.npmrc b/packages/os-cloud-provider/.npmrc
new file mode 100644
index 00000000..8c7deef7
--- /dev/null
+++ b/packages/os-cloud-provider/.npmrc
@@ -0,0 +1,3 @@
+# Preview: @mieweb/* resolve from GitHub Packages while cross-repo PRs are in review.
+# Remove once @mieweb/deploy-contract is released to npmjs.
+@mieweb:registry=https://npm.pkg.github.com
diff --git a/packages/os-cloud-provider/README.md b/packages/os-cloud-provider/README.md
new file mode 100644
index 00000000..e6f9a058
--- /dev/null
+++ b/packages/os-cloud-provider/README.md
@@ -0,0 +1,54 @@
+# `@mieweb/os-cloud-provider`
+
+The opensource-server (os.mieweb.org) implementation of the
+[`@mieweb/deploy-contract`](https://github.com/mieweb/cloud/tree/main/packages/deploy-contract)
+`DeployProvider`. With it, `mieweb deploy --target mieweb` creates or updates
+one container per app through the Manager API.
+
+User documentation: [Deploying with the mieweb CLI](../../mie-opensource-landing/docs/users/mieweb-cli-deploy.md).
+Example config: [`examples/mieweb.jsonc`](examples/mieweb.jsonc).
+
+| Verb | Manager operations |
+| --- | --- |
+| `deploy` | `list_containers?hostname=` → `create_container` (409 → retry as update) \| `update_container` (only when config differs) \| `delete_container`+`create_container` when the image or GPU requirement changes; poll `get_job`; `get_container` for the URL, VMID and SSH port; then wait for SSH and sync the worktree (honoring `.gitignore`) into `/opt/app/src` and restart `app.service` over SSH |
+| `destroy` | `delete_container` (the `/mnt/data` volume is retained) |
+| `whoami` | `get_session` |
+| `login` / `logout` | `/api/v1/auth/cli/callback` loopback handoff / `delete_api_key` |
+| `tail` | `get_container` for the SSH port, then `sudo journalctl -u app.service -f` over SSH (`-n/--lines N`, `--no-follow`, `--since <time>`) |
+| `dev` | not implemented (there's no remote dev mode) |
+
+`DeployResult.resources` holds one `{ kind: 'container', binding: <name>, id: <VMID> }`.
+
+## Development
+
+Node ≥ 22.18 runs the TypeScript sources directly (type stripping), so there's
+no build step during development. The source uses only erasable syntax, and
+relative imports end in `.ts`.
+
+```sh
+pnpm install
+pnpm test          # unit + contract conformance against an in-process fake Manager
+pnpm typecheck
+pnpm build         # tsc → dist/ (ESM .js + .d.ts), run automatically on pack/publish
+pnpm gen:types     # regenerate src/generated/manager-api.ts from the Manager's OpenAPI spec
+```
+
+The code sync is pure JavaScript. It uses [`ssh2`](https://www.npmjs.com/package/ssh2) for SSH, [`ignore`](https://www.npmjs.com/package/ignore) for `.gitignore` rules, and [`tar-stream`](https://www.npmjs.com/package/tar-stream) for the upload, so no local `ssh` or `rsync` is needed. Authentication tries ssh-agent, then `~/.ssh/id_{ed25519,ecdsa,rsa}` (prompting for a passphrase if the key is encrypted), then keyboard-interactive or password prompts. `src/sync.ts` diffs the files by size and mtime, streams the changed ones as a tar into `sudo tar -x`, deletes removed files, and restarts the app. Tests drive it against an in-process `ssh2` server (`test/ssh.test.ts`) and a fake remote shell backed by a directory (`test/sync.test.ts`).
+
+Live test against a real Manager (the code sync is disabled there, since DummyApi containers have no SSH) (`make dev` at the repo root: SQLite plus the
+DummyApi hypervisor):
+
+```sh
+MIEWEB_OS_LIVE=1 MIEWEB_OS_URL=http://localhost:3000 MIEWEB_OS_TOKEN=<key> \
+  MIEWEB_OS_SITE_ID=1 pnpm test:live
+```
+
+For a full end-to-end run on real Proxmox (the top-level `compose.yml` stack),
+build `images/cloud` locally and stage it into the Proxmox template cache with
+the stack's existing local-first skopeo pattern
+(`skopeo copy docker-daemon:<image> … || skopeo copy docker://<image> …`). Then
+set `targets.mieweb.image` to that reference and deploy. That run needs a
+privileged host, so keep it behind a CI gate.
+
+`@mieweb/deploy-contract` is not published to npm yet. It's a regular dependency installed with pnpm's subdirectory git syntax, pinned to a commit of mieweb/cloud#14:
+`github:mieweb/cloud#<sha>&path:/packages/deploy-contract`. Install the provider with pnpm, because npm can't resolve that specifier. Once the contract is published, switch it to a semver range (`^0.2.1`).
diff --git a/packages/os-cloud-provider/examples/mieweb.jsonc b/packages/os-cloud-provider/examples/mieweb.jsonc
new file mode 100644
index 00000000..5a03b74d
--- /dev/null
+++ b/packages/os-cloud-provider/examples/mieweb.jsonc
@@ -0,0 +1,36 @@
+// Example mieweb.jsonc for deploying a @mieweb/cloud app to opensource-server
+// (os.mieweb.org) with `mieweb deploy --target mieweb`.
+//
+// Non-secret configuration only. Credentials come from the environment:
+//   MIEWEB_OS_TOKEN        API key (or run `mieweb login --target mieweb`)
+//   MIEWEB_OS_URL          Manager URL; overrides targets.mieweb.instanceUrl
+//   MIEWEB_OS_SITE_ID      Manager site; overrides targets.mieweb.siteId
+//   MIEWEB_OS_SECRET_<NAME> injected into the container as <NAME>
+//   MIEWEB_OS_SSH_USER     SSH login for the code sync (default: your Manager username)
+//
+// Each deploy syncs this worktree (minus .gitignore'd files) into the
+// container over its SSH port using your own SSH keys/agent or password.
+{
+  "target": "mieweb",
+  "targets": {
+    "mieweb": {
+      "provider": "@mieweb/os-cloud-provider",
+      // Optional: without it deploy uses your only site, or asks which one, and
+      // saves the choice here.
+      "siteId": 1,
+      "instanceUrl": "https://os.mieweb.org",
+      // Optional; defaults shown.
+      "image": "ghcr.io/mieweb/opensource-server/cloud:latest",
+      "port": 8787,
+      "authRequired": false,
+
+      // The app's bindings, served by the datastores inside the container.
+      "runtime": "node",
+      "bindings": {
+        "DB": { "driver": "libsql", "url": "http://127.0.0.1:8080" },
+        "FILES": { "driver": "s3", "endpoint": "http://127.0.0.1:9000", "bucket": "files", "forcePathStyle": true },
+        "CACHE": { "driver": "valkey", "host": "127.0.0.1", "port": 6379 }
+      }
+    }
+  }
+}
diff --git a/packages/os-cloud-provider/package.json b/packages/os-cloud-provider/package.json
new file mode 100644
index 00000000..775f8de9
--- /dev/null
+++ b/packages/os-cloud-provider/package.json
@@ -0,0 +1,52 @@
+{
+  "name": "@mieweb/os-cloud-provider",
+  "version": "0.1.0",
+  "packageManager": "pnpm@12.8.1",
+  "description": "DeployProvider (@mieweb/deploy-contract) for opensource-server / os.mieweb.org: `mieweb deploy --target mieweb` converges one container per app through the Manager API.",
+  "type": "module",
+  "license": "MIT",
+  "author": "MIEWEB",
+  "homepage": "https://github.com/mieweb/opensource-server/tree/main/packages/os-cloud-provider#readme",
+  "bugs": "https://github.com/mieweb/opensource-server/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mieweb/opensource-server.git",
+    "directory": "packages/os-cloud-provider"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test 'test/**/*.test.ts'",
+    "test:live": "MIEWEB_OS_LIVE=1 node --test test/live.test.ts",
+    "prepack": "pnpm run build",
+    "gen:types": "openapi-typescript ../../create-a-container/openapi.v1.yaml -o src/generated/manager-api.ts"
+  },
+  "dependencies": {
+    "@mieweb/deploy-contract": "0.2.1-pr14.5",
+    "ignore": "^7.0.10",
+    "ssh2": "^1.17.0",
+    "tar-stream": "^3.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.19.0",
+    "@types/ssh2": "^1.15.6",
+    "@types/tar-stream": "^3.1.5",
+    "openapi-typescript": "^7.13.0",
+    "typescript": "^5.9.3"
+  }
+}
diff --git a/packages/os-cloud-provider/pnpm-lock.yaml b/packages/os-cloud-provider/pnpm-lock.yaml
new file mode 100644
index 00000000..236849f7
--- /dev/null
+++ b/packages/os-cloud-provider/pnpm-lock.yaml
@@ -0,0 +1,683 @@
+---
+lockfileVersion: '9.0'
+
+importers:
+
+  .:
+    configDependencies: {}
+    packageManagerDependencies:
+      pnpm:
+        specifier: 12.8.1
+        version: 12.8.1
+
+packages:
+
+  '@pnpm/exe.android-arm64@12.8.1':
+    resolution: {integrity: sha512-siDxcidfz5eM6L2tJfik+i2bbUEw8UC7MZ3Yl2HYdRmqbdhHGAOQACtOOu6QVW4Jul4/w5wVKm+wM8ACtgh1Pg==}
+    cpu: [arm64]
+    os: [android]
+
+  '@pnpm/exe.android-x64@12.8.1':
+    resolution: {integrity: sha512-0F/uqPRc3aN4vLHsa0f+6fTtmsigFQ9/yxEU43fionF//pNHEd5e97b3w/nKIgqYMCUQCJphmBRMA9Q8/wlo9Q==}
+    cpu: [x64]
+    os: [android]
+
+  '@pnpm/exe.darwin-arm64@12.8.1':
+    resolution: {integrity: sha512-/rwavvMQJsl2RIxOHBnDF+4Gk+fhQFAY4M3PQZoKskJOEnaJcygG9p1xby6wcQcbS4d9dIubv09CQhufTgfmpw==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@pnpm/exe.darwin-x64@12.8.1':
+    resolution: {integrity: sha512-htYt2gN7zqJKLhC99Ft6EUiO7myjZAZXfmGCTJUL1v+o7vE9hZdE1+fAkk4Oj1ZHNRti6b2woOxEkRkAusi8OQ==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@pnpm/exe.freebsd-x64@12.8.1':
+    resolution: {integrity: sha512-PB5BULNgytxvExoOXUUeseS/DcpPENs+cg3iA6xHHeaLT4ctEGKSGXEbuj7USeqvo8JBpAx039hivnbzGqDwnA==}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@pnpm/exe.linux-arm64-musl@12.8.1':
+    resolution: {integrity: sha512-kKeyC/ArjrgdciQRBrOL0j9HtOI4gDRgoyP+eJ1CQKyadpKlf/DhDDyspXe07R3B9KagTVLUF2nlt6Dr5quFIg==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@pnpm/exe.linux-arm64@12.8.1':
+    resolution: {integrity: sha512-q4s9a9X2O3N9aeUFooW24orNrxvu20+jyVUFR5RanPCqOKKPBrgs2iywMkBBx1aXkkzdWT54/mfz8Be8sJlWEw==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@pnpm/exe.linux-ppc64@12.8.1':
+    resolution: {integrity: sha512-F7XSjKJthwCh/L6abZiMpAfo2Cm61SZIT3e4dfgiIjESndlWaXCnfLKngSgZ/SEMsdmHT6dud3+kWIB3tw0/xQ==}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@pnpm/exe.linux-riscv64@12.8.1':
+    resolution: {integrity: sha512-z1ecpIK/ZY08Unk69KWWE9867oaKUytGUjrHnBoGFAAhsK+q+0cfvBH+f5fWobJ7FX97leMlLO+gkJolddM45Q==}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [glibc]
+
+  '@pnpm/exe.linux-s390x@12.8.1':
+    resolution: {integrity: sha512-KU6tnrBfu4uKXTq6N5qJwSm8FSrs9Wc8b5AUEsHK9bRXwNdsZ1/lRxG1++X29SKRW9OSNuDSjxASv5mAvGo1gA==}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@pnpm/exe.linux-x64-musl@12.8.1':
+    resolution: {integrity: sha512-eUE8BWJkDr2tJb/yrk0yVnszlmNqFarVxUlqiZ9BAkct28Nq/5g2H0tvMDmPA7fAQW3STNj+omJPPRVT+4s5sQ==}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@pnpm/exe.linux-x64@12.8.1':
+    resolution: {integrity: sha512-8bDZ0lZlCdi2rvnFul7EYgcC7zKeWSe76y8JV2oXobaS8p9i9d6PSf6LgLtTM0fI7R9Oh4eLCbveXyNDMmvZ+g==}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@pnpm/exe.win32-arm64@12.8.1':
+    resolution: {integrity: sha512-MsT0dlrRxnCRCHCaosNbhWpEiAFnFuMEu3KuDJDU41BXgTwiINxU8goloUSUDejWZUqKaUqNC/qUTihl9nFtqg==}
+    cpu: [arm64]
+    os: [win32]
+
+  '@pnpm/exe.win32-x64@12.8.1':
+    resolution: {integrity: sha512-SWtPe0PsbTTk//gJND10tMdOfCYjrkq5+qV49hzVhY7xz2iJ339Rc+xwASlcvbwTfrvH39YNqpKYibD+CRGLwA==}
+    cpu: [x64]
+    os: [win32]
+
+  pnpm@12.8.1:
+    resolution: {integrity: sha512-9kupB1B/XOr+BsjTjmBS0BeURFgOwSed3Vv8EctIqoomRLZlmOB+dh2oSHKp/FfV+QK4f6SdAkGY1VhhKqu+RQ==}
+    engines: {node: '>=18.*'}
+    hasBin: true
+
+snapshots:
+
+  '@pnpm/exe.android-arm64@12.8.1':
+    optional: true
+
+  '@pnpm/exe.android-x64@12.8.1':
+    optional: true
+
+  '@pnpm/exe.darwin-arm64@12.8.1':
+    optional: true
+
+  '@pnpm/exe.darwin-x64@12.8.1':
+    optional: true
+
+  '@pnpm/exe.freebsd-x64@12.8.1':
+    optional: true
+
+  '@pnpm/exe.linux-arm64-musl@12.8.1':
+    optional: true
+
+  '@pnpm/exe.linux-arm64@12.8.1':
+    optional: true
+
+  '@pnpm/exe.linux-ppc64@12.8.1':
+    optional: true
+
+  '@pnpm/exe.linux-riscv64@12.8.1':
+    optional: true
+
+  '@pnpm/exe.linux-s390x@12.8.1':
+    optional: true
+
+  '@pnpm/exe.linux-x64-musl@12.8.1':
+    optional: true
+
+  '@pnpm/exe.linux-x64@12.8.1':
+    optional: true
+
+  '@pnpm/exe.win32-arm64@12.8.1':
+    optional: true
+
+  '@pnpm/exe.win32-x64@12.8.1':
+    optional: true
+
+  pnpm@12.8.1:
+    optionalDependencies:
+      '@pnpm/exe.android-arm64': 12.8.1
+      '@pnpm/exe.android-x64': 12.8.1
+      '@pnpm/exe.darwin-arm64': 12.8.1
+      '@pnpm/exe.darwin-x64': 12.8.1
+      '@pnpm/exe.freebsd-x64': 12.8.1
+      '@pnpm/exe.linux-arm64': 12.8.1
+      '@pnpm/exe.linux-arm64-musl': 12.8.1
+      '@pnpm/exe.linux-ppc64': 12.8.1
+      '@pnpm/exe.linux-riscv64': 12.8.1
+      '@pnpm/exe.linux-s390x': 12.8.1
+      '@pnpm/exe.linux-x64': 12.8.1
+      '@pnpm/exe.linux-x64-musl': 12.8.1
+      '@pnpm/exe.win32-arm64': 12.8.1
+      '@pnpm/exe.win32-x64': 12.8.1
+
+---
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      '@mieweb/deploy-contract':
+        specifier: 0.2.1-pr14.5
+        version: 0.2.1-pr14.5
+      ignore:
+        specifier: ^7.0.10
+        version: 7.0.10
+      ssh2:
+        specifier: ^1.17.0
+        version: 1.17.0
+      tar-stream:
+        specifier: ^3.2.1
+        version: 3.2.1
+    devDependencies:
+      '@types/node':
+        specifier: ^24.19.0
+        version: 24.19.0
+      '@types/ssh2':
+        specifier: ^1.15.6
+        version: 1.15.6
+      '@types/tar-stream':
+        specifier: ^3.1.5
+        version: 3.1.5
+      openapi-typescript:
+        specifier: ^7.13.0
+        version: 7.13.0(typescript@5.9.3)
+      typescript:
+        specifier: ^5.9.3
+        version: 5.9.3
+
+packages:
+
+  '@babel/code-frame@7.29.7':
+    resolution: {integrity: sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-validator-identifier@7.29.7':
+    resolution: {integrity: sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==}
+    engines: {node: '>=6.9.0'}
+
+  '@mieweb/deploy-contract@0.2.1-pr14.5':
+    resolution: {integrity: sha512-OgTpvGm8iUp0JKjsr1k9kIVsjSMzmJbr5VXNA+QNDXen6ItKOhR9fe/D2T9SzrFyO/0+qbLenz5yT0CUAr9AEA==, tarball: https://npm.pkg.github.com/download/@mieweb/deploy-contract/0.2.1-pr14.5/18d12fabb58f4b7350f4b0065ed3fd46f716d6fc}
+
+  '@redocly/ajv@8.11.2':
+    resolution: {integrity: sha512-io1JpnwtIcvojV7QKDUSIuMN/ikdOUd1ReEnUnMKGfDVridQZ31J0MmIuqwuRjWDZfmvr+Q0MqCcfHM2gTivOg==}
+
+  '@redocly/config@0.22.0':
+    resolution: {integrity: sha512-gAy93Ddo01Z3bHuVdPWfCwzgfaYgMdaZPcfL7JZ7hWJoK9V0lXDbigTWkhiPFAaLWzbOJ+kbUQG1+XwIm0KRGQ==}
+
+  '@redocly/openapi-core@1.34.20':
+    resolution: {integrity: sha512-ypeBZ/6BKXR9+7/TtbKhbl4UgD7raHhPS12oknlKno2A8+lnFkxIwiE/Aklu6L2cd/ioH+fCWuMxi9/p3EyAPw==}
+    engines: {node: '>=18.17.0', npm: '>=9.5.0'}
+
+  '@types/node@18.19.130':
+    resolution: {integrity: sha512-GRaXQx6jGfL8sKfaIDD6OupbIHBr9jv7Jnaml9tB7l4v068PAOXqfcujMMo5PhbIs6ggR1XODELqahT2R8v0fg==}
+
+  '@types/node@24.19.0':
+    resolution: {integrity: sha512-zY+5tKxXdhGh1PYI0ac+7juvEu4OI6vWtVVoj5i2m42jxAY1U+zHGt6QCyOFwykdP62sM3MJ9stoYYUw5aCWew==}
+
+  '@types/ssh2@1.15.6':
+    resolution: {integrity: sha512-oGdxhBqcRTwSTKFm+9EiKzkNVYRLEFkcW44lhguvBalGJbWfGnDt/ezwSUZc+SF9m9bMc3VyklNAtp7zICjS5w==}
+
+  '@types/tar-stream@3.1.5':
+    resolution: {integrity: sha512-zCUA6CSDw0t2cpQiZixpyzfubpeuVZmBr5wztvuCG4bhy7reX/9wGXdZxEzz2CjMFLQ32UPR/01jzUUSRJeCeQ==}
+
+  agent-base@7.1.4:
+    resolution: {integrity: sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==}
+    engines: {node: '>= 14'}
+
+  ansi-colors@4.1.3:
+    resolution: {integrity: sha512-/6w/C21Pm1A7aZitlI5Ni/2J6FFQN8i1Cvz3kHABAAbw93v/NlvKdVOqz7CCWz/3iv/JplRSEEZ83XION15ovw==}
+    engines: {node: '>=6'}
+
+  argparse@2.0.1:
+    resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==}
+
+  asn1@0.2.6:
+    resolution: {integrity: sha512-ix/FxPn0MDjeyJ7i/yoHGFt/EX6LyNbxSEhPPXODPL+KB0VPk86UYfL0lMdy+KCnv+fmvIzySwaK5COwqVbWTQ==}
+
+  b4a@1.9.0:
+    resolution: {integrity: sha512-dpfcF9fDNR6++cthXR67iyhgqWy9CBouAvIWhIntzBG6cvK/cnIPiZQjBwi/ZqjjBEDGfoNDtmB0kTjroOJ3pQ==}
+    peerDependencies:
+      react-native-b4a: '*'
+    peerDependenciesMeta:
+      react-native-b4a:
+        optional: true
+
+  balanced-match@1.0.2:
+    resolution: {integrity: sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==}
+
+  bare-events@2.9.2:
+    resolution: {integrity: sha512-AIPKioV7/Y/8KfZ3AAhjPJxLLbY49S64Ym5DakZlUg75qQiTgUq9hEJoEwa4eUezPUlXRy/i5NpsKvo9jgKmoA==}
+    peerDependencies:
+      bare-abort-controller: '*'
+    peerDependenciesMeta:
+      bare-abort-controller:
+        optional: true
+
+  bare-fs@4.8.2:
+    resolution: {integrity: sha512-+ZI68KHMUvosXfKbg/UOHK0tbCdRnegbvPEdEcZ3Nd6TetieQsJPRXBRXPdLyy8+3VSEbPXtsumTpEtt78xv9w==}
+    engines: {bare: '>=1.28.0'}
+    peerDependencies:
+      bare-buffer: '*'
+    peerDependenciesMeta:
+      bare-buffer:
+        optional: true
+
+  bare-path@3.1.2:
+    resolution: {integrity: sha512-ZyKbsuuqK6Ag0K8pX6V5Txq6XeJRvY+wXucnFGRjiyVYP9YWDpIQugk/b+enRYrEYBJaqLzghRQpXPMR7341Nw==}
+
+  bare-stream@2.13.4:
+    resolution: {integrity: sha512-PcrQ8lVLbiJscNm1Kez+Yp4Gy4AHGcN1lzwjvf5NybWen7VvEgUfyfnXYJ2zNqWnzOfCb1Abq6lH8ti0syQszA==}
+    peerDependencies:
+      bare-abort-controller: '*'
+      bare-buffer: '*'
+      bare-events: '*'
+    peerDependenciesMeta:
+      bare-abort-controller:
+        optional: true
+      bare-buffer:
+        optional: true
+      bare-events:
+        optional: true
+
+  bare-url@2.5.4:
+    resolution: {integrity: sha512-Gxa7UVWBr0/edU1b+TJhn/AZvMQUj9OGspvYsaTYQrAbZA4BOTZGL3LiZxvD+CeMlDH4juwD84+eTAp/bLYW5g==}
+
+  bcrypt-pbkdf@1.0.2:
+    resolution: {integrity: sha512-qeFIXtP4MSoi6NLqO12WfqARWWuCKi2Rn/9hJLEmtB5yTNr9DqFWkJRCf2qShWzPeAMRnOgCrq0sg/KLv5ES9w==}
+
+  brace-expansion@2.1.7:
+    resolution: {integrity: sha512-uZbew1NqdmPDTMJ8ah1y+b+9QEJrfkXFk3RcTQw3X0jW/xRUvFKsg1CfQdSYGdTbXZWExtU3J3ccxtnfw1Fi0g==}
+
+  buildcheck@0.0.7:
+    resolution: {integrity: sha512-lHblz4ahamxpTmnsk+MNTRWsjYKv965MwOrSJyeD588rR3Jcu7swE+0wN5F+PbL5cjgu/9ObkhfzEPuofEMwLA==}
+    engines: {node: '>=10.0.0'}
+
+  change-case@5.4.4:
+    resolution: {integrity: sha512-HRQyTk2/YPEkt9TnUPbOpr64Uw3KOicFWPVBb+xiHvd6eBx/qPr9xqfBFDT8P2vWsvvz4jbEkfDe71W3VyNu2w==}
+
+  colorette@1.4.0:
+    resolution: {integrity: sha512-Y2oEozpomLn7Q3HFP7dpww7AtMJplbM9lGZP6RDfHqmbeRjiwRg4n6VM6j4KLmRke85uWEI7JqF17f3pqdRA0g==}
+
+  cpu-features@0.0.10:
+    resolution: {integrity: sha512-9IkYqtX3YHPCzoVg1Py+o9057a3i0fp7S530UWokCSaFVTc7CwXPRiOjRjBQQ18ZCNafx78YfnG+HALxtVmOGA==}
+    engines: {node: '>=10.0.0'}
+
+  debug@4.4.3:
+    resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==}
+    engines: {node: '>=6.0'}
+    peerDependencies:
+      supports-color: '*'
+    peerDependenciesMeta:
+      supports-color:
+        optional: true
+
+  events-universal@1.0.1:
+    resolution: {integrity: sha512-LUd5euvbMLpwOF8m6ivPCbhQeSiYVNb8Vs0fQ8QjXo0JTkEHpz8pxdQf0gStltaPpw0Cca8b39KxvK9cfKRiAw==}
+
+  fast-deep-equal@3.1.3:
+    resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==}
+
+  fast-fifo@1.3.2:
+    resolution: {integrity: sha512-/d9sfos4yxzpwkDkuN7k2SqFKtYNmCTzgfEpz82x34IM9/zc8KGxQoXg1liNC/izpRM/MBdt44Nmx41ZWqk+FQ==}
+
+  https-proxy-agent@7.0.6:
+    resolution: {integrity: sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==}
+    engines: {node: '>= 14'}
+
+  ignore@7.0.10:
+    resolution: {integrity: sha512-HpbUakT7xp5miBUywCHf36ZEuAJNklBJDDsGpUIjMzOSmM8ELSfA9Sa/QDPeNeqeoN31u+UTCkL4klCOVvRm4Q==}
+    engines: {node: '>= 4'}
+
+  index-to-position@1.2.0:
+    resolution: {integrity: sha512-Yg7+ztRkqslMAS2iFaU+Oa4KTSidr63OsFGlOrJoW981kIYO3CGCS3wA95P1mUi/IVSJkn0D479KTJpVpvFNuw==}
+    engines: {node: '>=18'}
+
+  js-levenshtein@1.1.6:
+    resolution: {integrity: sha512-X2BB11YZtrRqY4EnQcLX5Rh373zbK4alC1FW7D7MBhL2gtcC17cTnr6DmfHZeS0s2rTHjUTMMHfG7gO8SSdw+g==}
+    engines: {node: '>=0.10.0'}
+
+  js-tokens@4.0.0:
+    resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
+
+  js-yaml@4.3.2:
+    resolution: {integrity: sha512-SFNOvSJ+Dgf/9An904Yx+CgSlIPCkIpao4qo51lpee25TIRejdH3rhR4EZMGoNx3/TP3O+wzWuiTFl4sqbltzA==}
+    hasBin: true
+
+  json-schema-traverse@1.0.0:
+    resolution: {integrity: sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==}
+
+  minimatch@5.1.9:
+    resolution: {integrity: sha512-7o1wEA2RyMP7Iu7GNba9vc0RWWGACJOCZBJX2GJWip0ikV+wcOsgVuY9uE8CPiyQhkGFSlhuSkZPavN7u1c2Fw==}
+    engines: {node: '>=10'}
+
+  ms@2.1.3:
+    resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
+
+  nan@2.29.0:
+    resolution: {integrity: sha512-GlGk3HIvitbvs+LT3g6XUP1kpirKNvmDFwF/bmo6XNWSb/eYEs/O4bfgIEIXCZ+lIOTS5xNwDvSGMw6FJdAhtA==}
+
+  openapi-typescript@7.13.0:
+    resolution: {integrity: sha512-EFP392gcqXS7ntPvbhBzbF8TyBA+baIYEm791Hy5YkjDYKTnk/Tn5OQeKm5BIZvJihpp8Zzr4hzx0Irde1LNGQ==}
+    hasBin: true
+    peerDependencies:
+      typescript: ^5.x
+
+  parse-json@8.3.0:
+    resolution: {integrity: sha512-ybiGyvspI+fAoRQbIPRddCcSTV9/LsJbf0e/S85VLowVGzRmokfneg2kwVW/KU5rOXrPSbF1qAKPMgNTqqROQQ==}
+    engines: {node: '>=18'}
+
+  picocolors@1.1.1:
+    resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
+
+  pluralize@8.0.0:
+    resolution: {integrity: sha512-Nc3IT5yHzflTfbjgqWcCPpo7DaKy4FnpB0l/zCAW0Tc7jxAiuqSxHasntB3D7887LSrA93kDJ9IXovxJYxyLCA==}
+    engines: {node: '>=4'}
+
+  require-from-string@2.0.2:
+    resolution: {integrity: sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==}
+    engines: {node: '>=0.10.0'}
+
+  safer-buffer@2.1.2:
+    resolution: {integrity: sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==}
+
+  ssh2@1.17.0:
+    resolution: {integrity: sha512-wPldCk3asibAjQ/kziWQQt1Wh3PgDFpC0XpwclzKcdT1vql6KeYxf5LIt4nlFkUeR8WuphYMKqUA56X4rjbfgQ==}
+    engines: {node: '>=10.16.0'}
+
+  streamx@2.28.1:
+    resolution: {integrity: sha512-zEzXb0s5Cds7tqMH6rhZ05lcJydCWiQPEwiNngVqzsxCc962vLY4Uw+mW7od8kDH258k2Uz/JrOkdIAAhSh9VA==}
+
+  supports-color@10.2.2:
+    resolution: {integrity: sha512-SS+jx45GF1QjgEXQx4NJZV9ImqmO2NPz5FNsIHrsDjh2YsHnawpan7SNQ1o8NuhrbHZy9AZhIoCUiCeaW/C80g==}
+    engines: {node: '>=18'}
+
+  tar-stream@3.2.1:
+    resolution: {integrity: sha512-nqsEO8zLZJvrOMdEwkA0QdCLFbetHMn95Zqu4fKwX+hkaTWJPZZOrxx/PwtxoK0MMGQmBQNRW3CPs8IFYQz4cQ==}
+
+  teex@1.0.1:
+    resolution: {integrity: sha512-eYE6iEI62Ni1H8oIa7KlDU6uQBtqr4Eajni3wX7rpfXD8ysFx8z0+dri+KWEPWpBsxXfxu58x/0jvTVT1ekOSg==}
+
+  text-decoder@1.2.7:
+    resolution: {integrity: sha512-vlLytXkeP4xvEq2otHeJfSQIRyWxo/oZGEbXrtEEF9Hnmrdly59sUbzZ/QgyWuLYHctCHxFF4tRQZNQ9k60ExQ==}
+
+  tweetnacl@0.14.5:
+    resolution: {integrity: sha512-KXXFFdAbFXY4geFIwoyNK+f5Z1b7swfXABfL7HXCmoIWMKU3dmS26672A4EeQtDzLKy7SXmfBu51JolvEKwtGA==}
+
+  type-fest@4.41.0:
+    resolution: {integrity: sha512-TeTSQ6H5YHvpqVwBRcnLDCBnDOHWYu7IvGbHT6N8AOymcr9PJGjc1GTtiWZTYg0NCgYwvnYWEkVChQAr9bjfwA==}
+    engines: {node: '>=16'}
+
+  typescript@5.9.3:
+    resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  undici-types@5.26.5:
+    resolution: {integrity: sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA==}
+
+  undici-types@7.24.6:
+    resolution: {integrity: sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg==}
+
+  uri-js-replace@1.0.1:
+    resolution: {integrity: sha512-W+C9NWNLFOoBI2QWDp4UT9pv65r2w5Cx+3sTYFvtMdDBxkKt1syCqsUdSFAChbEe1uK5TfS04wt/nGwmaeIQ0g==}
+
+  yaml-ast-parser@0.0.43:
+    resolution: {integrity: sha512-2PTINUwsRqSd+s8XxKaJWQlUuEMHJQyEuh2edBbW8KNJz0SJPwUSD2zRWqezFEdN7IzAgeuYHFUCF7o8zRdZ0A==}
+
+  yargs-parser@21.1.1:
+    resolution: {integrity: sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==}
+    engines: {node: '>=12'}
+
+snapshots:
+
+  '@babel/code-frame@7.29.7':
+    dependencies:
+      '@babel/helper-validator-identifier': 7.29.7
+      js-tokens: 4.0.0
+      picocolors: 1.1.1
+
+  '@babel/helper-validator-identifier@7.29.7': {}
+
+  '@mieweb/deploy-contract@0.2.1-pr14.5': {}
+
+  '@redocly/ajv@8.11.2':
+    dependencies:
+      fast-deep-equal: 3.1.3
+      json-schema-traverse: 1.0.0
+      require-from-string: 2.0.2
+      uri-js-replace: 1.0.1
+
+  '@redocly/config@0.22.0': {}
+
+  '@redocly/openapi-core@1.34.20(supports-color@10.2.2)':
+    dependencies:
+      '@redocly/ajv': 8.11.2
+      '@redocly/config': 0.22.0
+      colorette: 1.4.0
+      https-proxy-agent: 7.0.6(supports-color@10.2.2)
+      js-levenshtein: 1.1.6
+      js-yaml: 4.3.2
+      minimatch: 5.1.9
+      pluralize: 8.0.0
+      yaml-ast-parser: 0.0.43
+    transitivePeerDependencies:
+      - supports-color
+
+  '@types/node@18.19.130':
+    dependencies:
+      undici-types: 5.26.5
+
+  '@types/node@24.19.0':
+    dependencies:
+      undici-types: 7.24.6
+
+  '@types/ssh2@1.15.6':
+    dependencies:
+      '@types/node': 18.19.130
+
+  '@types/tar-stream@3.1.5':
+    dependencies:
+      '@types/node': 24.19.0
+
+  agent-base@7.1.4: {}
+
+  ansi-colors@4.1.3: {}
+
+  argparse@2.0.1: {}
+
+  asn1@0.2.6:
+    dependencies:
+      safer-buffer: 2.1.2
+
+  b4a@1.9.0: {}
+
+  balanced-match@1.0.2: {}
+
+  bare-events@2.9.2: {}
+
+  bare-fs@4.8.2:
+    dependencies:
+      bare-events: 2.9.2
+      bare-path: 3.1.2
+      bare-stream: 2.13.4(bare-events@2.9.2)
+      bare-url: 2.5.4
+      fast-fifo: 1.3.2
+    transitivePeerDependencies:
+      - bare-abort-controller
+      - react-native-b4a
+
+  bare-path@3.1.2: {}
+
+  bare-stream@2.13.4(bare-events@2.9.2):
+    dependencies:
+      b4a: 1.9.0
+      streamx: 2.28.1
+      teex: 1.0.1
+    optionalDependencies:
+      bare-events: 2.9.2
+    transitivePeerDependencies:
+      - react-native-b4a
+
+  bare-url@2.5.4:
+    dependencies:
+      bare-path: 3.1.2
+
+  bcrypt-pbkdf@1.0.2:
+    dependencies:
+      tweetnacl: 0.14.5
+
+  brace-expansion@2.1.7:
+    dependencies:
+      balanced-match: 1.0.2
+
+  buildcheck@0.0.7:
+    optional: true
+
+  change-case@5.4.4: {}
+
+  colorette@1.4.0: {}
+
+  cpu-features@0.0.10:
+    dependencies:
+      buildcheck: 0.0.7
+      nan: 2.29.0
+    optional: true
+
+  debug@4.4.3(supports-color@10.2.2):
+    dependencies:
+      ms: 2.1.3
+    optionalDependencies:
+      supports-color: 10.2.2
+
+  events-universal@1.0.1:
+    dependencies:
+      bare-events: 2.9.2
+    transitivePeerDependencies:
+      - bare-abort-controller
+
+  fast-deep-equal@3.1.3: {}
+
+  fast-fifo@1.3.2: {}
+
+  https-proxy-agent@7.0.6(supports-color@10.2.2):
+    dependencies:
+      agent-base: 7.1.4
+      debug: 4.4.3(supports-color@10.2.2)
+    transitivePeerDependencies:
+      - supports-color
+
+  ignore@7.0.10: {}
+
+  index-to-position@1.2.0: {}
+
+  js-levenshtein@1.1.6: {}
+
+  js-tokens@4.0.0: {}
+
+  js-yaml@4.3.2:
+    dependencies:
+      argparse: 2.0.1
+
+  json-schema-traverse@1.0.0: {}
+
+  minimatch@5.1.9:
+    dependencies:
+      brace-expansion: 2.1.7
+
+  ms@2.1.3: {}
+
+  nan@2.29.0:
+    optional: true
+
+  openapi-typescript@7.13.0(typescript@5.9.3):
+    dependencies:
+      '@redocly/openapi-core': 1.34.20(supports-color@10.2.2)
+      ansi-colors: 4.1.3
+      change-case: 5.4.4
+      parse-json: 8.3.0
+      supports-color: 10.2.2
+      typescript: 5.9.3
+      yargs-parser: 21.1.1
+
+  parse-json@8.3.0:
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      index-to-position: 1.2.0
+      type-fest: 4.41.0
+
+  picocolors@1.1.1: {}
+
+  pluralize@8.0.0: {}
+
+  require-from-string@2.0.2: {}
+
+  safer-buffer@2.1.2: {}
+
+  ssh2@1.17.0:
+    dependencies:
+      asn1: 0.2.6
+      bcrypt-pbkdf: 1.0.2
+    optionalDependencies:
+      cpu-features: 0.0.10
+      nan: 2.29.0
+
+  streamx@2.28.1:
+    dependencies:
+      events-universal: 1.0.1
+      fast-fifo: 1.3.2
+      text-decoder: 1.2.7
+    transitivePeerDependencies:
+      - bare-abort-controller
+      - react-native-b4a
+
+  supports-color@10.2.2: {}
+
+  tar-stream@3.2.1:
+    dependencies:
+      b4a: 1.9.0
+      bare-fs: 4.8.2
+      fast-fifo: 1.3.2
+      streamx: 2.28.1
+    transitivePeerDependencies:
+      - bare-abort-controller
+      - bare-buffer
+      - react-native-b4a
+
+  teex@1.0.1:
+    dependencies:
+      streamx: 2.28.1
+    transitivePeerDependencies:
+      - bare-abort-controller
+      - react-native-b4a
+
+  text-decoder@1.2.7:
+    dependencies:
+      b4a: 1.9.0
+    transitivePeerDependencies:
+      - react-native-b4a
+
+  tweetnacl@0.14.5: {}
+
+  type-fest@4.41.0: {}
+
+  typescript@5.9.3: {}
+
+  undici-types@5.26.5: {}
+
+  undici-types@7.24.6: {}
+
+  uri-js-replace@1.0.1: {}
+
+  yaml-ast-parser@0.0.43: {}
+
+  yargs-parser@21.1.1: {}
diff --git a/packages/os-cloud-provider/pnpm-workspace.yaml b/packages/os-cloud-provider/pnpm-workspace.yaml
new file mode 100644
index 00000000..feeb5b32
--- /dev/null
+++ b/packages/os-cloud-provider/pnpm-workspace.yaml
@@ -0,0 +1,7 @@
+# Standalone package (not part of a repo-wide workspace); this file only holds pnpm settings.
+# ssh2 works in pure JS; skip its optional native add-ons so installs need no compiler.
+allowBuilds:
+  ssh2: false
+  cpu-features: false
+minimumReleaseAgeExclude:
+  - '@mieweb/deploy-contract@0.2.1-pr14.1 || 0.2.1-pr14.5'
diff --git a/packages/os-cloud-provider/src/api-types.ts b/packages/os-cloud-provider/src/api-types.ts
new file mode 100644
index 00000000..f3fca2c3
--- /dev/null
+++ b/packages/os-cloud-provider/src/api-types.ts
@@ -0,0 +1,72 @@
+/**
+ * Manager API types, derived from the Manager's own OpenAPI spec
+ * (`create-a-container/openapi.v1.yaml`, regenerated with `pnpm gen:types`).
+ * Aliases only — the provider never hand-writes a Manager response shape.
+ */
+
+import type { components } from './generated/manager-api.ts';
+
+type Schemas = components['schemas'];
+
+export type Container = Schemas['Container'];
+export type ContainerService = Schemas['ContainerService'];
+export type ServiceInput = Schemas['ServiceInput'];
+export type ServiceUpdate = Schemas['ServiceUpdate'];
+export type EnvVar = Schemas['EnvVar'];
+export type VolumeAttach = Schemas['VolumeAttach'];
+export type Volume = Schemas['Volume'];
+
+/** `Job.status` as returned by `get_job`. */
+export type JobStatus = 'pending' | 'running' | 'success' | 'failure' | 'cancelled';
+
+export interface Job {
+  id: number;
+  status: JobStatus;
+  command?: string;
+  createdBy?: string;
+}
+
+export interface JobLogRow {
+  id: number;
+  output: string;
+  createdAt?: string;
+}
+
+/** `get_new_container_form` payload. */
+export interface NewContainerForm {
+  siteId: number;
+  externalDomains: { id: number; name: string; siteId?: number | null }[];
+  nvidiaAvailable: boolean;
+}
+
+/** `create_container` 201 payload (`containerId` is the Manager DB id). */
+export interface CreateContainerResult {
+  containerId: number;
+  jobId: number;
+  hostname: string;
+  status: string;
+}
+
+/** `update_container` 200 payload. */
+export interface UpdateContainerResult {
+  containerId: number;
+  jobId?: number | null;
+  dnsWarnings?: string[];
+  pendingRestart?: boolean;
+  message?: string;
+}
+
+export interface DeleteContainerResult {
+  deleted: boolean;
+  dnsWarnings?: string[];
+}
+
+export interface SessionInfo {
+  user: string;
+  isAdmin: boolean;
+}
+
+export interface CreatedApiKey {
+  id: string;
+  key: string;
+}
diff --git a/packages/os-cloud-provider/src/auth.ts b/packages/os-cloud-provider/src/auth.ts
new file mode 100644
index 00000000..114a53cd
--- /dev/null
+++ b/packages/os-cloud-provider/src/auth.ts
@@ -0,0 +1,285 @@
+/**
+ * `whoami`, `login`, `logout`.
+ *
+ * `login` is a loopback handoff (issue #475 §3b/§4.3): listen on
+ * 127.0.0.1:<random>, open the browser at the Manager's
+ * `/api/v1/auth/cli/callback?port&state`, and wait for the Manager to redirect
+ * back to `http://127.0.0.1:<port>/callback#key=…&id=…&user=…&state=…`.
+ * Browsers never send the fragment to a server, so `/callback` returns a small
+ * page that POSTs it to `/token` on the same listener.
+ */
+
+import { spawn } from 'node:child_process';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
+import { hostname as osHostname } from 'node:os';
+import { createInterface } from 'node:readline/promises';
+import type { AuthStatus, DeployContext, DeployLogger } from '@mieweb/deploy-contract';
+import type { SessionInfo } from './api-types.ts';
+import { ManagerClient } from './client.ts';
+import {
+  DEFAULT_INSTANCE_URL,
+  instanceFromArgv,
+  normalizeInstanceUrl,
+  resolveInstanceUrl,
+  resolveToken,
+} from './config.ts';
+import { deleteCredential, readCredential, writeCredential } from './credentials.ts';
+import type { ProviderDeps } from './deploy.ts';
+
+export async function whoami(ctx: DeployContext, deps: ProviderDeps): Promise<AuthStatus> {
+  const instanceUrl = resolveInstanceUrl(deps.env, ctx.targetConfig);
+  const tok = await resolveToken(deps.env, instanceUrl);
+  if (!tok) return { authenticated: false };
+  const client = new ManagerClient({ instanceUrl, token: tok.token, target: ctx.target, signal: ctx.signal, fetch: deps.fetch });
+  try {
+    const session = await client.get<SessionInfo>('/session');
+    return { authenticated: true, account: session.user, method: tok.method };
+  } catch (err) {
+    if ((err as Error).name === 'AuthError') return { authenticated: false, method: tok.method };
+    throw err;
+  }
+}
+
+// --- login ------------------------------------------------------------------
+
+export interface LoginHooks {
+  /** Open a URL in the user's browser (default: platform opener). */
+  openBrowser?: (url: string) => void;
+  /** Ask for the instance URL when nothing configures it. */
+  prompt?: (question: string) => Promise<string>;
+  /** Give up waiting after this long (default 5 min). */
+  timeoutMs?: number;
+}
+
+function defaultOpenBrowser(url: string): void {
+  const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+  const args = process.platform === 'win32' ? ['/c', 'start', '""', url] : [url];
+  try {
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+  } catch {
+    // The URL is always printed too; a missing opener isn't fatal.
+  }
+}
+
+async function defaultPrompt(question: string): Promise<string> {
+  if (!process.stdin.isTTY) return '';
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+  }
+}
+
+/** Instance for `login`: --instance → env → targetConfig.instanceUrl → prompt (default os.mieweb.org). */
+async function loginInstanceUrl(ctx: DeployContext, deps: ProviderDeps, hooks: LoginHooks): Promise<string> {
+  const configured =
+    instanceFromArgv(ctx.argv) ||
+    deps.env.MIEWEB_OS_URL?.trim() ||
+    (typeof ctx.targetConfig.instanceUrl === 'string' ? ctx.targetConfig.instanceUrl.trim() : '');
+  if (configured) return normalizeInstanceUrl(configured);
+  const answer = (await (hooks.prompt ?? defaultPrompt)(`Manager URL [${DEFAULT_INSTANCE_URL}]: `)).trim();
+  return normalizeInstanceUrl(answer || DEFAULT_INSTANCE_URL);
+}
+
+const CALLBACK_PAGE = `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>mieweb login</title>
+<style>body{font-family:system-ui,sans-serif;max-width:32rem;margin:4rem auto;padding:0 1rem}</style></head>
+<body><h1 id="t">Finishing sign-in…</h1><p id="m"></p><script>
+(async () => {
+  const t = document.getElementById('t'), m = document.getElementById('m');
+  const frag = location.hash.slice(1);
+  history.replaceState(null, '', location.pathname);
+  try {
+    const r = await fetch('/token', { method: 'POST', headers: { 'Content-Type': 'text/plain' }, body: frag });
+    if (!r.ok) throw new Error(await r.text());
+    t.textContent = 'Signed in'; m.textContent = 'You can close this tab and return to the terminal.';
+  } catch (e) {
+    t.textContent = 'Sign-in failed'; m.textContent = String(e.message || e);
+  }
+})();
+</script></body></html>`;
+
+interface Handoff {
+  key: string;
+  id: string;
+  user: string;
+}
+
+function safeEqual(a: string, b: string): boolean {
+  const x = Buffer.from(a);
+  const y = Buffer.from(b);
+  return x.length === y.length && timingSafeEqual(x, y);
+}
+
+function readBody(req: IncomingMessage, limit = 8192): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let body = '';
+    req.setEncoding('utf8');
+    req.on('data', (chunk: string) => {
+      body += chunk;
+      if (body.length > limit) {
+        reject(new Error('body too large'));
+        req.destroy();
+      }
+    });
+    req.on('end', () => resolve(body));
+    req.on('error', reject);
+  });
+}
+
+/** Start the loopback listener; resolves the handoff once a valid `/token` POST arrives. */
+export async function startLoopback(
+  state: string,
+  signal: AbortSignal,
+  timeoutMs: number,
+): Promise<{ port: number; result: Promise<Handoff>; close: () => void }> {
+  let settle!: { resolve: (h: Handoff) => void; reject: (e: unknown) => void };
+  const result = new Promise<Handoff>((resolve, reject) => {
+    settle = { resolve, reject };
+  });
+
+  const server = createServer((req: IncomingMessage, res: ServerResponse) => {
+    const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+    const send = (status: number, type: string, body: string): void => {
+      res.writeHead(status, { 'Content-Type': type, 'Cache-Control': 'no-store', 'Referrer-Policy': 'no-referrer' });
+      res.end(body);
+    };
+    if (req.method === 'GET' && url.pathname === '/callback') {
+      send(200, 'text/html; charset=utf-8', CALLBACK_PAGE);
+      return;
+    }
+    if (req.method === 'POST' && url.pathname === '/token') {
+      // Only our own callback page (same origin) may post the handoff.
+      const origin = req.headers.origin;
+      const self = `http://127.0.0.1:${(server.address() as { port: number }).port}`;
+      if (origin !== undefined && origin !== self) {
+        send(403, 'text/plain', 'Forbidden origin');
+        return;
+      }
+      readBody(req).then(
+        (body) => {
+          const p = new URLSearchParams(body);
+          const key = p.get('key') ?? '';
+          const id = p.get('id') ?? '';
+          const user = p.get('user') ?? '';
+          if (!safeEqual(p.get('state') ?? '', state)) {
+            send(400, 'text/plain', 'State mismatch — this sign-in was not started by this terminal. Re-run `mieweb login`.');
+            return;
+          }
+          if (!key || !id) {
+            send(400, 'text/plain', 'The Manager did not return an API key.');
+            return;
+          }
+          send(200, 'text/plain', 'ok');
+          settle.resolve({ key, id, user });
+        },
+        () => send(400, 'text/plain', 'Bad request'),
+      );
+      return;
+    }
+    send(404, 'text/plain', 'Not found');
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => resolve());
+  });
+  const port = (server.address() as { port: number }).port;
+
+  const timer = setTimeout(() => settle.reject(new Error('Timed out waiting for the browser sign-in')), timeoutMs);
+  const onAbort = (): void => settle.reject(signal.reason);
+  signal.addEventListener('abort', onAbort, { once: true });
+  const close = (): void => {
+    clearTimeout(timer);
+    signal.removeEventListener('abort', onAbort);
+    server.closeAllConnections();
+    server.close();
+  };
+  return { port, result, close };
+}
+
+function clientLabel(): string {
+  const host = osHostname().toLowerCase().replace(/[^a-z0-9._-]/g, '-').slice(0, 40) || 'host';
+  return `mieweb-cli@${host}`;
+}
+
+export async function login(ctx: DeployContext, deps: ProviderDeps, hooks: LoginHooks = {}): Promise<void> {
+  const { logger } = ctx;
+  const instanceUrl = await loginInstanceUrl(ctx, deps, hooks);
+  if (deps.env.MIEWEB_OS_TOKEN?.trim()) {
+    logger.warn('MIEWEB_OS_TOKEN is set in the environment and takes precedence over the login cache.');
+  }
+
+  // Fail fast (before opening a browser) if the instance isn't a Manager.
+  const probe = new ManagerClient({ instanceUrl, token: null, target: ctx.target, signal: ctx.signal, fetch: deps.fetch });
+  await probe.request<{ status: string }>('GET', '/health', { auth: false });
+
+  const state = randomBytes(24).toString('base64url');
+  const loop = await startLoopback(state, ctx.signal, hooks.timeoutMs ?? 5 * 60 * 1000);
+  try {
+    const params = new URLSearchParams({ port: String(loop.port), state, client: clientLabel() });
+    const authUrl = `${instanceUrl}/api/v1/auth/cli/callback?${params.toString()}`;
+    logger.info(`Opening your browser to sign in to ${instanceUrl}`);
+    logger.info(`If it doesn't open, visit: ${authUrl}`);
+    (hooks.openBrowser ?? defaultOpenBrowser)(authUrl);
+
+    const handoff = await loop.result;
+
+    const client = new ManagerClient({ instanceUrl, token: handoff.key, target: ctx.target, signal: ctx.signal, fetch: deps.fetch });
+    const session = await client.get<SessionInfo>('/session');
+
+    // Revoke the key this login replaces, so repeated logins don't pile up keys.
+    const previous = await readCredential(deps.env, instanceUrl);
+    await writeCredential(deps.env, instanceUrl, {
+      token: handoff.key,
+      apiKeyId: handoff.id,
+      user: session.user,
+      savedAt: new Date().toISOString(),
+    });
+    if (previous && previous.apiKeyId !== handoff.id) {
+      await revoke(instanceUrl, previous.token, previous.apiKeyId, ctx, deps, logger);
+    }
+    logger.info(`Logged in to ${instanceUrl} as ${session.user}`);
+  } finally {
+    loop.close();
+  }
+}
+
+async function revoke(
+  instanceUrl: string,
+  token: string,
+  apiKeyId: string,
+  ctx: DeployContext,
+  deps: ProviderDeps,
+  logger: DeployLogger,
+): Promise<void> {
+  const client = new ManagerClient({ instanceUrl, token, target: ctx.target, signal: ctx.signal, fetch: deps.fetch });
+  try {
+    await client.delete(`/apikeys/${encodeURIComponent(apiKeyId)}`);
+  } catch (err) {
+    const status = (err as { status?: number }).status;
+    // Already gone or already invalid: nothing to revoke.
+    if ((err as Error).name === 'AuthError' || status === 404) return;
+    logger.warn(`Could not revoke API key ${apiKeyId} on ${instanceUrl}: ${(err as Error).message}`);
+  }
+}
+
+export async function logout(ctx: DeployContext, deps: ProviderDeps): Promise<void> {
+  const { logger } = ctx;
+  const explicit = instanceFromArgv(ctx.argv) || deps.env.MIEWEB_OS_URL?.trim();
+  const instanceUrl = explicit ? normalizeInstanceUrl(explicit) : resolveInstanceUrl(deps.env, ctx.targetConfig);
+  if (deps.env.MIEWEB_OS_TOKEN?.trim()) {
+    logger.warn('MIEWEB_OS_TOKEN is set in the environment; logout cannot clear it. Unset it to fully log out.');
+  }
+  const cred = await readCredential(deps.env, instanceUrl);
+  if (!cred) {
+    logger.info(`Not logged in to ${instanceUrl}`);
+    return;
+  }
+  await revoke(instanceUrl, cred.token, cred.apiKeyId, ctx, deps, logger);
+  await deleteCredential(deps.env, instanceUrl);
+  logger.info(`Logged out of ${instanceUrl}`);
+}
diff --git a/packages/os-cloud-provider/src/client.ts b/packages/os-cloud-provider/src/client.ts
new file mode 100644
index 00000000..6495a537
--- /dev/null
+++ b/packages/os-cloud-provider/src/client.ts
@@ -0,0 +1,136 @@
+/**
+ * Minimal Manager API client: Bearer auth, `{ data }` / `{ error }` envelope
+ * unwrapping, AbortSignal support, and 401/403 → AuthError.
+ *
+ * Only `Authorization: Bearer` is sent — no cookies — so the Manager's CSRF
+ * guard skips these requests (middlewares/api.js).
+ */
+
+import { AuthError } from '@mieweb/deploy-contract';
+import type { DeployTarget } from '@mieweb/deploy-contract';
+import { LOGIN_HINT, PROVIDER_NAME } from './config.ts';
+import { sleep } from './jobs.ts';
+
+const RETRIES = 3;
+const RETRY_DELAY_MS = 500;
+
+/** A non-auth error response from the Manager. */
+export class ManagerApiError extends Error {
+  readonly status: number;
+  readonly code: string;
+  constructor(status: number, code: string, message: string) {
+    super(message);
+    this.name = 'ManagerApiError';
+    this.status = status;
+    this.code = code;
+  }
+}
+
+export interface ClientOptions {
+  instanceUrl: string;
+  token: string | null;
+  target: DeployTarget;
+  signal?: AbortSignal;
+  fetch?: typeof fetch;
+}
+
+type Query = Record<string, string | number | undefined>;
+
+export class ManagerClient {
+  readonly instanceUrl: string;
+  readonly target: DeployTarget;
+  private readonly token: string | null;
+  private readonly signal: AbortSignal | undefined;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(opts: ClientOptions) {
+    this.instanceUrl = opts.instanceUrl;
+    this.target = opts.target;
+    this.token = opts.token;
+    this.signal = opts.signal;
+    this.fetchImpl = opts.fetch ?? globalThis.fetch;
+  }
+
+  private url(path: string, query?: Query): string {
+    const u = new URL(`${this.instanceUrl}/api/v1${path}`);
+    for (const [k, v] of Object.entries(query ?? {})) {
+      if (v !== undefined) u.searchParams.set(k, String(v));
+    }
+    return u.toString();
+  }
+
+  authError(): AuthError {
+    return new AuthError(PROVIDER_NAME, this.target, LOGIN_HINT);
+  }
+
+  /** Perform a request and return the unwrapped `data` payload. */
+  async request<T>(method: string, path: string, opts: { body?: unknown; query?: Query; auth?: boolean } = {}): Promise<T> {
+    const needsAuth = opts.auth !== false;
+    if (needsAuth && !this.token) throw this.authError();
+
+    const headers: Record<string, string> = { Accept: 'application/json' };
+    if (needsAuth && this.token) headers.Authorization = `Bearer ${this.token}`;
+    if (opts.body !== undefined) headers['Content-Type'] = 'application/json';
+
+    // GETs are idempotent, so retry them on connection-level failures (a
+    // dropped keep-alive socket mid job-poll shouldn't fail a deploy).
+    // Writes are never retried.
+    const attempts = method === 'GET' ? RETRIES + 1 : 1;
+    let res!: Response;
+    for (let attempt = 1; ; attempt += 1) {
+      try {
+        res = await this.fetchImpl(this.url(path, opts.query), {
+          method,
+          headers,
+          body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+          signal: this.signal,
+          redirect: 'manual',
+        });
+        break;
+      } catch (err) {
+        if ((err as Error).name === 'AbortError' || this.signal?.aborted) throw err;
+        if (attempt < attempts) {
+          await sleep(RETRY_DELAY_MS * attempt, this.signal ?? new AbortController().signal);
+          continue;
+        }
+        throw new Error(`Cannot reach the Manager at ${this.instanceUrl}: ${(err as Error).message}`, { cause: err });
+      }
+    }
+
+    if (res.status === 401 || res.status === 403) {
+      await res.body?.cancel();
+      throw this.authError();
+    }
+    if (res.status === 204) return undefined as T;
+
+    const text = await res.text();
+    let json: { data?: unknown; error?: { code?: string; message?: string } } | undefined;
+    try {
+      json = text ? JSON.parse(text) : undefined;
+    } catch {
+      json = undefined;
+    }
+    if (!res.ok) {
+      const code = json?.error?.code ?? `http_${res.status}`;
+      const message = json?.error?.message ?? (text.slice(0, 200) || res.statusText);
+      throw new ManagerApiError(res.status, code, `${method} ${path} failed (${res.status} ${code}): ${message}`);
+    }
+    if (json === undefined || !('data' in json)) {
+      throw new ManagerApiError(res.status, 'bad_response', `${method} ${path}: unexpected non-JSON response from ${this.instanceUrl}`);
+    }
+    return json.data as T;
+  }
+
+  get<T>(path: string, query?: Query): Promise<T> {
+    return this.request<T>('GET', path, { query });
+  }
+  post<T>(path: string, body: unknown): Promise<T> {
+    return this.request<T>('POST', path, { body });
+  }
+  put<T>(path: string, body: unknown): Promise<T> {
+    return this.request<T>('PUT', path, { body });
+  }
+  delete<T>(path: string): Promise<T> {
+    return this.request<T>('DELETE', path);
+  }
+}
diff --git a/packages/os-cloud-provider/src/config.ts b/packages/os-cloud-provider/src/config.ts
new file mode 100644
index 00000000..a603ac39
--- /dev/null
+++ b/packages/os-cloud-provider/src/config.ts
@@ -0,0 +1,218 @@
+/**
+ * Configuration resolution: instance URL, API token, and the non-secret
+ * `targets.mieweb` block of mieweb.jsonc.
+ *
+ * Precedence (issue #475 §3):
+ *   token:        env.MIEWEB_OS_TOKEN → machine-local login cache (never config)
+ *   instance URL: env.MIEWEB_OS_URL → targetConfig.instanceUrl → default
+ */
+
+import type { DeployContext, ProviderEnv } from '@mieweb/deploy-contract';
+import { readCredential } from './credentials.ts';
+
+export const PROVIDER_NAME = 'opensource-server';
+export const DEFAULT_INSTANCE_URL = 'https://os.mieweb.org';
+export const DEFAULT_IMAGE = 'ghcr.io/mieweb/opensource-server/cloud:latest';
+export const DEFAULT_PORT = 8787;
+/** The one rw persistent volume the converged container's datastores live on (#421). */
+export const DATA_VOLUME = { name: 'data', mountPath: '/mnt/data', mode: 'rw' } as const;
+
+/** Same rule the Manager enforces on `Container.hostname` (models/container.js). */
+export const DNS_LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+
+export const LOGIN_HINT = 'set MIEWEB_OS_TOKEN, or run `mieweb login --target mieweb`';
+
+/** Thrown for configuration problems the user must fix (not auth, not backend). */
+export class ConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ConfigError';
+  }
+}
+
+/**
+ * Canonical instance URL: scheme + host (+ port) + path without a trailing
+ * slash or a trailing `/api/v1`. It is also the key for the login cache, so
+ * `https://OS.mieweb.org/` and `https://os.mieweb.org` share one entry.
+ */
+export function normalizeInstanceUrl(raw: string): string {
+  let url: URL;
+  try {
+    url = new URL(raw.trim());
+  } catch {
+    throw new ConfigError(`Invalid instance URL: ${JSON.stringify(raw)}`);
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new ConfigError(`Instance URL must be http(s): ${JSON.stringify(raw)}`);
+  }
+  if (url.username || url.password) {
+    throw new ConfigError('Instance URL must not contain credentials');
+  }
+  let path = url.pathname.replace(/\/+$/, '');
+  if (path.endsWith('/api/v1')) path = path.slice(0, -'/api/v1'.length);
+  return `${url.protocol}//${url.host}${path}`;
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === 'string' && v.trim() !== '' ? v.trim() : undefined;
+}
+
+/** Instance URL for all verbs except `login` (see {@link loginInstanceUrl}). */
+export function resolveInstanceUrl(env: ProviderEnv, targetConfig: Readonly<Record<string, unknown>>): string {
+  return normalizeInstanceUrl(str(env.MIEWEB_OS_URL) ?? str(targetConfig.instanceUrl) ?? DEFAULT_INSTANCE_URL);
+}
+
+/** Value of `--instance <url>` / `--instance=<url>` in passthrough argv, if any. */
+export function instanceFromArgv(argv: readonly string[]): string | undefined {
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]!;
+    if (a === '--instance') return str(argv[i + 1]);
+    if (a.startsWith('--instance=')) return str(a.slice('--instance='.length));
+  }
+  return undefined;
+}
+
+export interface ResolvedToken {
+  token: string;
+  method: 'env' | 'login';
+}
+
+/** Token for `instanceUrl`, or null when neither env nor the login cache has one. */
+export async function resolveToken(env: ProviderEnv, instanceUrl: string): Promise<ResolvedToken | null> {
+  const fromEnv = str(env.MIEWEB_OS_TOKEN);
+  if (fromEnv) return { token: fromEnv, method: 'env' };
+  const cached = await readCredential(env, instanceUrl);
+  return cached ? { token: cached.token, method: 'login' } : null;
+}
+
+/** Extra non-HTTP service declared in `targets.mieweb.services`. */
+export interface ExtraService {
+  type: 'tcp' | 'udp' | 'srv';
+  internalPort: number;
+  dnsName?: string;
+}
+
+/** The parts of `targets.mieweb` deploy/destroy use. All non-secret. */
+export interface TargetSettings {
+  instanceUrl: string;
+  /** Manager site; undefined → chosen at deploy time (see resolveSiteId in deploy.ts). */
+  siteId?: number;
+  image: string;
+  port: number;
+  /** External hostname label; defaults to the app name. */
+  externalHostname: string;
+  /** External domain, by name or id; defaults to the site's first domain. */
+  domain?: string | number;
+  authRequired: boolean;
+  nvidia?: boolean;
+  services: ExtraService[];
+  /** Sync the worktree into the container after converging (default true). */
+  sync: boolean;
+  /** SSH login for the sync (default: the Manager account). */
+  sshUser?: string;
+  /** SSH host override (default: the container's published sshHost). */
+  sshHost?: string;
+  /** Start command inside the container (default `npm start`). */
+  start?: string;
+}
+
+function posInt(v: unknown, what: string): number {
+  const n = typeof v === 'string' && /^\d+$/.test(v) ? Number(v) : v;
+  if (typeof n !== 'number' || !Number.isInteger(n) || n <= 0) {
+    throw new ConfigError(`${what} must be a positive integer, got ${JSON.stringify(v)}`);
+  }
+  return n;
+}
+
+function port(v: unknown, what: string): number {
+  const n = posInt(v, what);
+  if (n > 65535) throw new ConfigError(`${what} must be a TCP port (1-65535), got ${n}`);
+  return n;
+}
+
+/** App name from wrangler.jsonc `name`; must be a DNS label (it becomes the hostname). */
+export function appName(manifest: Readonly<Record<string, unknown>>): string {
+  const name = manifest.name;
+  if (typeof name !== 'string' || name === '') {
+    throw new ConfigError('wrangler.jsonc must set `name` (it is used as the container hostname)');
+  }
+  if (!DNS_LABEL.test(name)) {
+    throw new ConfigError(
+      `wrangler.jsonc \`name\` ${JSON.stringify(name)} is not a valid DNS label ` +
+        '(1-63 chars of a-z, 0-9 and "-", starting and ending with a letter or digit)',
+    );
+  }
+  return name;
+}
+
+/** Validate `targets.mieweb` for deploy/destroy. */
+export function resolveTargetSettings(ctx: DeployContext, env: ProviderEnv): TargetSettings {
+  const tc = ctx.targetConfig;
+  const name = appName(ctx.manifest);
+  const target = `targets.${ctx.target}`;
+
+  // MIEWEB_OS_SITE_ID → targets.mieweb.siteId → (deploy time) the only site, or a prompt.
+  const rawSite = str(env.MIEWEB_OS_SITE_ID) ?? (tc.siteId === null || tc.siteId === '' ? undefined : tc.siteId);
+  const siteId = rawSite === undefined ? undefined : posInt(rawSite, str(env.MIEWEB_OS_SITE_ID) ? 'MIEWEB_OS_SITE_ID' : `${target}.siteId`);
+
+  const externalHostname = str(tc.externalHostname) ?? name;
+  if (!DNS_LABEL.test(externalHostname)) {
+    throw new ConfigError(`${target}.externalHostname ${JSON.stringify(externalHostname)} is not a valid DNS label`);
+  }
+
+  let domain: string | number | undefined;
+  if (tc.domain !== undefined) {
+    if (typeof tc.domain === 'number') domain = posInt(tc.domain, `${target}.domain`);
+    else if (str(tc.domain)) domain = str(tc.domain);
+    else throw new ConfigError(`${target}.domain must be a domain name or id`);
+  }
+
+  if (tc.authRequired !== undefined && typeof tc.authRequired !== 'boolean') {
+    throw new ConfigError(`${target}.authRequired must be a boolean`);
+  }
+  if (tc.sync !== undefined && typeof tc.sync !== 'boolean') {
+    throw new ConfigError(`${target}.sync must be a boolean`);
+  }
+  if (tc.source !== undefined || tc.ref !== undefined) {
+    throw new ConfigError(
+      `${target}.source/.ref are no longer used: deploy syncs your local worktree into the container over SSH`,
+    );
+  }
+  if (tc.nvidia !== undefined && typeof tc.nvidia !== 'boolean') {
+    throw new ConfigError(`${target}.nvidia must be a boolean`);
+  }
+
+  const services: ExtraService[] = [];
+  if (tc.services !== undefined) {
+    if (!Array.isArray(tc.services)) throw new ConfigError(`${target}.services must be an array`);
+    for (const [i, raw] of tc.services.entries()) {
+      const s = (raw ?? {}) as Record<string, unknown>;
+      if (s.type !== 'tcp' && s.type !== 'udp' && s.type !== 'srv') {
+        throw new ConfigError(`${target}.services[${i}].type must be tcp, udp or srv (the HTTP service is implicit)`);
+      }
+      const svc: ExtraService = { type: s.type, internalPort: port(s.internalPort, `${target}.services[${i}].internalPort`) };
+      if (s.type === 'srv') {
+        const dnsName = str(s.dnsName);
+        if (!dnsName) throw new ConfigError(`${target}.services[${i}].dnsName is required for srv services`);
+        svc.dnsName = dnsName;
+      }
+      services.push(svc);
+    }
+  }
+
+  return {
+    instanceUrl: resolveInstanceUrl(env, tc),
+    siteId,
+    image: str(tc.image) ?? DEFAULT_IMAGE,
+    port: tc.port === undefined ? DEFAULT_PORT : port(tc.port, `${target}.port`),
+    externalHostname,
+    domain,
+    authRequired: tc.authRequired === true,
+    nvidia: tc.nvidia as boolean | undefined,
+    services,
+    sync: tc.sync !== false,
+    sshUser: str(env.MIEWEB_OS_SSH_USER) ?? str(tc.sshUser),
+    sshHost: str(tc.sshHost),
+    start: str(tc.start),
+  };
+}
diff --git a/packages/os-cloud-provider/src/credentials.ts b/packages/os-cloud-provider/src/credentials.ts
new file mode 100644
index 00000000..9e98936c
--- /dev/null
+++ b/packages/os-cloud-provider/src/credentials.ts
@@ -0,0 +1,75 @@
+/**
+ * Machine-local login cache: `~/.mieweb/os.json`, keyed by instance URL so a
+ * user can be logged into os.mieweb.org and a self-hosted instance at once
+ * (mirrors wrangler's `~/.wrangler` cache). Written 0600 in a 0700 directory.
+ *
+ * `MIEWEB_OS_CREDENTIALS` (from the provider env) overrides the file path.
+ */
+
+import { mkdir, readFile, rename, writeFile, chmod } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import type { ProviderEnv } from '@mieweb/deploy-contract';
+
+export interface StoredCredential {
+  token: string;
+  /** API key id, so `logout` can revoke it server-side. */
+  apiKeyId: string;
+  user?: string;
+  savedAt: string;
+}
+
+interface CredentialFile {
+  version: 1;
+  instances: Record<string, StoredCredential>;
+}
+
+export function credentialsPath(env: ProviderEnv): string {
+  const override = env.MIEWEB_OS_CREDENTIALS?.trim();
+  return override ? override : join(env.HOME?.trim() || homedir(), '.mieweb', 'os.json');
+}
+
+async function load(path: string): Promise<CredentialFile> {
+  let text: string;
+  try {
+    text = await readFile(path, 'utf8');
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return { version: 1, instances: {} };
+    throw err;
+  }
+  try {
+    const parsed = JSON.parse(text) as Partial<CredentialFile>;
+    return { version: 1, instances: { ...(parsed.instances ?? {}) } };
+  } catch {
+    throw new Error(`Credential cache ${path} is not valid JSON; delete it and run \`mieweb login\` again`);
+  }
+}
+
+async function save(path: string, data: CredentialFile): Promise<void> {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const tmp = `${path}.${process.pid}.tmp`;
+  await writeFile(tmp, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+  await chmod(tmp, 0o600);
+  await rename(tmp, path);
+}
+
+export async function readCredential(env: ProviderEnv, instanceUrl: string): Promise<StoredCredential | null> {
+  const data = await load(credentialsPath(env));
+  return data.instances[instanceUrl] ?? null;
+}
+
+export async function writeCredential(env: ProviderEnv, instanceUrl: string, cred: StoredCredential): Promise<void> {
+  const path = credentialsPath(env);
+  const data = await load(path);
+  data.instances[instanceUrl] = cred;
+  await save(path, data);
+}
+
+export async function deleteCredential(env: ProviderEnv, instanceUrl: string): Promise<boolean> {
+  const path = credentialsPath(env);
+  const data = await load(path);
+  if (!(instanceUrl in data.instances)) return false;
+  delete data.instances[instanceUrl];
+  await save(path, data);
+  return true;
+}
diff --git a/packages/os-cloud-provider/src/deploy.ts b/packages/os-cloud-provider/src/deploy.ts
new file mode 100644
index 00000000..aec37d41
--- /dev/null
+++ b/packages/os-cloud-provider/src/deploy.ts
@@ -0,0 +1,697 @@
+/**
+ * `deploy` / `destroy`: converge one container per app on a Manager site.
+ *
+ * Identity is the hostname (= wrangler.jsonc `name`), unique per site, so
+ * deploy is an upsert:
+ *
+ *   list_containers?hostname=<name>
+ *     ├─ none            → create_container (retry as update on 409 conflict)
+ *     ├─ same image/GPU  → update_container (services diff, full env, restart)
+ *     └─ image/GPU drift → delete_container + create_container
+ *                          (`template`/`nvidiaRequested` are create-only; the
+ *                          /mnt/data volume is retained on delete (#421), so
+ *                          datastore state survives the recreate)
+ *
+ * then poll the job and read the container back for the URL + VMID.
+ */
+
+import { randomBytes } from 'node:crypto';
+import type { DeployContext, DeployResult, ProviderEnv } from '@mieweb/deploy-contract';
+import type {
+  Container,
+  CreateContainerResult,
+  DeleteContainerResult,
+  EnvVar,
+  NewContainerForm,
+  ServiceUpdate,
+  UpdateContainerResult,
+  VolumeAttach,
+} from './api-types.ts';
+import { ManagerApiError, ManagerClient } from './client.ts';
+import {
+  appName,
+  ConfigError,
+  DATA_VOLUME,
+  resolveTargetSettings,
+  resolveToken,
+  type ExtraService,
+  type TargetSettings,
+} from './config.ts';
+import { sleep, waitForJob } from './jobs.ts';
+import type { SessionInfo } from './api-types.ts';
+import { forgetHostKey, knownHostsPath, SshConnection, SshError, ttyPrompter, waitForSsh, type Prompter, type RemoteShell, type SshTarget } from './ssh.ts';
+import { syncWorktree } from './sync.ts';
+
+/** Env keys the provider owns inside the converged container. */
+export const MANAGED_ENV = {
+  port: 'PORT',
+  target: 'MIEWEB_TARGET',
+  start: 'MIEWEB_APP_START',
+  minioUser: 'MINIO_ROOT_USER',
+  minioPassword: 'MINIO_ROOT_PASSWORD',
+  s3Endpoint: 'MIEWEB_S3_ENDPOINT',
+  s3AccessKey: 'MIEWEB_S3_ACCESS_KEY_ID',
+  s3SecretKey: 'MIEWEB_S3_SECRET_ACCESS_KEY',
+  libsqlUrl: 'MIEWEB_LIBSQL_URL',
+  valkeyUrl: 'MIEWEB_VALKEY_URL',
+} as const;
+
+/** Provider env vars with this prefix are injected (prefix stripped) as app secrets. */
+export const SECRET_ENV_PREFIX = 'MIEWEB_OS_SECRET_';
+
+/**
+ * Same normalization the Manager applies to `template` on create
+ * (normalizeDockerRef in routers/api/v1/containers.js), so a stored template
+ * can be compared with the configured image.
+ */
+export function normalizeImageRef(ref: string): string {
+  if (ref.startsWith('http://') || ref.startsWith('https://') || ref.startsWith('git@')) return ref;
+  let tag = 'latest';
+  let imagePart = ref;
+  const lastColon = ref.lastIndexOf(':');
+  if (lastColon !== -1) {
+    const potentialTag = ref.substring(lastColon + 1);
+    if (!potentialTag.includes('/')) {
+      tag = potentialTag;
+      imagePart = ref.substring(0, lastColon);
+    }
+  }
+  const parts = imagePart.split('/');
+  let host = 'docker.io';
+  let org = 'library';
+  let image: string;
+  if (parts.length === 1) {
+    image = parts[0]!;
+  } else if (parts.length === 2) {
+    if (parts[0]!.includes('.') || parts[0]!.includes(':')) {
+      host = parts[0]!;
+      image = parts[1]!;
+    } else {
+      org = parts[0]!;
+      image = parts[1]!;
+    }
+  } else {
+    host = parts[0]!;
+    image = parts[parts.length - 1]!;
+    org = parts.slice(1, -1).join('/');
+  }
+  return `${host}/${org}/${image}:${tag}`;
+}
+
+/** Pick the external domain to expose the app under. */
+export function pickDomain(form: NewContainerForm, wanted: string | number | undefined): { id: number; name: string } {
+  const domains = form.externalDomains ?? [];
+  if (wanted !== undefined) {
+    const hit = domains.find((d) => (typeof wanted === 'number' ? d.id === wanted : d.name === wanted));
+    if (!hit) {
+      const names = domains.map((d) => `${d.name} (${d.id})`).join(', ') || 'none';
+      throw new ConfigError(`External domain ${JSON.stringify(wanted)} is not available on this site (available: ${names})`);
+    }
+    return { id: hit.id, name: hit.name };
+  }
+  // The Manager sorts the site's own default domains first.
+  const first = domains[0];
+  if (!first) throw new ConfigError('The site has no external domains; ask an admin to add one, or set targets.mieweb.domain');
+  return { id: first.id, name: first.name };
+}
+
+function envString(v: unknown): string {
+  return typeof v === 'string' ? v : JSON.stringify(v);
+}
+
+export interface EnvInputs {
+  manifest: Readonly<Record<string, unknown>>;
+  env: ProviderEnv;
+  settings: Pick<TargetSettings, 'port' | 'start'>;
+  /** Current env map of the existing container (read shape is an object). */
+  existing?: Record<string, string>;
+  warn: (m: string) => void;
+}
+
+/**
+ * The complete desired env set. `update_container` treats `environmentVars`
+ * as a full replacement, so this always returns everything.
+ *
+ * Order of precedence (later wins): wrangler `vars` → MIEWEB_OS_SECRET_* from
+ * the provider env → provider-managed keys (warned on collision).
+ */
+export function buildEnv(inputs: EnvInputs): EnvVar[] {
+  const out = new Map<string, string>();
+  const vars = inputs.manifest.vars;
+  if (vars && typeof vars === 'object' && !Array.isArray(vars)) {
+    for (const [k, v] of Object.entries(vars)) out.set(k, envString(v));
+  }
+  for (const [k, v] of Object.entries(inputs.env)) {
+    if (k.startsWith(SECRET_ENV_PREFIX) && k.length > SECRET_ENV_PREFIX.length && v !== undefined) {
+      out.set(k.slice(SECRET_ENV_PREFIX.length), v);
+    }
+  }
+
+  // Reuse the generated MinIO secret: the data on /mnt/data was written with
+  // it, so it must survive redeploys and image-change recreates.
+  const minioPassword =
+    inputs.existing?.[MANAGED_ENV.minioPassword] || randomBytes(24).toString('base64url');
+  const minioUser = inputs.existing?.[MANAGED_ENV.minioUser] || 'mieweb';
+
+  const managed: [string, string | undefined][] = [
+    [MANAGED_ENV.port, String(inputs.settings.port)],
+    [MANAGED_ENV.target, 'mieweb'],
+    [MANAGED_ENV.start, inputs.settings.start],
+    [MANAGED_ENV.minioUser, minioUser],
+    [MANAGED_ENV.minioPassword, minioPassword],
+    [MANAGED_ENV.s3Endpoint, 'http://127.0.0.1:9000'],
+    [MANAGED_ENV.s3AccessKey, minioUser],
+    [MANAGED_ENV.s3SecretKey, minioPassword],
+    [MANAGED_ENV.libsqlUrl, 'http://127.0.0.1:8080'],
+    [MANAGED_ENV.valkeyUrl, 'redis://127.0.0.1:6379'],
+  ];
+  for (const [k, v] of managed) {
+    if (v === undefined) continue;
+    if (out.has(k) && out.get(k) !== v) inputs.warn(`Env var ${k} is managed by the provider; ignoring the app's value`);
+    out.set(k, v);
+  }
+  return [...out.entries()].map(([key, value]) => ({ key, value }));
+}
+
+export interface DesiredHttp {
+  internalPort: number;
+  externalHostname: string;
+  externalDomainId: number;
+  authRequired: boolean;
+}
+
+/**
+ * Diff the container's services against the desired set and produce an
+ * `update_container` services map.
+ *
+ * The provider owns the app's HTTP exposure: every HTTP service that doesn't
+ * match is removed. Non-HTTP services are only added (to match
+ * `targets.mieweb.services`), never removed — e.g. an SSH port someone added
+ * in the UI survives a redeploy.
+ */
+export function planServices(
+  current: Container['services'],
+  http: DesiredHttp,
+  extras: readonly ExtraService[],
+): Record<string, ServiceUpdate> {
+  const plan: Record<string, ServiceUpdate> = {};
+  let keptHttp = false;
+  for (const svc of current ?? []) {
+    if (svc.type !== 'http' || svc.id === undefined) continue;
+    const h = svc.httpService;
+    const matches =
+      !keptHttp &&
+      svc.internalPort === http.internalPort &&
+      h?.externalHostname === http.externalHostname &&
+      h?.externalDomainId === http.externalDomainId &&
+      (h?.backendProtocol ?? 'http') === 'http';
+    if (matches) {
+      keptHttp = true;
+      // Existing entries may only toggle authRequired.
+      plan[`keep-${svc.id}`] = { id: svc.id, type: 'http', internalPort: http.internalPort, authRequired: http.authRequired };
+    } else {
+      plan[`del-${svc.id}`] = { id: svc.id, deleted: true, type: 'http', internalPort: svc.internalPort ?? 0 };
+    }
+  }
+  if (!keptHttp) {
+    plan.http = {
+      type: 'http',
+      internalPort: http.internalPort,
+      externalHostname: http.externalHostname,
+      externalDomainId: http.externalDomainId,
+      authRequired: http.authRequired,
+    };
+  }
+
+  extras.forEach((want, i) => {
+    const exists = (current ?? []).some((svc) =>
+      want.type === 'srv'
+        ? svc.type === 'dns' && svc.internalPort === want.internalPort && svc.dnsService?.dnsName === want.dnsName
+        : svc.type === 'transport' && svc.internalPort === want.internalPort && svc.transportService?.protocol === want.type,
+    );
+    if (!exists) {
+      plan[`extra-${i}`] = { type: want.type, internalPort: want.internalPort, ...(want.dnsName ? { dnsName: want.dnsName } : {}) };
+    }
+  });
+  return plan;
+}
+
+/** The SSH service the code sync uses; always requested. */
+export const SSH_SERVICE: ExtraService = { type: 'tcp', internalPort: 22 };
+
+function withSsh(extras: readonly ExtraService[]): ExtraService[] {
+  return extras.some((e) => e.type === 'tcp' && e.internalPort === 22) ? [...extras] : [SSH_SERVICE, ...extras];
+}
+
+/** True when applying `plan` to `current` would change nothing. */
+export function servicesUnchanged(current: Container['services'], plan: Record<string, ServiceUpdate>): boolean {
+  return Object.entries(plan).every(([key, entry]) => {
+    if (!key.startsWith('keep-')) return false;
+    const svc = (current ?? []).find((c) => c.id === entry.id);
+    return (svc?.httpService?.authRequired ?? false) === (entry.authRequired ?? false);
+  });
+}
+
+export function envUnchanged(current: unknown, desired: readonly EnvVar[]): boolean {
+  const cur = asEnvMap(current);
+  return (
+    Object.keys(cur).length === desired.length && desired.every((e) => cur[e.key ?? ''] === (e.value ?? ''))
+  );
+}
+
+function createServices(http: DesiredHttp, extras: readonly ExtraService[]): Record<string, ServiceUpdate> {
+  return planServices([], http, extras);
+}
+
+function asEnvMap(v: unknown): Record<string, string> {
+  if (Array.isArray(v)) return Object.fromEntries(v.map((e: EnvVar) => [e.key ?? '', e.value ?? '']));
+  return v && typeof v === 'object' ? (v as Record<string, string>) : {};
+}
+
+/** Whether AI is bound in wrangler.jsonc (suggests a GPU node). */
+function wantsAi(manifest: Readonly<Record<string, unknown>>): boolean {
+  return manifest.ai !== undefined && manifest.ai !== null;
+}
+
+export interface ProviderDeps {
+  env: ProviderEnv;
+  fetch?: typeof fetch;
+  /** Job poll interval (tests shorten it). */
+  pollIntervalMs?: number;
+  /** Open the SSH session used for the code sync (tests inject a fake). */
+  connectSsh?: (target: SshTarget, opts: { knownHostsFile: string; signal: AbortSignal; logger: DeployContext['logger'] }) => Promise<RemoteShell>;
+  /** Wait for the SSH banner (tests inject a fake). */
+  waitForSsh?: typeof waitForSsh;
+  /** Terminal prompt for passphrases/passwords. */
+  prompt?: Prompter;
+  /** Total time to keep trying to reach SSH (default 60 s; tests shorten it). */
+  sshTimeoutMs?: number;
+  /** Delay between SSH connection attempts (default 2 s). */
+  sshRetryDelayMs?: number;
+}
+
+async function clientFor(ctx: DeployContext, deps: ProviderDeps, instanceUrl: string): Promise<ManagerClient> {
+  const tok = await resolveToken(deps.env, instanceUrl);
+  return new ManagerClient({ instanceUrl, token: tok?.token ?? null, target: ctx.target, signal: ctx.signal, fetch: deps.fetch });
+}
+
+async function findByHostname(client: ManagerClient, siteId: number, hostname: string): Promise<Container | null> {
+  const list = await client.get<Container[]>(`/sites/${siteId}/containers`, { hostname });
+  return list.find((c) => c.hostname === hostname) ?? null;
+}
+
+interface SiteSummary {
+  id: number;
+  name: string;
+}
+
+/**
+ * The site to deploy into when none is configured: the only site the user can
+ * see, otherwise ask on the terminal. Non-interactive runs get an error that
+ * lists the choices.
+ */
+export async function resolveSiteId(
+  configured: number | undefined,
+  client: ManagerClient,
+  deps: ProviderDeps,
+  ctx: DeployContext,
+): Promise<number> {
+  if (configured !== undefined) return configured;
+  const { logger, target } = ctx;
+  const sites = await client.get<SiteSummary[]>('/sites');
+  // Save the choice to mieweb.jsonc when the host supports it (CLI >= this
+  // contract); otherwise tell the user what to set.
+  const remember = async (site: SiteSummary, why: string): Promise<number> => {
+    logger.info(`Using site ${site.id} (${site.name})${why}`);
+    const saved = await ctx.persistTargetConfig?.({ siteId: site.id }).catch((err: unknown) => {
+      logger.warn(`Could not save siteId to mieweb.jsonc: ${err instanceof Error ? err.message : String(err)}`);
+      return false;
+    });
+    if (!saved) logger.info(`Set targets.${target}.siteId to ${site.id} in mieweb.jsonc (or MIEWEB_OS_SITE_ID) to skip this`);
+    return site.id;
+  };
+  if (sites.length === 0) throw new ConfigError('No Manager sites are visible to your account');
+  const [only] = sites;
+  if (sites.length === 1 && only) return remember(only, ', the only one available');
+  const list = sites.map((x) => `  ${x.id}) ${x.name}`).join('\n');
+  const prompt = deps.prompt ?? ttyPrompter;
+  for (;;) {
+    const answer = await prompt(`Manager sites:\n${list}\nSite to deploy into: `, false);
+    if (answer === null) {
+      throw new ConfigError(`targets.${target}.siteId is required (the Manager site to deploy into). Available:\n${list}`);
+    }
+    const pick = sites.find((x) => String(x.id) === answer.trim() || x.name === answer.trim());
+    if (pick) return remember(pick, '');
+    process.stderr.write(`"${answer.trim()}" is not one of the listed sites\n`);
+  }
+}
+
+export async function deploy(ctx: DeployContext, deps: ProviderDeps): Promise<DeployResult> {
+  const { logger, signal } = ctx;
+  const name = appName(ctx.manifest);
+  const s = resolveTargetSettings(ctx, deps.env);
+  const client = await clientFor(ctx, deps, s.instanceUrl);
+  const siteId = await resolveSiteId(s.siteId, client, deps, ctx);
+  const image = normalizeImageRef(s.image);
+  const wait = (jobId: number): Promise<void> =>
+    waitForJob(client, jobId, { signal, logger, intervalMs: deps.pollIntervalMs });
+
+  logger.info(`Deploying "${name}" to site ${siteId} on ${s.instanceUrl}`);
+  logger.info(`Image: ${image}`);
+
+  const form = await client.get<NewContainerForm>(`/sites/${siteId}/containers/new`);
+  const domain = pickDomain(form, s.domain);
+  let nvidia = s.nvidia ?? false;
+  if (s.nvidia === undefined && wantsAi(ctx.manifest)) {
+    nvidia = form.nvidiaAvailable;
+    logger.info(
+      nvidia
+        ? 'AI binding found; requesting an NVIDIA node'
+        : 'AI binding found but the site has no NVIDIA node; deploying without a GPU',
+    );
+  }
+
+  const extras = withSsh(s.services);
+  const http: DesiredHttp = {
+    internalPort: s.port,
+    externalHostname: s.externalHostname,
+    externalDomainId: domain.id,
+    authRequired: s.authRequired,
+  };
+  const envFor = (existing?: Container | null): EnvVar[] =>
+    buildEnv({
+      manifest: ctx.manifest,
+      env: deps.env,
+      settings: s,
+      existing: existing ? asEnvMap(existing.environmentVars) : undefined,
+      warn: (m) => logger.warn(m),
+    });
+
+  let existing = await findByHostname(client, siteId, name);
+  let carryEnv: Container | null = existing;
+
+  if (existing) {
+    // A create still in flight (e.g. a concurrent or interrupted deploy):
+    // let it finish before deciding anything.
+    if (!existing.containerId && existing.status === 'creating' && existing.creationJobId) {
+      logger.info(`Container ${existing.id} is still being created; waiting for job ${existing.creationJobId}`);
+      await waitForJob(client, existing.creationJobId, { signal, logger, intervalMs: deps.pollIntervalMs }).catch(() => {});
+      existing = await findByHostname(client, siteId, name);
+      carryEnv = existing;
+    }
+  }
+
+  if (existing) {
+    const drift: string[] = [];
+    if (!existing.containerId) {
+      // Never provisioned (failed/missing create); an update can't fix that.
+      drift.push(`not provisioned (status ${existing.status ?? 'unknown'})`);
+    }
+    if (existing.template && normalizeImageRef(existing.template) !== image) {
+      drift.push(`image ${existing.template} → ${image}`);
+    }
+    if (!!existing.nvidiaRequested !== nvidia) drift.push(`nvidia ${!!existing.nvidiaRequested} → ${nvidia}`);
+    if (drift.length > 0) {
+      logger.info(`Recreating container ${existing.id} (${drift.join(', ')}); ${DATA_VOLUME.mountPath} is retained`);
+      const del = await client.delete<DeleteContainerResult>(`/sites/${siteId}/containers/${existing.id}`);
+      for (const w of del.dnsWarnings ?? []) logger.warn(w);
+      existing = null;
+    }
+  }
+
+  let id: number;
+  // Set when this deploy (re)created the container: its SSH host key is new.
+  let fresh = false;
+  if (!existing) {
+    const created = await createOrAdopt(client, siteId, s, name, image, nvidia, envFor(carryEnv), http, logger);
+    if ('created' in created) {
+      id = created.created.containerId;
+      fresh = true;
+      logger.info(`Created container ${id}; waiting for job ${created.created.jobId}`);
+      await wait(created.created.jobId);
+    } else {
+      // Lost a concurrent-create race: someone else created the same hostname
+      // between our list and create. Converge it with an update instead.
+      existing = created.adopted;
+      carryEnv = existing;
+    }
+  }
+
+  if (existing) {
+    id = existing.id!;
+    const services = planServices(existing.services, http, extras);
+    const environmentVars = envFor(carryEnv);
+    const body: Record<string, unknown> = {
+      services,
+      environmentVars,
+      entrypoint: existing.entrypoint ?? null,
+      restart: true,
+    };
+    let changed = !servicesUnchanged(existing.services, services) || !envUnchanged(existing.environmentVars, environmentVars);
+    if (existing.volumes === undefined) {
+      // Manager predates volumes (#421): it neither reports nor accepts them.
+      logger.warn(
+        `This Manager does not support volumes; ${DATA_VOLUME.mountPath} is not persistent and datastore state will not survive a container recreate`,
+      );
+    } else if (!existing.volumes.some((v) => v.mountPath === DATA_VOLUME.mountPath)) {
+      body.volumes = [DATA_VOLUME satisfies VolumeAttach];
+      changed = true;
+      logger.info(`Attaching the ${DATA_VOLUME.mountPath} data volume`);
+    } else if ((existing.volumes ?? []).some((v) => v.mountPath === DATA_VOLUME.mountPath && v.mode !== 'rw')) {
+      logger.warn(`${DATA_VOLUME.mountPath} is attached read-only; the datastores need it read-write`);
+    }
+    // Code-only redeploys skip the Manager entirely and just sync.
+    if (changed) {
+    const upd = await client.put<UpdateContainerResult>(`/sites/${siteId}/containers/${id}`, body);
+    for (const w of upd.dnsWarnings ?? []) logger.warn(w);
+    if (upd.jobId) {
+      logger.info(`Updated container ${id}; waiting for job ${upd.jobId}`);
+      await wait(upd.jobId);
+    } else {
+      logger.info(`Updated container ${id}${upd.message ? `: ${upd.message}` : ''}`);
+    }
+    } else {
+      logger.info(`Container ${id} configuration is up to date`);
+    }
+  }
+
+  const final = await client.get<Container>(`/sites/${siteId}/containers/${id!}`);
+  if (!final.containerId) {
+    throw new Error(`Container ${id!} has no hypervisor id after the job finished (status: ${final.status ?? 'unknown'})`);
+  }
+  const url =
+    final.httpEntries?.find((e) => e.port === s.port && e.externalUrl)?.externalUrl ??
+    final.httpEntries?.find((e) => e.externalUrl)?.externalUrl ??
+    undefined;
+
+  if (s.sync) {
+    if (!final.sshPort || !(s.sshHost ?? final.sshHost)) {
+      throw new Error(`Container ${id!} has no published SSH port/host; cannot sync code (set targets.${ctx.target}.sync to false to skip)`);
+    }
+    const shell = await openShell(ctx, deps, client, s, final, { fresh });
+    try {
+      await syncWorktree(ctx.root, shell, logger, signal);
+    } finally {
+      shell.close();
+    }
+  } else {
+    logger.info('Code sync disabled (sync: false)');
+  }
+
+  if (url) logger.info(`Live at ${url}`);
+  return {
+    ...(url ? { url } : {}),
+    resources: [{ binding: name, kind: 'container', id: String(final.containerId) }],
+  };
+}
+
+/** Open an SSH session to the container (waiting for SSH to come up). */
+export async function openShell(
+  ctx: DeployContext,
+  deps: ProviderDeps,
+  client: ManagerClient,
+  s: TargetSettings,
+  container: Container,
+  opts: { fresh?: boolean } = {},
+): Promise<RemoteShell> {
+  const { logger, signal } = ctx;
+  const port = container.sshPort;
+  const host = s.sshHost ?? container.sshHost ?? undefined;
+  if (!port || !host) throw new Error(`Container ${container.id} has no published SSH port/host`);
+  const user = s.sshUser ?? (await client.get<SessionInfo>('/session')).user;
+  const target: SshTarget = { host, port, user };
+  const knownHostsFile = knownHostsPath(deps.env);
+  if (opts.fresh) await forgetHostKey(knownHostsFile, host, port);
+
+  // A freshly created/rebuilt container can take a while before sshd answers,
+  // accepts connections reliably, and (via SSSD) serves the user's LDAP keys.
+  // Keep retrying transient failures within one overall budget.
+  const budgetMs = deps.sshTimeoutMs ?? 60_000;
+  const delayMs = deps.sshRetryDelayMs ?? 2000;
+  const deadline = Date.now() + budgetMs;
+  const remaining = (): number => Math.max(0, deadline - Date.now());
+  // Ask for a password/passphrase at most once across attempts.
+  const answers = new Map<string, string | null>();
+  const basePrompt = deps.prompt ?? ttyPrompter;
+  const prompt: Prompter = async (q, hidden) => {
+    if (!answers.has(q)) answers.set(q, await basePrompt(q, hidden));
+    return answers.get(q)!;
+  };
+
+  logger.info(`Connecting to ${user}@${host}:${port}`);
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      await (deps.waitForSsh ?? waitForSsh)(host, port, signal, logger, Math.max(remaining(), 1000));
+      const attemptTimeout = Math.min(20_000, Math.max(remaining(), 5000));
+      return await (deps.connectSsh
+        ? deps.connectSsh(target, { knownHostsFile, signal, logger })
+        : SshConnection.connect({ target, env: deps.env, knownHostsFile, prompt, signal, logger, timeoutMs: attemptTimeout }));
+    } catch (err) {
+      if (signal.aborted) throw err;
+      const kind = err instanceof SshError ? err.kind : 'network';
+      // Auth failures are only plausibly transient right after (re)creation.
+      const retryable = kind === 'network' || (kind === 'auth' && opts.fresh === true);
+      if (!retryable || remaining() <= delayMs) {
+        if (retryable && attempt > 1) {
+          throw new Error(
+            `SSH on ${host}:${port} was not usable within ${Math.round(budgetMs / 1000)}s (${attempt} attempts): ${(err as Error).message}`,
+            { cause: err },
+          );
+        }
+        throw err;
+      }
+      logger.info(`SSH not ready yet (${(err as Error).message.split('. ')[0]}); retrying…`);
+      await sleep(delayMs, signal);
+    }
+  }
+}
+
+export interface TailOptions {
+  lines: number;
+  follow: boolean;
+  since?: string;
+}
+
+/** Parse `mieweb tail` passthrough args: `-n/--lines N`, `--no-follow`, `--since <time>`. */
+export function parseTailArgs(argv: readonly string[]): TailOptions {
+  const out: TailOptions = { lines: 100, follow: true };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]!;
+    const val = (): string => {
+      const eq = a.indexOf('=');
+      if (eq !== -1) return a.slice(eq + 1);
+      const v = argv[++i];
+      if (v === undefined) throw new ConfigError(`${a} needs a value`);
+      return v;
+    };
+    if (a === '-n' || a === '--lines' || a.startsWith('--lines=')) {
+      const n = Number(val());
+      if (!Number.isInteger(n) || n < 0) throw new ConfigError(`${a} must be a non-negative integer`);
+      out.lines = n;
+    } else if (a === '--no-follow') out.follow = false;
+    else if (a === '--since' || a.startsWith('--since=')) {
+      const v = val();
+      // journalctl accepts e.g. "2026-10-01 12:00", "-1h", "yesterday".
+      if (!/^[A-Za-z0-9 :+.-]{1,40}$/.test(v)) throw new ConfigError(`--since value ${JSON.stringify(v)} is not a valid time`);
+      out.since = v;
+    } else throw new ConfigError(`Unknown tail option ${JSON.stringify(a)} (supported: -n/--lines N, --no-follow, --since <time>)`);
+  }
+  return out;
+}
+
+export function journalCommand(o: TailOptions): string {
+  const args = ['sudo', 'journalctl', '-u', 'app.service', '-o', 'cat', '--no-pager', '-n', String(o.lines)];
+  if (o.since) args.push('--since', `'${o.since}'`);
+  if (o.follow) args.push('-f');
+  return args.join(' ');
+}
+
+/** `mieweb tail`: stream app.service's journal until aborted (or the end, with --no-follow). */
+export async function tail(ctx: DeployContext, deps: ProviderDeps): Promise<void> {
+  const opts = parseTailArgs(ctx.argv);
+  const name = appName(ctx.manifest);
+  const s = resolveTargetSettings(ctx, deps.env);
+  const client = await clientFor(ctx, deps, s.instanceUrl);
+  const siteId = await resolveSiteId(s.siteId, client, deps, ctx);
+  const found = await findByHostname(client, siteId, name);
+  if (!found) throw new Error(`No container "${name}" on site ${siteId}; run \`mieweb deploy\` first`);
+  const container = await client.get<Container>(`/sites/${siteId}/containers/${found.id}`);
+  const shell = await openShell(ctx, deps, client, s, container);
+  try {
+    ctx.logger.info(`Tailing app.service on "${name}"${opts.follow ? ' (Ctrl-C to stop)' : ''}`);
+    // Re-split chunks into whole lines so each log line is one logger call.
+    const pending = { stdout: '', stderr: '' };
+    const emit = (line: string, which: 'stdout' | 'stderr'): void =>
+      which === 'stderr' ? ctx.logger.warn(line) : ctx.logger.info(line);
+    const code = await shell.stream(
+      journalCommand(opts),
+      (chunk, which) => {
+        const lines = (pending[which] + chunk.toString('utf8')).split('\n');
+        pending[which] = lines.pop() ?? '';
+        for (const l of lines) emit(l, which);
+      },
+      ctx.signal,
+    );
+    for (const which of ['stdout', 'stderr'] as const) if (pending[which]) emit(pending[which], which);
+    if (code > 0) throw new Error(`journalctl exited with code ${code}`);
+  } finally {
+    shell.close();
+  }
+}
+
+async function createOrAdopt(
+  client: ManagerClient,
+  siteId: number,
+  s: TargetSettings,
+  name: string,
+  image: string,
+  nvidia: boolean,
+  environmentVars: EnvVar[],
+  http: DesiredHttp,
+  logger: DeployContext['logger'],
+): Promise<{ created: CreateContainerResult } | { adopted: Container }> {
+  try {
+    const created = await client.post<CreateContainerResult>(`/sites/${siteId}/containers`, {
+      hostname: name,
+      template: image,
+      nvidiaRequested: nvidia,
+      environmentVars,
+      volumes: [DATA_VOLUME],
+      services: createServices(http, withSsh(s.services)),
+    });
+    return { created };
+  } catch (err) {
+    if (!(err instanceof ManagerApiError) || err.status !== 409 || err.code !== 'conflict') throw err;
+    const adopted = await findByHostname(client, siteId, name);
+    if (!adopted) {
+      throw new Error(
+        `Hostname "${name}" is already taken on site ${siteId} by a container you cannot manage; ` +
+          'rename the app (wrangler.jsonc `name`) or ask its owner to delete it.',
+        { cause: err },
+      );
+    }
+    logger.info(`Container "${name}" was created concurrently; updating it instead`);
+    return { adopted };
+  }
+}
+
+export async function destroy(ctx: DeployContext, deps: ProviderDeps): Promise<void> {
+  const name = appName(ctx.manifest);
+  const s = resolveTargetSettings(ctx, deps.env);
+  const client = await clientFor(ctx, deps, s.instanceUrl);
+  const siteId = await resolveSiteId(s.siteId, client, deps, ctx);
+  const existing = await findByHostname(client, siteId, name);
+  if (!existing) {
+    ctx.logger.info(`No container "${name}" on site ${siteId}; nothing to destroy`);
+    return;
+  }
+  const res = await client.delete<DeleteContainerResult>(`/sites/${siteId}/containers/${existing.id}`);
+  for (const w of res.dnsWarnings ?? []) ctx.logger.warn(w);
+  const retained = (existing.volumes ?? []).some((v) => v.mountPath === DATA_VOLUME.mountPath);
+  ctx.logger.info(
+    `Destroyed container "${name}" (${existing.id}).` +
+      (retained
+        ? ` The ${DATA_VOLUME.mountPath} data directory is retained on the node and is reattached if you deploy the same name again.`
+        : ''),
+  );
+}
diff --git a/packages/os-cloud-provider/src/generated/manager-api.ts b/packages/os-cloud-provider/src/generated/manager-api.ts
new file mode 100644
index 00000000..c235e225
--- /dev/null
+++ b/packages/os-cloud-provider/src/generated/manager-api.ts
@@ -0,0 +1,4184 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+
+export interface paths {
+    "/csrf-token": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Get a CSRF token */
+        get: operations["get_csrf_token"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/health": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Health check */
+        get: operations["get_health"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/openapi.json": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** This OpenAPI specification (JSON) */
+        get: operations["get_openapi_json"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/openapi.yaml": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** This OpenAPI specification (YAML) */
+        get: operations["get_openapi_yaml"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/session": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Current session */
+        get: operations["get_session"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/auth/login": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Username/password login (disabled when OIDC SSO is enabled) */
+        post: operations["login"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/auth/oidc/login": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Begin OIDC single sign-on (redirects to the identity provider) */
+        get: operations["oidc_login"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/auth/oidc/callback": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** OIDC authorization-code callback (completes SSO and starts a session) */
+        get: operations["oidc_callback"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/auth/cli/callback": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * CLI loopback login — browser confirmation page
+         * @description Browser-facing (HTML), used by `mieweb login`. Without a session, it redirects through the normal sign-in (OIDC or /login) and comes back here. With a session, it renders a confirmation form that POSTs back to this path. A GET never mints a key.
+         */
+        get: operations["cli_login_authorize"];
+        put?: never;
+        /**
+         * CLI loopback login — mint an API key and hand it to the loopback listener
+         * @description Requires a browser session and a CSRF token (`_csrf`). Bearer-only requests are rejected. Mints an API key for the session user and 303-redirects to `http://127.0.0.1:<port>/callback#key=…&id=…&user=…&state=…`. The key is in the URL fragment, so it never appears in a request line.
+         */
+        post: operations["cli_login_mint"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/auth/logout": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Log out (clears the session; returns an IdP end-session URL when OIDC is enabled) */
+        post: operations["logout"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/auth/register": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Self-register (disabled when OIDC SSO is enabled) */
+        post: operations["register"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/auth/register/invite/{token}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Validate an invitation token */
+        get: operations["validate_invite"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/auth/password-reset/request": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations["request_password_reset"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/auth/password-reset/{token}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["validate_password_reset_token"];
+        put?: never;
+        post: operations["reset_password"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sites": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List sites */
+        get: operations["list_sites"];
+        put?: never;
+        /** Create a site (admin) */
+        post: operations["create_site"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sites/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: number;
+            };
+            cookie?: never;
+        };
+        get: operations["get_site"];
+        /** Update a site (admin). Full update — omitted optional fields are cleared. */
+        put: operations["update_site"];
+        post?: never;
+        /** Delete a site (admin) */
+        delete: operations["delete_site"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sites/{siteId}/containers": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["list_containers"];
+        put?: never;
+        post: operations["create_container"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sites/{siteId}/containers/new": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Form bootstrap data (domains + NVIDIA flag) */
+        get: operations["get_new_container_form"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sites/{siteId}/containers/metadata": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Fetch Docker image metadata */
+        get: operations["get_image_metadata"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sites/{siteId}/containers/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                siteId: number;
+                id: number;
+            };
+            cookie?: never;
+        };
+        get: operations["get_container"];
+        /** Update services/env/entrypoint; enqueues a restart job only when explicitly requested (owner/admin) */
+        put: operations["update_container"];
+        post?: never;
+        delete: operations["delete_container"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sites/{siteId}/containers/{id}/collaborators": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                siteId: number;
+                id: number;
+            };
+            cookie?: never;
+        };
+        /** List users a container is shared with (owner/collaborator/admin) */
+        get: operations["list_container_collaborators"];
+        put?: never;
+        /** Share a container with another user (owner/admin). Idempotent — sharing with an existing collaborator is a no-op. */
+        post: operations["add_container_collaborator"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sites/{siteId}/containers/{id}/collaborators/{username}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        /** Stop sharing a container with a user (owner/admin) */
+        delete: operations["remove_container_collaborator"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sites/{siteId}/nodes": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                siteId: number;
+            };
+            cookie?: never;
+        };
+        get: operations["list_nodes"];
+        put?: never;
+        /** Create a node (admin) */
+        post: operations["create_node"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sites/{siteId}/nodes/import": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Bulk-import nodes + containers from a Proxmox cluster (admin) */
+        post: operations["import_nodes"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sites/{siteId}/nodes/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                siteId: number;
+                id: number;
+            };
+            cookie?: never;
+        };
+        get: operations["get_node"];
+        /** Update a node (admin). Full update — omitted fields are reset to defaults/null (except `secret`, which is kept when blank/omitted, and `nodeType`, which keeps its current value). */
+        put: operations["update_node"];
+        post?: never;
+        /** Delete a node (admin) */
+        delete: operations["delete_node"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sites/{siteId}/nodes/{id}/storages": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List Proxmox CT template storages (empty array when the node has no API credentials or the query fails) */
+        get: operations["list_node_storages"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sites/{siteId}/nodes/{id}/stats": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Live hardware utilization (CPU/memory/swap/rootfs, uptime) plus per-datastore usage */
+        get: operations["get_node_stats"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sites/{siteId}/usage": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Live per-owner resource usage report (allocated vs used), computed from one Proxmox cluster-resources call per cluster
+         * @description Admins see every owner on the site; other users see their own containers plus containers shared with them. `findings` (owner-tag vs DB attribution drift, unattributed containers) and `unknownNodeRows` are admin-only.
+         */
+        get: operations["get_site_usage"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/jobs/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: number;
+            };
+            cookie?: never;
+        };
+        /** Job metadata (creator or admin; others receive 404) */
+        get: operations["get_job"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/jobs/{id}/status": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["get_job_status"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/jobs/{id}/stream": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Server-sent events stream of job output */
+        get: operations["stream_job_output"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/agents": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Current status of all agents (admin) */
+        get: operations["list_agents"];
+        put?: never;
+        /**
+         * Agent check-in
+         * @description Site agents POST their system info, per-service status, and per-volume
+         *     directory-provisioning results every 30 seconds. The response carries
+         *     the site's config snapshot with a strong `ETag`; send it back via
+         *     `If-None-Match` to receive `304 Not Modified` when nothing changed.
+         *     Allowed from localhost without credentials (manager bootstrap) or with
+         *     an admin API key. Exempt from the CSRF guard.
+         */
+        post: operations["agent_check_in"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/notifications": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List the current user's notifications
+         * @description Owner-scoped feed for the notification bell. Returned unacknowledged
+         *     first, then newest first, so the client can derive its unread badge from
+         *     the response.
+         */
+        get: operations["list_notifications"];
+        put?: never;
+        /**
+         * Ingest a node-side event (admin API key)
+         * @description Inbound webhook for node-side tools (e.g. lxc-oomd) to report events.
+         *     Requires an admin API key (Bearer). The event is persisted and surfaced
+         *     per owner in the UI notification bell. When `owner` is omitted it is
+         *     resolved best-effort from `node` + `ctid` via the Containers table; an
+         *     unresolved owner is stored as null and appears in no user's feed. `ts`
+         *     is epoch seconds and is recorded as `eventAt`. See
+         *     docs/notification-webhook.md for the full contract.
+         */
+        post: operations["ingest_notification"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/notifications/all/ack": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Acknowledge all of the caller's notifications */
+        post: operations["acknowledge_all_notifications"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/notifications/{id}/ack": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: number;
+            };
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Acknowledge one notification the caller owns */
+        post: operations["acknowledge_notification"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/services/{id}/last-access": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Record service access (proxy accounting)
+         * @description Called by the site proxy (nginx accounting module) on the first
+         *     request/connection to a service after 10+ minutes of none. Sets the
+         *     service's lastAccessedAt to the current server time. Allowed from
+         *     localhost without credentials (manager bootstrap) or with an admin
+         *     API key. Exempt from the CSRF guard for Bearer/localhost callers.
+         */
+        post: operations["record_service_access"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/external-domains": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List external domains (admin) */
+        get: operations["list_external_domains"];
+        put?: never;
+        /** Create an external domain (admin) */
+        post: operations["create_external_domain"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/external-domains/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: number;
+            };
+            cookie?: never;
+        };
+        get: operations["get_external_domain"];
+        /** Update an external domain (admin). Full update — omitted optional fields are cleared (except `cloudflareApiKey`, which is kept when blank/omitted). */
+        put: operations["update_external_domain"];
+        post?: never;
+        /** Delete an external domain (admin) */
+        delete: operations["delete_external_domain"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/users": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List users (admin) */
+        get: operations["list_users"];
+        put?: never;
+        /** Create a user (admin) */
+        post: operations["create_user"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/users/invite": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Send an email invitation (admin) */
+        post: operations["invite_user"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/users/email-all": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Broadcast an email to every user with an address (admin) */
+        post: operations["email_all_users"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/users/{uidNumber}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                uidNumber: number;
+            };
+            cookie?: never;
+        };
+        get: operations["get_user"];
+        /** Update a user (admin). Partial — omitted/blank fields keep their current values. */
+        put: operations["update_user"];
+        post?: never;
+        /** Delete a user (admin) */
+        delete: operations["delete_user"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/groups": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List groups (admin) */
+        get: operations["list_groups"];
+        put?: never;
+        /** Create a group (admin) */
+        post: operations["create_group"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/groups/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description gidNumber */
+                id: number;
+            };
+            cookie?: never;
+        };
+        get: operations["get_group"];
+        /** Update a group (admin) */
+        put: operations["update_group"];
+        post?: never;
+        /** Delete a group (admin) */
+        delete: operations["delete_group"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/apikeys": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List the current user's API keys */
+        get: operations["list_api_keys"];
+        put?: never;
+        /** Mint a new API key (plaintext returned ONCE) */
+        post: operations["create_api_key"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/apikeys/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        get: operations["get_api_key"];
+        put?: never;
+        post?: never;
+        delete: operations["delete_api_key"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/settings": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Read system settings (admin) */
+        get: operations["get_settings"];
+        /** Save system settings (admin). Full update — omitted fields are cleared. */
+        put: operations["update_settings"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/resource-requests": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List resource requests (admins see all; users see only their own) */
+        get: operations["list_resource_requests"];
+        put?: never;
+        /** Request a resource adjustment for a container. Auto-approved (and applied to matching provisioned containers) when the caller is an admin or the value is at or below the default (memory 4096 MB, swap 0 MB, cpus 4, rootfs 50 GB); otherwise left pending for admin review. */
+        post: operations["create_resource_request"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/resource-requests/count": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Count pending resource requests (for badge display) */
+        get: operations["count_pending_resource_requests"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/resource-requests/effective/{siteId}/{hostname}/{username}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Effective approved resources for a container identity (defaults merged with the most recent approval per type) */
+        get: operations["get_effective_resources"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/resource-requests/{id}/approve": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        /** Approve a pending request and apply it to matching provisioned containers (admin) */
+        put: operations["approve_resource_request"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/resource-requests/{id}/deny": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        /** Deny a pending request (admin) */
+        put: operations["deny_resource_request"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        Error: {
+            error: {
+                code: string;
+                message: string;
+                fields?: {
+                    [key: string]: string;
+                };
+            };
+        };
+        DataWrap: {
+            data: unknown;
+        };
+        Notification: {
+            id?: number;
+            /** @description Emitter of the event */
+            source?: string;
+            /** @enum {string} */
+            severity?: "info" | "warning" | "critical";
+            /** @description Hypervisor node name */
+            node?: string | null;
+            /** @description Container id on the hypervisor (CTID/VMID) */
+            ctid?: string | null;
+            /** @description Owning user (Users.uid); drives per-user visibility */
+            owner?: string | null;
+            /** @description freeze | kill | bump | quarantine | detect | ... */
+            action?: string | null;
+            message?: string;
+            evidence?: {
+                [key: string]: unknown;
+            } | null;
+            /**
+             * Format: date-time
+             * @description When the event happened on the node
+             */
+            eventAt?: string | null;
+            /** Format: date-time */
+            acknowledgedAt?: string | null;
+            acknowledgedBy?: string | null;
+            /** Format: date-time */
+            createdAt?: string;
+            /** Format: date-time */
+            updatedAt?: string;
+        };
+        Site: {
+            id?: number;
+            name?: string;
+            internalDomain?: string;
+            dhcpRange?: string;
+            subnetMask?: string;
+            gateway?: string;
+            dnsForwarders?: string;
+            externalIp?: string | null;
+            /** @description Number of nodes in the site. Present on list/show responses; absent from create/update responses. */
+            nodeCount?: number;
+        };
+        SiteInput: {
+            name?: string;
+            internalDomain?: string;
+            dhcpRange?: string;
+            subnetMask?: string;
+            gateway?: string;
+            dnsForwarders?: string;
+            externalIp?: string | null;
+        };
+        Container: {
+            id?: number;
+            hostname?: string;
+            /** @description Username of the user who created the container */
+            owner?: string;
+            /** @description Usernames the container is shared with */
+            collaborators?: string[];
+            /** @description Provider container id — Proxmox VMID or Docker container id (null until provisioned) */
+            containerId?: string | null;
+            status?: components["schemas"]["ContainerStatus"];
+            template?: string;
+            ipv4Address?: string | null;
+            macAddress?: string | null;
+            creationJobId?: number | null;
+            entrypoint?: string | null;
+            environmentVars?: {
+                [key: string]: string;
+            };
+            nvidiaRequested?: boolean;
+            /** @description External port of the TCP service on internal port 22, if any */
+            sshPort?: number | null;
+            /** @description Hostname to use with sshPort when connecting over SSH, falling back to the site external IP */
+            sshHost?: string | null;
+            /** @description One entry per HTTP service */
+            httpEntries?: {
+                port?: number;
+                externalUrl?: string | null;
+            }[];
+            /**
+             * Format: date-time
+             * @description Most recent proxy-reported access across the container's services (max of the services' lastAccessedAt). Null when never accessed.
+             */
+            lastAccessedAt?: string | null;
+            nodeName?: string | null;
+            nodeApiUrl?: string | null;
+            volumes?: components["schemas"]["Volume"][];
+            services?: components["schemas"]["ContainerService"][];
+            /** Format: date-time */
+            createdAt?: string;
+        };
+        ContainerService: {
+            id?: number;
+            /** @enum {string} */
+            type?: "http" | "transport" | "dns";
+            internalPort?: number;
+            /**
+             * Format: date-time
+             * @description Set when the site proxy reports traffic to this service — at most once per 10 minutes per service. Null when never accessed.
+             */
+            lastAccessedAt?: string | null;
+            httpService?: {
+                id?: number;
+                externalHostname?: string;
+                externalDomainId?: number;
+                /** @enum {string} */
+                backendProtocol?: "http" | "https";
+                authRequired?: boolean;
+                domain?: string | null;
+            } | null;
+            transportService?: {
+                id?: number;
+                /** @enum {string} */
+                protocol?: "tcp" | "udp";
+                externalPort?: number;
+            } | null;
+            dnsService?: {
+                id?: number;
+                /** @enum {string} */
+                recordType?: "SRV";
+                dnsName?: string;
+            } | null;
+        };
+        /**
+         * @description Live container status, resolved on read from Proxmox run-state and the create job. running = online in Proxmox; offline = exists in Proxmox but stopped; creating = no Proxmox VM yet, active create job; failed = no Proxmox VM, create job failed; missing = no Proxmox VM, create succeeded or no create job; unknown = Proxmox unreachable / no node credentials.
+         * @enum {string}
+         */
+        ContainerStatus: "running" | "offline" | "creating" | "failed" | "missing" | "unknown";
+        ServiceInput: {
+            /**
+             * @description http/https create an HTTP service (https sets backendProtocol to https); srv creates a DNS SRV service; tcp/udp create a transport service with an auto-assigned external port.
+             * @enum {string}
+             */
+            type: "http" | "https" | "tcp" | "udp" | "srv";
+            internalPort: number;
+            /** @description Required for http/https */
+            externalHostname?: string;
+            /** @description Required for http/https */
+            externalDomainId?: number;
+            /** @description Required for srv */
+            dnsName?: string;
+            authRequired?: boolean;
+        };
+        ServiceUpdate: components["schemas"]["ServiceInput"] & {
+            /** @description Existing service id. Omit to create a new service. */
+            id?: number;
+            /** @description true deletes the service identified by `id` */
+            deleted?: boolean;
+        };
+        EnvVar: {
+            key?: string;
+            value?: string;
+        };
+        /** @description A container bind-mount volume (issue #421). Host directories are created by the site agent and attached as Proxmox mpN bind mounts. On Docker nodes, volumes map to Docker binds. */
+        Volume: {
+            id?: number;
+            /** @description Safe path segment; no traversal/separators */
+            name?: string;
+            /** @description Absolute guest mount point (e.g. /mnt/data) */
+            mountPath?: string;
+            /** @enum {string} */
+            mode?: "ro" | "rw";
+            /** @description Currently always `container` (per-container). Per-user/site/node is a later extension. */
+            scope?: string;
+            /** @description True only for the retired quick_and_dirty mount recorded on pre-existing containers. Never set on new volumes and never re-applied. */
+            builtin?: boolean;
+            /**
+             * @description Directory-readiness lifecycle. `pending` until the site agent creates the host directory, then `ready`; `failed` on a mkdir/chown error (see statusMessage). The create job blocks on `ready` before attaching the mount.
+             * @enum {string}
+             */
+            status?: "pending" | "ready" | "failed";
+            /** @description Agent error detail when status is failed */
+            statusMessage?: string | null;
+            /** Format: date-time */
+            appliedAt?: string | null;
+        };
+        /** @description A volume to attach. `hostPath` is NOT accepted from clients — it is derived server-side from the node storage's configured path. */
+        VolumeAttach: {
+            /** @description Safe path segment (letters, digits, dot, dash, underscore) */
+            name: string;
+            /** @description Absolute guest mount point; no provider delimiters (comma/colon), backslashes, whitespace, control chars, or . / .. segments */
+            mountPath: string;
+            /** @enum {string} */
+            mode: "ro" | "rw";
+        };
+        /** @description Detach an existing volume by id (update only). */
+        VolumeDetach: {
+            /** @description Existing volume id to detach */
+            id: number;
+            /**
+             * @description Must be true to detach
+             * @enum {boolean}
+             */
+            detach: true;
+        };
+        /** @description A single volume change on update: either an attach (`{ name, mountPath, mode }`) or a detach (`{ id, detach: true }`). */
+        VolumeChange: components["schemas"]["VolumeAttach"] | components["schemas"]["VolumeDetach"];
+        Node: {
+            id?: number;
+            name?: string;
+            /** @enum {string} */
+            nodeType?: "proxmox" | "dummy" | "docker";
+            siteId?: number;
+            ipv4Address?: string | null;
+            /** @description Proxmox API URL or Docker host, e.g. unix:///var/run/docker.sock, tcp://host:2375, http://host:2375, https://host:2376 */
+            apiUrl?: string | null;
+            tokenId?: string | null;
+            tlsVerify?: boolean | null;
+            imageStorage?: string;
+            volumeStorage?: string;
+            networkBridge?: string;
+            nvidiaAvailable?: boolean;
+            hasSecret?: boolean;
+            /** @description Advisory warnings from the last save (create/update), e.g. the volume storage is not shared across the cluster (issue #421). Present on create/update responses only. */
+            warnings?: string[];
+        };
+        NodeInput: {
+            name: string;
+            /**
+             * @default proxmox
+             * @enum {string}
+             */
+            nodeType: "proxmox" | "dummy" | "docker";
+            ipv4Address?: string | null;
+            /** @description Proxmox API URL or Docker host, e.g. unix:///var/run/docker.sock, tcp://host:2375, http://host:2375, https://host:2376. Required (and validated) when nodeType is docker. */
+            apiUrl?: string | null;
+            tokenId?: string | null;
+            /** @description Proxmox API token secret. Never returned (see `hasSecret`). On update, blank/omitted keeps the existing secret. */
+            secret?: string;
+            tlsVerify?: boolean | null;
+            /** @default local */
+            imageStorage: string;
+            /** @default local-lvm */
+            volumeStorage: string;
+            /** @default vmbr0 */
+            networkBridge: string;
+            /** @default false */
+            nvidiaAvailable: boolean;
+        };
+        Job: {
+            id?: number;
+            command?: string;
+            /** @enum {string} */
+            status?: "pending" | "running" | "success" | "failure" | "cancelled";
+            createdBy?: string;
+            /** Format: date-time */
+            createdAt?: string;
+            /** Format: date-time */
+            updatedAt?: string;
+        };
+        JobStatusRow: {
+            id?: number;
+            jobId?: number;
+            output?: string | null;
+            /** Format: date-time */
+            createdAt?: string;
+            /** Format: date-time */
+            updatedAt?: string;
+        };
+        ApiKey: {
+            /** Format: uuid */
+            id?: string;
+            keyPrefix?: string;
+            description?: string | null;
+            /** Format: date-time */
+            lastUsedAt?: string | null;
+            /** Format: date-time */
+            createdAt?: string;
+            /** Format: date-time */
+            updatedAt?: string;
+        };
+        User: {
+            uidNumber?: number;
+            /** @description Username */
+            uid?: string;
+            givenName?: string;
+            sn?: string;
+            /** @description Full name (derived from givenName + sn) */
+            cn?: string;
+            /** Format: email */
+            mail?: string;
+            /** @description Account status: `pending` until approved, `active` allows login */
+            status?: string;
+            /** @description Present when group memberships are loaded */
+            groups?: {
+                gidNumber?: number;
+                cn?: string;
+                isAdmin?: boolean;
+            }[];
+            isAdmin?: boolean;
+        };
+        UserInput: {
+            uid?: string;
+            givenName?: string;
+            sn?: string;
+            /** Format: email */
+            mail?: string;
+            /**
+             * Format: password
+             * @description On update, blank/omitted keeps the existing password.
+             */
+            userPassword?: string;
+            /** @description Defaults to `pending` on create */
+            status?: string;
+            /** @description gidNumbers. When provided, replaces the user's group memberships. */
+            groupIds?: number[];
+        };
+        Group: {
+            gidNumber?: number;
+            cn?: string;
+            isAdmin?: boolean;
+            /** @description Present on list/show responses; absent from create/update responses. */
+            userCount?: number;
+        };
+        ExternalDomain: {
+            id?: number;
+            name?: string;
+            acmeEmail?: string | null;
+            acmeDirectoryUrl?: string | null;
+            cloudflareApiEmail?: string | null;
+            siteId?: number | null;
+            site?: {
+                id?: number;
+                name?: string;
+            } | null;
+            authServer?: string | null;
+            hasCloudflareApiKey?: boolean;
+        };
+        ExternalDomainInput: {
+            name?: string;
+            acmeEmail?: string | null;
+            acmeDirectoryUrl?: string | null;
+            cloudflareApiEmail?: string | null;
+            /** @description Never returned (see `hasCloudflareApiKey`). On update, blank/omitted keeps the existing key. */
+            cloudflareApiKey?: string;
+            siteId?: number | null;
+            authServer?: string | null;
+        };
+        Settings: {
+            smtpUrl?: string;
+            smtpNoreplyAddress?: string;
+            defaultContainerEnvVars?: {
+                key?: string;
+                value?: string;
+                description?: string;
+            }[];
+            netboxUrl?: string;
+            netboxToken?: string;
+            /** @description Announcement banner shown at the top of the app (supports [text](url) links); blank disables it. Also surfaced unauthenticated via GET /health as `banner`. */
+            bannerMessage?: string;
+            /** @description Max PSI (pressure stall) probes per usage report, spent on the highest-utilization running containers. Non-negative integer as string; "0" disables PSI, blank uses the default (16). */
+            usagePsiProbeLimit?: string;
+        };
+        ResourceRequest: {
+            id?: number;
+            siteId?: number;
+            hostname?: string;
+            username?: string;
+            /** @enum {string} */
+            resourceType?: "memory" | "swap" | "cpus" | "rootfs";
+            /** @description memory/swap in MB, rootfs in GB, cpus as a count */
+            value?: number;
+            /** @enum {string} */
+            status?: "pending" | "approved" | "denied";
+            comment?: string | null;
+            adminComment?: string | null;
+            /** @description Reviewer username, or `system` for auto-approvals */
+            reviewedBy?: string | null;
+            /** Format: date-time */
+            reviewedAt?: string | null;
+            /** Format: date-time */
+            createdAt?: string;
+            /** Format: date-time */
+            updatedAt?: string;
+            site?: {
+                id?: number;
+                name?: string;
+            } | null;
+        };
+        CollaboratorList: {
+            collaborators?: string[];
+        };
+    };
+    responses: {
+        /** @description Resource not found */
+        NotFound: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+        /** @description Forbidden */
+        Forbidden: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+        /** @description Invalid request (code: invalid_request) */
+        BadRequest: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+    };
+    parameters: never;
+    requestBodies: never;
+    headers: {
+        /** @description CSRF token returned by GET /csrf-token. Required for state-changing requests under session auth. */
+        XCSRFToken: string;
+    };
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export interface operations {
+    get_csrf_token: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Token returned */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            csrfToken?: string;
+                        };
+                    };
+                };
+            };
+        };
+    };
+    get_health: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            status?: string;
+                            isDev?: boolean;
+                            oidcEnabled?: boolean;
+                            /** @description Admin-configured announcement banner (null when unset) */
+                            banner?: string | null;
+                        };
+                    };
+                };
+            };
+        };
+    };
+    get_openapi_json: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OpenAPI document */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": unknown;
+                };
+            };
+        };
+    };
+    get_openapi_yaml: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OpenAPI document */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/yaml": unknown;
+                };
+            };
+        };
+    };
+    get_session: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Session payload */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            user?: string;
+                            isAdmin?: boolean;
+                        };
+                    };
+                };
+            };
+            /** @description Not authenticated */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    login: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    username: string;
+                    /** Format: password */
+                    password: string;
+                    redirect?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Logged in */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            user?: string;
+                            isAdmin?: boolean;
+                            redirect?: string;
+                        };
+                    };
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            /** @description Invalid credentials (code: invalid_credentials) */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description OIDC enabled (code: oidc_enabled) — use SSO instead; or account not active (code: account_inactive) */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    oidc_login: {
+        parameters: {
+            query?: {
+                redirect?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Redirect to the identity provider authorization endpoint */
+            302: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description OIDC not configured (code: oidc_disabled) */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    oidc_callback: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Redirect to the post-login destination on success, or /login?oidc_error=<code> on failure */
+            302: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description OIDC not configured (code: oidc_disabled) */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    cli_login_authorize: {
+        parameters: {
+            query: {
+                /** @description Loopback port the CLI listens on (host is always 127.0.0.1) */
+                port: number;
+                /** @description CLI-generated one-time nonce */
+                state: string;
+                /** @description Label recorded in the minted key's description */
+                client?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description HTML confirmation page */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Redirect to sign-in when there is no session */
+            302: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description HTML error page for invalid parameters */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    cli_login_mint: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/x-www-form-urlencoded": {
+                    _csrf: string;
+                    port: number;
+                    state: string;
+                    client?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Redirect to the loopback listener with the key in the fragment */
+            303: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description HTML error page for invalid parameters */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description No browser session */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Missing/invalid CSRF token */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    logout: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Logged out */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            loggedOut?: boolean;
+                            logoutUrl?: string | null;
+                        };
+                    };
+                };
+            };
+        };
+    };
+    register: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    uid: string;
+                    givenName: string;
+                    sn: string;
+                    /** Format: email */
+                    mail: string;
+                    /** Format: password */
+                    userPassword: string;
+                    inviteToken?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Account created (`status` is `active` for the first user or invited users, otherwise `pending`) */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            uid?: string;
+                            status?: string;
+                            message?: string;
+                        };
+                    };
+                };
+            };
+            /** @description invalid_request, invalid_invite, or email_mismatch */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description OIDC enabled (code: oidc_enabled) — self-registration disabled */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    validate_invite: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                token: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Invite valid, returns email */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            email?: string;
+                        };
+                    };
+                };
+            };
+            /** @description OIDC enabled (code: oidc_enabled) */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description Invalid or expired invitation (code: invalid_invite) */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    request_password_reset: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    usernameOrEmail: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Generic OK (does not reveal account existence) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            400: components["responses"]["BadRequest"];
+        };
+    };
+    validate_password_reset_token: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                token: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Token valid, returns username */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            username?: string;
+                        };
+                    };
+                };
+            };
+            /** @description Invalid or expired (code: invalid_token) */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    reset_password: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                token: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @description Minimum 8 characters */
+                    password: string;
+                    confirmPassword: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Password reset */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description invalid_request, mismatch, or weak_password */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description Invalid or expired (code: invalid_token) */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    list_sites: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Array of sites */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["Site"][];
+                    };
+                };
+            };
+        };
+    };
+    create_site: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["SiteInput"];
+            };
+        };
+        responses: {
+            /** @description Created */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["Site"];
+                    };
+                };
+            };
+            403: components["responses"]["Forbidden"];
+        };
+    };
+    get_site: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Site */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["Site"];
+                    };
+                };
+            };
+            404: components["responses"]["NotFound"];
+        };
+    };
+    update_site: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["SiteInput"];
+            };
+        };
+        responses: {
+            /** @description Updated */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["Site"];
+                    };
+                };
+            };
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    delete_site: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Deleted */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            /** @description Site still has nodes (code: has_nodes) */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    list_containers: {
+        parameters: {
+            query?: {
+                hostname?: string;
+                /** @description Filter to a single node belonging to the site */
+                nodeId?: number;
+                /** @description Owner filter, sent in bracket notation (`user[0]=alice&user[1]=bob`) so it always parses as a list. Omitted/empty returns everything the caller may see: every container on the site for admins, or their own plus any shared with them for non-admins. A list of usernames returns those owners' containers for admins; for non-admins the list is intersected with what they may already see (own plus shared), so it can only narrow visibility. */
+                user?: string[];
+            };
+            header?: never;
+            path: {
+                siteId: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Array of containers */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["Container"][];
+                    };
+                };
+            };
+            /** @description Site not found (code: site_not_found) */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    create_container: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                siteId: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    hostname: string;
+                    /** @description Docker image reference, or `custom` to use `customTemplate` */
+                    template: string;
+                    /** @description Image reference used when `template` is `custom` */
+                    customTemplate?: string;
+                    entrypoint?: string;
+                    nvidiaRequested?: boolean;
+                    /** @description (Admin only) Create the container attributed to this existing user instead of the authenticated admin */
+                    username?: string;
+                    /** @description Usernames to share the new container with (must exist) */
+                    collaborators?: string[];
+                    environmentVars?: components["schemas"]["EnvVar"][];
+                    /** @description Volumes (bind mounts) to attach to the new container */
+                    volumes?: components["schemas"]["VolumeAttach"][];
+                    /** @description Keyed map of services to create (keys are arbitrary) */
+                    services?: {
+                        [key: string]: components["schemas"]["ServiceInput"];
+                    };
+                };
+            };
+        };
+        responses: {
+            /** @description Creation job enqueued */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            /** @description Database id of the new container */
+                            containerId?: number;
+                            jobId?: number;
+                            hostname?: string;
+                            status?: components["schemas"]["ContainerStatus"];
+                        };
+                    };
+                };
+            };
+            /** @description invalid_request, invalid_service, or invalid_volume */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description forbidden — non-admins may not create containers for other users */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description site_not_found, or user_not_found when a collaborator does not exist */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description No provisionable node available (code: no_node or no_nvidia_node) */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    get_new_container_form: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                siteId: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Bootstrap payload */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            siteId?: number;
+                            externalDomains?: Record<string, never>[];
+                            nvidiaAvailable?: boolean;
+                        };
+                    };
+                };
+            };
+            /** @description Site not found (code: site_not_found) */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    get_image_metadata: {
+        parameters: {
+            query: {
+                image: string;
+            };
+            header?: never;
+            path: {
+                siteId: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Image metadata */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            400: components["responses"]["BadRequest"];
+            /** @description Image not found (code: image_not_found) */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description Registry lookup failed (code: registry_error) */
+            502: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    get_container: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                siteId: number;
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Container */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["Container"];
+                    };
+                };
+            };
+            404: components["responses"]["NotFound"];
+        };
+    };
+    update_container: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                siteId: number;
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    /** @description (Admin only) Reassign ownership of this container to the specified existing user */
+                    username?: string;
+                    /** @description Keyed map of service changes (keys are arbitrary). Entries with `deleted: true` remove the service `id`; entries with an `id` may toggle `authRequired`; entries without an `id` create a new service. */
+                    services?: {
+                        [key: string]: components["schemas"]["ServiceUpdate"];
+                    };
+                    /** @description Full replacement set. Omitting it clears all user env vars (unless the request is restart-only). */
+                    environmentVars?: components["schemas"]["EnvVar"][];
+                    /** @description Omitting/blank clears the entrypoint (unless the request is restart-only) */
+                    entrypoint?: string | null;
+                    /** @description Volume changes. Attach entries are `{ name, mountPath, mode }`; detach entries are `{ id, detach: true }`. A volume mutation on a provisioned container enqueues a reconfigure job to apply it. */
+                    volumes?: components["schemas"]["VolumeChange"][];
+                    /** @description A restart job is enqueued only when true — config changes alone never restart the container (they apply on the next restart); alone, it performs a restart-only request */
+                    restart?: boolean;
+                };
+            };
+        };
+        responses: {
+            /** @description Updated, optional restart job */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            containerId?: number;
+                            /** @description Restart job id, when a restart was enqueued */
+                            jobId?: number | null;
+                            dnsWarnings?: string[];
+                            /** @description true when env/entrypoint changes were saved but no restart was requested — they apply on the next restart */
+                            pendingRestart?: boolean;
+                            message?: string;
+                        };
+                    };
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            /** @description forbidden — only the owner/admin may edit (collaborators have a read-only view); non-admins may not reassign ownership */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            404: components["responses"]["NotFound"];
+        };
+    };
+    delete_container: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                siteId: number;
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Deleted, with DNS cleanup warnings */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            deleted?: boolean;
+                            dnsWarnings?: string[];
+                        };
+                    };
+                };
+            };
+            /** @description forbidden — only the owner/admin may delete (collaborators can view but not manage) */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            404: components["responses"]["NotFound"];
+            /** @description DB/Proxmox hostname mismatch — delete aborted (code: hostname_mismatch) */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    list_container_collaborators: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                siteId: number;
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Collaborator list */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["CollaboratorList"];
+                    };
+                };
+            };
+            404: components["responses"]["NotFound"];
+        };
+    };
+    add_container_collaborator: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                siteId: number;
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    username: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Collaborator list */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["CollaboratorList"];
+                    };
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            /** @description forbidden — only the owner/admin may share (collaborators can view but not manage) */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description user_not_found when the username does not exist */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description already_owner */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    remove_container_collaborator: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                siteId: number;
+                id: number;
+                username: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Collaborator list */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["CollaboratorList"];
+                    };
+                };
+            };
+            /** @description forbidden — only the owner/admin may unshare (collaborators can view but not manage) */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description Container or collaborator not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    list_nodes: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                siteId: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Array of nodes */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["Node"][];
+                    };
+                };
+            };
+            /** @description Site not found (code: site_not_found) */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    create_node: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                siteId: number;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["NodeInput"];
+            };
+        };
+        responses: {
+            /** @description Created */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["Node"];
+                    };
+                };
+            };
+            /** @description invalid_node_type, or invalid_docker_host when nodeType is docker and apiUrl is not a valid Docker host */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            403: components["responses"]["Forbidden"];
+        };
+    };
+    import_nodes: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                siteId: number;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** Format: uri */
+                    apiUrl: string;
+                    username: string;
+                    password: string;
+                    tlsVerify?: boolean;
+                };
+            };
+        };
+        responses: {
+            /** @description Imported */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            nodes?: components["schemas"]["Node"][];
+                            importedContainerCount?: number;
+                        };
+                    };
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            403: components["responses"]["Forbidden"];
+            /** @description Proxmox import failed (code: import_failed) */
+            502: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    get_node: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                siteId: number;
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Node */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["Node"];
+                    };
+                };
+            };
+            404: components["responses"]["NotFound"];
+        };
+    };
+    update_node: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                siteId: number;
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["NodeInput"];
+            };
+        };
+        responses: {
+            /** @description Updated */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["Node"];
+                    };
+                };
+            };
+            /** @description invalid_node_type, or invalid_docker_host when nodeType is docker and apiUrl is not a valid Docker host */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    delete_node: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                siteId: number;
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Deleted */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            /** @description Node still has containers (code: has_containers) */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    list_node_storages: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                siteId: number;
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Array of Proxmox CT template storages */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            name?: string;
+                            total?: number;
+                            available?: number;
+                        }[];
+                    };
+                };
+            };
+            /** @description Site not found (code: site_not_found) */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    get_node_stats: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                siteId: number;
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Live hardware utilization. `available` is false when the node has no API credentials or the hypervisor is unreachable. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: Record<string, never>;
+                    };
+                };
+            };
+            /** @description Node not found (code: not_found) */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    get_site_usage: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                siteId: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Per-owner usage rows with per-container detail */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            /** Format: date-time */
+                            generatedAt?: string;
+                            owners?: Record<string, never>[];
+                            /** @description Physical cluster capacity summed from the hypervisor node rows */
+                            capacity?: {
+                                cpuCores?: number;
+                                memBytes?: number;
+                                diskBytes?: number;
+                            };
+                            /** @description Admin-only attribution findings (kind drift|unattributed) */
+                            findings?: Record<string, never>[];
+                            /** @description Admin-only count of cluster members not registered in the manager DB */
+                            unknownNodeRows?: number;
+                        };
+                    };
+                };
+            };
+            /** @description Site not found (code: site_not_found) */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    get_job: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Job metadata */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["Job"];
+                    };
+                };
+            };
+            404: components["responses"]["NotFound"];
+        };
+    };
+    get_job_status: {
+        parameters: {
+            query?: {
+                offset?: number;
+                limit?: number;
+            };
+            header?: never;
+            path: {
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Status rows */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["JobStatusRow"][];
+                    };
+                };
+            };
+            404: components["responses"]["NotFound"];
+        };
+    };
+    stream_job_output: {
+        parameters: {
+            query?: {
+                lastId?: number;
+            };
+            header?: never;
+            path: {
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description SSE stream — `log` events (`{id, output, timestamp}`) and a final `status` event (`{status}`) when the job leaves pending/running. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/event-stream": unknown;
+                };
+            };
+            404: components["responses"]["NotFound"];
+        };
+    };
+    list_agents: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description List of agents */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            id?: number;
+                            siteId?: number;
+                            siteName?: string | null;
+                            hostname?: string;
+                            ipv4Address?: string | null;
+                            services?: Record<string, never> | null;
+                            /** Format: date-time */
+                            lastCheckinAt?: string | null;
+                            /** @description Computed server-side at response time */
+                            secondsSinceCheckin?: number | null;
+                        }[];
+                    };
+                };
+            };
+            403: components["responses"]["Forbidden"];
+        };
+    };
+    agent_check_in: {
+        parameters: {
+            query?: never;
+            header?: {
+                "If-None-Match"?: string;
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    siteId: number;
+                    hostname: string;
+                    /** @description Agent time, epoch seconds UTC */
+                    currentTime?: number;
+                    ipv4Address?: string | null;
+                    services?: {
+                        [key: string]: {
+                            /** @description systemd ActiveState: active, inactive, failed, ... */
+                            state?: string;
+                            /** @enum {string} */
+                            lastApply?: "success" | "failure" | "unknown";
+                        };
+                    };
+                    /** @description Per-volume directory-provisioning results keyed by the manager-assigned Volume id. The manager writes these into Volume.status (ready when applied, failed otherwise) at check-in (issue #421). */
+                    volumes?: {
+                        [key: string]: {
+                            applied?: boolean;
+                            /** @description Failure detail (mkdir/chown error) */
+                            message?: string;
+                        };
+                    };
+                };
+            };
+        };
+        responses: {
+            /** @description Config snapshot (`{ data: { site, nginx } }`) with `ETag` header */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Config unchanged since If-None-Match */
+            304: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Missing siteId/hostname (code: validation_failed) */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    list_notifications: {
+        parameters: {
+            query?: {
+                limit?: number;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Array of the caller's notifications */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: components["schemas"]["Notification"][];
+                    };
+                };
+            };
+            /** @description Authentication required */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    ingest_notification: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @example lxc-oomd */
+                    source: string;
+                    /** @enum {string} */
+                    severity: "info" | "warning" | "critical";
+                    /** @example opensource-phxdc-pve1 */
+                    node?: string | null;
+                    /** @example 392 */
+                    ctid?: (number | string) | null;
+                    /** @example mbachelder */
+                    owner?: string | null;
+                    /** @example freeze */
+                    action?: string | null;
+                    /** @example CT 392 frozen: memory PSI full avg10=83 for 45s */
+                    message: string;
+                    evidence?: {
+                        [key: string]: unknown;
+                    } | null;
+                    /**
+                     * @description Epoch seconds when the event occurred
+                     * @example 1771234560
+                     */
+                    ts?: number;
+                };
+            };
+        };
+        responses: {
+            /** @description Created — the persisted notification */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: components["schemas"]["Notification"];
+                    };
+                };
+            };
+            /** @description Invalid payload */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description Missing/invalid credentials */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description Non-admin credentials */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    acknowledge_all_notifications: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Number of notifications acknowledged */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: {
+                            /** @description Count of notifications marked read */
+                            acknowledged: number;
+                        };
+                    };
+                };
+            };
+            /** @description Authentication required */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    acknowledge_notification: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The updated notification */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: components["schemas"]["Notification"];
+                    };
+                };
+            };
+            /** @description Authentication required */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description Not found or not owned by the caller */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    record_service_access: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Access recorded */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Non-numeric id (code: invalid_request) */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description Missing/invalid credentials from a non-localhost caller */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    list_external_domains: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description List */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["ExternalDomain"][];
+                    };
+                };
+            };
+            403: components["responses"]["Forbidden"];
+        };
+    };
+    create_external_domain: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["ExternalDomainInput"];
+            };
+        };
+        responses: {
+            /** @description Created */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["ExternalDomain"];
+                    };
+                };
+            };
+            403: components["responses"]["Forbidden"];
+        };
+    };
+    get_external_domain: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Item */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["ExternalDomain"];
+                    };
+                };
+            };
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    update_external_domain: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["ExternalDomainInput"];
+            };
+        };
+        responses: {
+            /** @description Updated */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["ExternalDomain"];
+                    };
+                };
+            };
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    delete_external_domain: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Deleted */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    list_users: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description List */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["User"][];
+                    };
+                };
+            };
+            403: components["responses"]["Forbidden"];
+        };
+    };
+    create_user: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["UserInput"] & unknown;
+            };
+        };
+        responses: {
+            /** @description Created */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["User"];
+                    };
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            403: components["responses"]["Forbidden"];
+        };
+    };
+    invite_user: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** Format: email */
+                    email: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Invitation sent */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            email?: string;
+                            message?: string;
+                        };
+                    };
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            403: components["responses"]["Forbidden"];
+            /** @description smtp_not_configured or duplicate_email */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description Email delivery failed (code: email_failed) */
+            502: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    email_all_users: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    subject: string;
+                    message: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Broadcast result */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            sent?: number;
+                            failed?: number;
+                            recipients?: number;
+                        };
+                    };
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            403: components["responses"]["Forbidden"];
+            /** @description smtp_not_configured or no_recipients */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    get_user: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                uidNumber: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description User */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["User"];
+                    };
+                };
+            };
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    update_user: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                uidNumber: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["UserInput"];
+            };
+        };
+        responses: {
+            /** @description Updated */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["User"];
+                    };
+                };
+            };
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    delete_user: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                uidNumber: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Deleted */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    list_groups: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description List */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["Group"][];
+                    };
+                };
+            };
+            403: components["responses"]["Forbidden"];
+        };
+    };
+    create_group: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    gidNumber: number;
+                    cn: string;
+                    isAdmin?: boolean;
+                };
+            };
+        };
+        responses: {
+            /** @description Created */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["Group"];
+                    };
+                };
+            };
+            403: components["responses"]["Forbidden"];
+        };
+    };
+    get_group: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description gidNumber */
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Group */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["Group"];
+                    };
+                };
+            };
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    update_group: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description gidNumber */
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    cn?: string;
+                    isAdmin?: boolean;
+                };
+            };
+        };
+        responses: {
+            /** @description Updated */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["Group"];
+                    };
+                };
+            };
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    delete_group: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description gidNumber */
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Deleted */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    list_api_keys: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description List of current user's keys */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["ApiKey"][];
+                    };
+                };
+            };
+        };
+    };
+    create_api_key: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    description?: string | null;
+                };
+            };
+        };
+        responses: {
+            /** @description Created with plaintext `key` */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["ApiKey"] & {
+                            /** @description Plaintext API key — this is the only time it is returned */
+                            key?: string;
+                            warning?: string;
+                        };
+                    };
+                };
+            };
+            400: components["responses"]["BadRequest"];
+        };
+    };
+    get_api_key: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Key metadata */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["ApiKey"];
+                    };
+                };
+            };
+            /** @description Malformed id — must be a UUID (code: invalid_request) */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            404: components["responses"]["NotFound"];
+        };
+    };
+    delete_api_key: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Revoked */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Malformed id — must be a UUID (code: invalid_request) */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            404: components["responses"]["NotFound"];
+        };
+    };
+    get_settings: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description System settings */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["Settings"];
+                    };
+                };
+            };
+            403: components["responses"]["Forbidden"];
+        };
+    };
+    update_settings: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["Settings"];
+            };
+        };
+        responses: {
+            /** @description Saved */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            saved?: boolean;
+                        };
+                    };
+                };
+            };
+            403: components["responses"]["Forbidden"];
+        };
+    };
+    list_resource_requests: {
+        parameters: {
+            query?: {
+                /** @description `closed` matches approved + denied */
+                status?: "pending" | "approved" | "denied" | "closed";
+                siteId?: number;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Array of resource requests */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["ResourceRequest"][];
+                    };
+                };
+            };
+        };
+    };
+    create_resource_request: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    siteId: number;
+                    hostname: string;
+                    /** @enum {string} */
+                    resourceType: "memory" | "swap" | "cpus" | "rootfs";
+                    /** @description memory/swap in MB, rootfs in GB, cpus as a count */
+                    value: number;
+                    comment?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Request created (`status` reflects any auto-approval) */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["ResourceRequest"];
+                    };
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            /** @description Site not found (code: site_not_found) */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    count_pending_resource_requests: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Pending count */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            count?: number;
+                        };
+                    };
+                };
+            };
+        };
+    };
+    get_effective_resources: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                siteId: number;
+                hostname: string;
+                username: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Effective resource values */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: {
+                            memory?: number;
+                            swap?: number;
+                            cpus?: number;
+                            rootfs?: number;
+                        };
+                    };
+                };
+            };
+            /** @description forbidden — non-admins may only query their own username */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    approve_resource_request: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    adminComment?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Approved */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["ResourceRequest"];
+                    };
+                };
+            };
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            /** @description Request already reviewed (code: already_reviewed) */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            /** @description No provisioned container matches the request (code: container_not_found) */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+    deny_resource_request: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: number;
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": {
+                    adminComment?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Denied */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data?: components["schemas"]["ResourceRequest"];
+                    };
+                };
+            };
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            /** @description Request already reviewed (code: already_reviewed) */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+        };
+    };
+}
diff --git a/packages/os-cloud-provider/src/index.ts b/packages/os-cloud-provider/src/index.ts
new file mode 100644
index 00000000..f8d3b1d3
--- /dev/null
+++ b/packages/os-cloud-provider/src/index.ts
@@ -0,0 +1,74 @@
+/**
+ * `@mieweb/os-cloud-provider` — the opensource-server (os.mieweb.org)
+ * implementation of the `@mieweb/deploy-contract` DeployProvider.
+ *
+ * `mieweb deploy --target mieweb` resolves this package from the app's
+ * node_modules via `targets.mieweb.provider` and calls `createProvider(env)`.
+ *
+ * Verbs: deploy, destroy, tail, whoami, login, logout. `deploy` converges the
+ * container through the Manager API (skipped when nothing changed) and then
+ * syncs the local worktree into it over its published SSH port (pure-JS
+ * SSH via `ssh2`; no local rsync/ssh binaries needed).
+ *   - `dev` is intentionally omitted: there is no remote analogue; local dev
+ *     uses the CLI's own host harness.
+ *   - `tail` streams `app.service`'s journal over the container's SSH port
+ *     (`-n/--lines N`, `--no-follow`, `--since <time>`).
+ *
+ * Secrets come only from `env` (MIEWEB_OS_TOKEN, MIEWEB_OS_SECRET_*) or the
+ * machine-local login cache, never from the DeployContext.
+ */
+
+import type { DeployContext, DeployProvider, DeployTarget, ProviderEnv } from '@mieweb/deploy-contract';
+import { login, logout, whoami, type LoginHooks } from './auth.ts';
+import { PROVIDER_NAME } from './config.ts';
+import { deploy, destroy, tail, type ProviderDeps } from './deploy.ts';
+import type { Prompter, waitForSsh } from './ssh.ts';
+
+export { PROVIDER_NAME, DEFAULT_IMAGE, DEFAULT_INSTANCE_URL, DATA_VOLUME, ConfigError } from './config.ts';
+export { ManagerApiError } from './client.ts';
+export { JobFailedError } from './jobs.ts';
+
+export interface ProviderOptions {
+  /** Injected fetch (tests). */
+  fetch?: typeof fetch;
+  /** Job poll interval in ms (default 2000). */
+  pollIntervalMs?: number;
+  /** Browser/prompt hooks for `login` (tests). */
+  login?: LoginHooks;
+  /** Open the sync SSH session (tests). */
+  connectSsh?: ProviderDeps['connectSsh'];
+  /** Terminal prompt for SSH passphrases/passwords. */
+  prompt?: Prompter;
+  /** SSH readiness probe (tests). */
+  waitForSsh?: typeof waitForSsh;
+  /** Total SSH readiness budget in ms (default 60000). */
+  sshTimeoutMs?: number;
+  /** Delay between SSH attempts in ms (default 2000). */
+  sshRetryDelayMs?: number;
+}
+
+/** The targets this provider serves. */
+export const SUPPORTED_TARGETS: readonly DeployTarget[] = ['mieweb'];
+
+export function createProvider(env: ProviderEnv, options: ProviderOptions = {}): DeployProvider {
+  const deps: ProviderDeps = {
+    env,
+    fetch: options.fetch,
+    pollIntervalMs: options.pollIntervalMs,
+    connectSsh: options.connectSsh,
+    prompt: options.prompt,
+    waitForSsh: options.waitForSsh,
+    sshTimeoutMs: options.sshTimeoutMs,
+    sshRetryDelayMs: options.sshRetryDelayMs,
+  };
+  return {
+    name: PROVIDER_NAME,
+    supports: (target: DeployTarget) => SUPPORTED_TARGETS.includes(target),
+    deploy: (ctx: DeployContext) => deploy(ctx, deps),
+    destroy: (ctx: DeployContext) => destroy(ctx, deps),
+    tail: (ctx: DeployContext) => tail(ctx, deps),
+    whoami: (ctx: DeployContext) => whoami(ctx, deps),
+    login: (ctx: DeployContext) => login(ctx, deps, options.login),
+    logout: (ctx: DeployContext) => logout(ctx, deps),
+  };
+}
diff --git a/packages/os-cloud-provider/src/jobs.ts b/packages/os-cloud-provider/src/jobs.ts
new file mode 100644
index 00000000..a6ddce82
--- /dev/null
+++ b/packages/os-cloud-provider/src/jobs.ts
@@ -0,0 +1,89 @@
+/**
+ * Job polling. `get_job` (`GET /jobs/{id}`) carries the terminal verdict
+ * (`Job.status`); `GET /jobs/{id}/status` only returns output log rows, which
+ * we forward to the logger as they arrive.
+ */
+
+import type { DeployLogger } from '@mieweb/deploy-contract';
+import type { Job, JobLogRow } from './api-types.ts';
+import type { ManagerClient } from './client.ts';
+
+export interface WaitOptions {
+  signal: AbortSignal;
+  logger: DeployLogger;
+  intervalMs?: number;
+  timeoutMs?: number;
+  /** Forward the job's output rows to the logger (default true). */
+  streamLogs?: boolean;
+}
+
+export class JobFailedError extends Error {
+  readonly jobId: number;
+  readonly status: string;
+  constructor(jobId: number, status: string, tail: string[]) {
+    super(`Manager job ${jobId} ended with status "${status}"${tail.length ? `:\n${tail.join('\n')}` : ''}`);
+    this.name = 'JobFailedError';
+    this.jobId = jobId;
+    this.status = status;
+  }
+}
+
+/** Resolve after `ms`, or reject with the signal's reason on abort. */
+export function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      reject(signal.reason);
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+const TERMINAL = new Set(['success', 'failure', 'cancelled']);
+
+/** Poll a job until it reaches a terminal status; throw unless it succeeded. */
+export async function waitForJob(client: ManagerClient, jobId: number, opts: WaitOptions): Promise<void> {
+  const interval = opts.intervalMs ?? 2000;
+  const deadline = Date.now() + (opts.timeoutMs ?? 30 * 60 * 1000);
+  const stream = opts.streamLogs !== false;
+  const tail: string[] = [];
+  let offset = 0;
+
+  const drainLogs = async (): Promise<void> => {
+    if (!stream) return;
+    for (;;) {
+      const rows = await client.get<JobLogRow[]>(`/jobs/${jobId}/status`, { offset, limit: 500 });
+      for (const row of rows) {
+        for (const line of String(row.output ?? '').split('\n')) {
+          if (line.trim() === '') continue;
+          opts.logger.info(`  [job ${jobId}] ${line}`);
+          tail.push(line);
+          if (tail.length > 20) tail.shift();
+        }
+      }
+      offset += rows.length;
+      if (rows.length < 500) return;
+    }
+  };
+
+  for (;;) {
+    const job = await client.get<Job>(`/jobs/${jobId}`);
+    await drainLogs();
+    if (TERMINAL.has(job.status)) {
+      if (job.status === 'success') return;
+      throw new JobFailedError(jobId, job.status, tail);
+    }
+    if (Date.now() > deadline) {
+      throw new Error(`Timed out waiting for Manager job ${jobId} (last status "${job.status}")`);
+    }
+    await sleep(interval, opts.signal);
+  }
+}
diff --git a/packages/os-cloud-provider/src/ssh.ts b/packages/os-cloud-provider/src/ssh.ts
new file mode 100644
index 00000000..53ff5888
--- /dev/null
+++ b/packages/os-cloud-provider/src/ssh.ts
@@ -0,0 +1,475 @@
+/**
+ * Pure-JS SSH (the `ssh2` package): no `ssh`/`rsync` binaries needed.
+ *
+ * Authentication uses the user's own local credentials, in order:
+ *   1. ssh-agent (`SSH_AUTH_SOCK`; Pageant on Windows)
+ *   2. default keys in ~/.ssh (id_ed25519, id_ecdsa, id_rsa), prompting for a
+ *      passphrase on the terminal when a key is encrypted
+ *   3. keyboard-interactive / password, prompted on the terminal
+ * Prompts go to stderr and only happen when stdin is a TTY.
+ *
+ * Host keys are pinned trust-on-first-use in ~/.mieweb/known_hosts
+ * (`[host]:port SHA256:<fingerprint>`). A changed key is an error unless the
+ * caller cleared the pin first (it does after recreating the container).
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { connect as netConnect } from 'node:net';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import type { DeployLogger, ProviderEnv } from '@mieweb/deploy-contract';
+import ssh2 from 'ssh2';
+import type { AnyAuthMethod, AuthenticationType, ClientChannel, ConnectConfig, Prompt } from 'ssh2';
+import { sleep } from './jobs.ts';
+
+const { Client, utils } = ssh2;
+
+export interface SshTarget {
+  host: string;
+  port: number;
+  user: string;
+}
+
+/**
+ * A failed SSH connection attempt. `kind` tells callers whether a retry can
+ * help: `network` (refused/reset/timeout, e.g. sshd still starting) and `auth`
+ * (possibly LDAP keys not served yet on a fresh container) may be transient;
+ * `hostkey` never is.
+ */
+export class SshError extends Error {
+  readonly kind: 'network' | 'auth' | 'hostkey';
+  constructor(kind: 'network' | 'auth' | 'hostkey', message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'SshError';
+    this.kind = kind;
+  }
+}
+
+export interface ExecResult {
+  code: number;
+  stdout: Buffer;
+  stderr: string;
+}
+
+/** The remote operations sync needs. `SshConnection` implements it over ssh2. */
+export interface RemoteShell {
+  exec(command: string, stdin?: Buffer | NodeJS.ReadableStream): Promise<ExecResult>;
+  /**
+   * Run a long-lived command, calling `onData` with stdout/stderr chunks.
+   * Resolves with the exit code, or -1 when `signal` aborts (the channel is
+   * closed).
+   */
+  stream(command: string, onData: (chunk: Buffer, stream: 'stdout' | 'stderr') => void, signal: AbortSignal): Promise<number>;
+  close(): void;
+}
+
+/** Terminal prompt; `hidden` suppresses echo. Returns null when not interactive. */
+export type Prompter = (question: string, hidden: boolean) => Promise<string | null>;
+
+export const ttyPrompter: Prompter = (question, hidden) =>
+  new Promise((resolve) => {
+    const stdin = process.stdin;
+    if (!stdin.isTTY) {
+      resolve(null);
+      return;
+    }
+    process.stderr.write(question);
+    let answer = '';
+    const wasRaw = stdin.isRaw;
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding('utf8');
+    const onData = (chunk: string): void => {
+      for (const ch of chunk) {
+        if (ch === '\r' || ch === '\n') {
+          done(answer);
+          return;
+        }
+        if (ch === '\u0003') {
+          done(null);
+          return;
+        }
+        if (ch === '\u007f' || ch === '\b') {
+          if (answer.length > 0) {
+            answer = answer.slice(0, -1);
+            if (!hidden) process.stderr.write('\b \b');
+          }
+          continue;
+        }
+        answer += ch;
+        if (!hidden) process.stderr.write(ch);
+      }
+    };
+    const done = (value: string | null): void => {
+      stdin.off('data', onData);
+      stdin.setRawMode(wasRaw);
+      stdin.pause();
+      process.stderr.write('\n');
+      resolve(value);
+    };
+    stdin.on('data', onData);
+  });
+
+// --- known hosts ------------------------------------------------------------
+
+export function knownHostsPath(env: ProviderEnv): string {
+  return join(env.HOME?.trim() || homedir(), '.mieweb', 'known_hosts');
+}
+
+function hostKeyId(host: string, port: number): string {
+  return `[${host}]:${port}`;
+}
+
+export function fingerprint(key: Buffer): string {
+  return `SHA256:${createHash('sha256').update(key).digest('base64').replace(/=+$/, '')}`;
+}
+
+function readKnownHosts(file: string): Map<string, string> {
+  const map = new Map<string, string>();
+  if (!existsSync(file)) return map;
+  for (const line of readFileSync(file, 'utf8').split('\n')) {
+    const [id, fp] = line.trim().split(/\s+/);
+    if (id && fp) map.set(id, fp);
+  }
+  return map;
+}
+
+async function writeKnownHosts(file: string, map: Map<string, string>): Promise<void> {
+  await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+  await writeFile(file, [...map].map(([id, fp]) => `${id} ${fp}\n`).join(''), { mode: 0o600 });
+}
+
+/** Drop the pinned key for host:port (the container behind it was replaced). */
+export async function forgetHostKey(file: string, host: string, port: number): Promise<void> {
+  const map = readKnownHosts(file);
+  if (map.delete(hostKeyId(host, port))) await writeKnownHosts(file, map);
+}
+
+// --- auth -------------------------------------------------------------------
+
+const DEFAULT_KEYS = ['id_ed25519', 'id_ecdsa', 'id_rsa'];
+
+interface KeyCandidate {
+  path: string;
+  data: Buffer;
+  encrypted: boolean;
+}
+
+function localKeys(env: ProviderEnv): KeyCandidate[] {
+  const dir = join(env.HOME?.trim() || homedir(), '.ssh');
+  const out: KeyCandidate[] = [];
+  for (const name of DEFAULT_KEYS) {
+    const path = join(dir, name);
+    let data: Buffer;
+    try {
+      data = readFileSync(path);
+    } catch {
+      continue;
+    }
+    const parsed = utils.parseKey(data);
+    if (parsed instanceof Error) {
+      if (/encrypted|passphrase/i.test(parsed.message)) out.push({ path, data, encrypted: true });
+      continue;
+    }
+    out.push({ path, data, encrypted: false });
+  }
+  return out;
+}
+
+/**
+ * Build the ssh2 authHandler. Methods are tried in order; ones the server
+ * doesn't offer are skipped. The password is asked for at most once and
+ * reused for keyboard-interactive.
+ */
+export function makeAuthHandler(
+  user: string,
+  env: ProviderEnv,
+  prompt: Prompter,
+  target: string,
+  interactive: boolean = !!process.stdin.isTTY,
+) {
+  let password: string | null | undefined;
+  const askPassword = async (): Promise<string | null> => {
+    if (password === undefined) password = await prompt(`${user}@${target}'s password: `, true);
+    return password;
+  };
+
+  type Step = () => Promise<AnyAuthMethod | null>;
+  const steps: { type: AuthenticationType; step: Step }[] = [];
+
+  const agent = env.SSH_AUTH_SOCK?.trim() || (process.platform === 'win32' ? 'pageant' : '');
+  if (agent) steps.push({ type: 'publickey', step: async () => ({ type: 'agent', username: user, agent }) });
+
+  for (const key of localKeys(env)) {
+    steps.push({
+      type: 'publickey',
+      step: async () => {
+        if (!key.encrypted) return { type: 'publickey', username: user, key: key.data };
+        if (!interactive) return null;
+        const passphrase = await prompt(`Enter passphrase for key '${key.path}': `, true);
+        if (!passphrase) return null;
+        if (utils.parseKey(key.data, passphrase) instanceof Error) return null;
+        return { type: 'publickey', username: user, key: key.data, passphrase };
+      },
+    });
+  }
+
+  steps.push({
+    type: 'keyboard-interactive',
+    step: async () => (!interactive ? null : {
+      type: 'keyboard-interactive',
+      username: user,
+      prompt: (_name: string, _instr: string, _lang: string, prompts: Prompt[], finish: (answers: string[]) => void) => {
+        void (async () => {
+          const answers: string[] = [];
+          for (const p of prompts) {
+            const isPassword = /password/i.test(p.prompt) && !p.echo;
+            const answer = isPassword ? await askPassword() : await prompt(p.prompt, !p.echo);
+            answers.push(answer ?? '');
+          }
+          finish(answers);
+        })();
+      },
+    }),
+  });
+  steps.push({
+    type: 'password',
+    step: async () => {
+      if (!interactive) return null;
+      const pw = await askPassword();
+      return pw === null ? null : { type: 'password', username: user, password: pw };
+    },
+  });
+
+  let i = 0;
+  return (authsLeft: AuthenticationType[] | null, _partial: boolean, next: (m: AnyAuthMethod | false) => void): void => {
+    void (async () => {
+      while (i < steps.length) {
+        const s = steps[i++]!;
+        if (authsLeft && !authsLeft.includes(s.type)) continue;
+        const method = await s.step();
+        if (method) {
+          next(method);
+          return;
+        }
+      }
+      next(false);
+    })();
+  };
+}
+
+// --- connection -------------------------------------------------------------
+
+export interface ConnectOptions {
+  target: SshTarget;
+  env: ProviderEnv;
+  knownHostsFile: string;
+  prompt?: Prompter;
+  /** Whether prompting is possible (default: stdin is a TTY). */
+  interactive?: boolean;
+  signal: AbortSignal;
+  logger: DeployLogger;
+  timeoutMs?: number;
+}
+
+export class SshConnection implements RemoteShell {
+  private readonly client: InstanceType<typeof Client>;
+  private constructor(client: InstanceType<typeof Client>) {
+    this.client = client;
+  }
+
+  static connect(opts: ConnectOptions): Promise<SshConnection> {
+    const { target, logger } = opts;
+    const id = hostKeyId(target.host, target.port);
+    const known = readKnownHosts(opts.knownHostsFile);
+    let pinned: { fp: string } | null = null;
+    let mismatch: string | null = null;
+
+    return new Promise((resolve, reject) => {
+      const client = new Client();
+      const onAbort = (): void => {
+        client.end();
+        reject(opts.signal.reason);
+      };
+      opts.signal.addEventListener('abort', onAbort, { once: true });
+      const fail = (err: Error): void => {
+        opts.signal.removeEventListener('abort', onAbort);
+        if (mismatch) {
+          reject(
+            new SshError(
+              'hostkey',
+              `SSH host key for ${id} changed (expected ${known.get(id)}, got ${mismatch}). ` +
+                `If the container was rebuilt, remove that line from ${opts.knownHostsFile}.`,
+            ),
+          );
+        } else if (/authentication methods failed/i.test(err.message)) {
+          reject(
+            new SshError(
+              'auth',
+              `SSH authentication as ${target.user}@${target.host}:${target.port} failed. ` +
+                'Add your public key to your account, load it into ssh-agent, or run deploy in a terminal to enter your password.',
+            ),
+          );
+        } else {
+          reject(new SshError('network', `SSH connection to ${target.host}:${target.port} failed: ${err.message}`, { cause: err }));
+        }
+      };
+      client.once('error', fail);
+      client.once('ready', () => {
+        opts.signal.removeEventListener('abort', onAbort);
+        client.off('error', fail);
+        client.on('error', () => {});
+        const done = (): void => resolve(new SshConnection(client));
+        if (pinned) {
+          known.set(id, pinned.fp);
+          logger.info(`Trusting SSH host key ${pinned.fp} for ${id}`);
+          writeKnownHosts(opts.knownHostsFile, known).then(done, done);
+        } else done();
+      });
+
+      const config: ConnectConfig = {
+        host: target.host,
+        port: target.port,
+        username: target.user,
+        readyTimeout: opts.timeoutMs ?? 20_000,
+        keepaliveInterval: 15_000,
+        hostVerifier: (key: Buffer) => {
+          const fp = fingerprint(key);
+          const expected = known.get(id);
+          if (!expected) {
+            pinned = { fp };
+            return true;
+          }
+          if (expected === fp) return true;
+          mismatch = fp;
+          return false;
+        },
+        authHandler: makeAuthHandler(
+          target.user,
+          opts.env,
+          opts.prompt ?? ttyPrompter,
+          `${target.host}:${target.port}`,
+          opts.interactive ?? !!process.stdin.isTTY,
+        ) as ConnectConfig['authHandler'],
+      };
+      client.connect(config);
+    });
+  }
+
+  exec(command: string, stdin?: Buffer | NodeJS.ReadableStream): Promise<ExecResult> {
+    return new Promise((resolve, reject) => {
+      this.client.exec(command, (err: Error | undefined, stream: ClientChannel) => {
+        if (err) {
+          reject(err);
+          return;
+        }
+        const out: Buffer[] = [];
+        let stderr = '';
+        let code = -1;
+        stream.on('data', (d: Buffer) => out.push(d));
+        stream.stderr.on('data', (d: Buffer) => {
+          stderr = (stderr + d.toString('utf8')).slice(-8192);
+        });
+        stream.on('exit', (c: number | null) => {
+          code = c ?? -1;
+        });
+        stream.on('close', () => resolve({ code, stdout: Buffer.concat(out), stderr }));
+        stream.on('error', reject);
+        if (stdin === undefined) stream.end();
+        else if (Buffer.isBuffer(stdin)) stream.end(stdin);
+        else {
+          stdin.on('error', () => stream.close());
+          stdin.pipe(stream);
+        }
+      });
+    });
+  }
+
+  stream(
+    command: string,
+    onData: (chunk: Buffer, stream: 'stdout' | 'stderr') => void,
+    signal: AbortSignal,
+  ): Promise<number> {
+    return new Promise((resolve, reject) => {
+      if (signal.aborted) {
+        resolve(-1);
+        return;
+      }
+      this.client.exec(command, (err: Error | undefined, stream: ClientChannel) => {
+        if (err) {
+          reject(err);
+          return;
+        }
+        let code = -1;
+        const onAbort = (): void => {
+          stream.close();
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        stream.on('data', (d: Buffer) => onData(d, 'stdout'));
+        stream.stderr.on('data', (d: Buffer) => onData(d, 'stderr'));
+        stream.on('exit', (c: number | null) => {
+          code = c ?? -1;
+        });
+        stream.on('close', () => {
+          signal.removeEventListener('abort', onAbort);
+          resolve(signal.aborted ? -1 : code);
+        });
+        stream.on('error', reject);
+        stream.end();
+      });
+    });
+  }
+
+  close(): void {
+    this.client.end();
+  }
+}
+
+// --- readiness --------------------------------------------------------------
+
+/** Resolve once host:port answers with an SSH banner. */
+export async function waitForSsh(
+  host: string,
+  port: number,
+  signal: AbortSignal,
+  logger: DeployLogger,
+  timeoutMs = 5 * 60 * 1000,
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  let announced = false;
+  for (;;) {
+    if (await probeSsh(host, port, signal)) return;
+    if (!announced) {
+      logger.info(`Waiting for SSH on ${host}:${port}…`);
+      announced = true;
+    }
+    if (Date.now() > deadline) {
+      throw new Error(`SSH on ${host}:${port} did not become available within ${Math.round(timeoutMs / 1000)}s`);
+    }
+    await sleep(2000, signal);
+  }
+}
+
+function probeSsh(host: string, port: number, signal: AbortSignal): Promise<boolean> {
+  return new Promise((resolve) => {
+    const sock = netConnect({ host, port, timeout: 5000 });
+    let buf = '';
+    const done = (ok: boolean): void => {
+      signal.removeEventListener('abort', onAbort);
+      sock.destroy();
+      resolve(ok);
+    };
+    const onAbort = (): void => done(false);
+    signal.addEventListener('abort', onAbort, { once: true });
+    sock.setEncoding('latin1');
+    sock.on('data', (d: string) => {
+      buf += d;
+      if (buf.includes('\n') || buf.length >= 4) done(buf.startsWith('SSH-'));
+    });
+    sock.on('timeout', () => done(false));
+    sock.on('error', () => done(false));
+    sock.on('end', () => done(false));
+  });
+}
diff --git a/packages/os-cloud-provider/src/sync.ts b/packages/os-cloud-provider/src/sync.ts
new file mode 100644
index 00000000..734da74b
--- /dev/null
+++ b/packages/os-cloud-provider/src/sync.ts
@@ -0,0 +1,275 @@
+/**
+ * Code delivery: copy the local worktree into the converged container over
+ * SSH and restart `app.service`. rsync-like, implemented in JS (no local
+ * rsync/ssh binaries):
+ *
+ * 1. Scan the worktree. `.gitignore` rules are honored (nested files too, via
+ *    the `ignore` package), `.git/` is skipped. Staged vs. committed status
+ *    doesn't matter; the files on disk are what gets sent.
+ * 2. List the remote tree (`find -printf`) and diff by size + mtime.
+ * 3. Stream a tar of the changed files into `sudo tar -x` (owned by the
+ *    `mieweb` service account, mtimes preserved so the next diff is exact).
+ * 4. Delete remote files that no longer exist locally. Remote paths matching
+ *    the ignore rules (node_modules, build output) are left alone.
+ * 5. `sudo systemctl restart app.service`, streaming the unit's journal while
+ *    it installs/builds (ExecStartPre) and failing the deploy if the restart
+ *    fails or the app doesn't stay up for APP_SETTLE_SECONDS.
+ *
+ * LDAP users have passwordless sudo in the base image.
+ */
+
+import { createReadStream } from 'node:fs';
+import { lstat, readdir, readFile, readlink } from 'node:fs/promises';
+import { posix, join } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import type { DeployLogger } from '@mieweb/deploy-contract';
+import ignore, { type Ignore } from 'ignore';
+import tarStream from 'tar-stream';
+import type { RemoteShell } from './ssh.ts';
+
+export const REMOTE_APP_DIR = '/opt/app/src';
+const OWNER = 'mieweb';
+
+export interface FileEntry {
+  /** POSIX path relative to the root. */
+  path: string;
+  type: 'file' | 'symlink';
+  size: number;
+  /** Seconds since the epoch (whole seconds; tar precision). */
+  mtime: number;
+  mode: number;
+  linkname?: string;
+}
+
+/** `.gitignore` rules scoped to the directories that declare them. */
+export class IgnoreRules {
+  private readonly scopes: { prefix: string; ig: Ignore }[] = [];
+
+  add(dir: string, content: string): void {
+    this.scopes.push({ prefix: dir === '' ? '' : `${dir}/`, ig: ignore().add(content) });
+  }
+
+  /** Whether `path` itself (not its ancestors) matches a rule. */
+  private matches(path: string, isDir: boolean): boolean {
+    let ignored = false;
+    for (const { prefix, ig } of this.scopes) {
+      if (!path.startsWith(prefix)) continue;
+      const rel = path.slice(prefix.length);
+      if (rel === '') continue;
+      const r = ig.test(isDir ? `${rel}/` : rel);
+      if (r.ignored) ignored = true;
+      else if (r.unignored) ignored = false;
+    }
+    return ignored;
+  }
+
+  /** Whether `path` or any directory above it is ignored (or is `.git`). */
+  ignores(path: string, isDir = false): boolean {
+    const parts = path.split('/');
+    for (let i = 1; i <= parts.length; i += 1) {
+      const sub = parts.slice(0, i).join('/');
+      const subIsDir = i < parts.length || isDir;
+      if (parts[i - 1] === '.git' && subIsDir) return true;
+      if (this.matches(sub, subIsDir)) return true;
+    }
+    return false;
+  }
+}
+
+/** Walk the worktree, honoring .gitignore. */
+export async function scanLocal(root: string): Promise<{ files: Map<string, FileEntry>; rules: IgnoreRules }> {
+  const rules = new IgnoreRules();
+  const files = new Map<string, FileEntry>();
+
+  const walk = async (dir: string): Promise<void> => {
+    const abs = join(root, dir);
+    try {
+      rules.add(dir, await readFile(join(abs, '.gitignore'), 'utf8'));
+    } catch {
+      // no .gitignore here
+    }
+    const entries = await readdir(abs, { withFileTypes: true });
+    entries.sort((a, b) => (a.name < b.name ? -1 : 1));
+    for (const e of entries) {
+      const rel = dir === '' ? e.name : `${dir}/${e.name}`;
+      if (e.isDirectory()) {
+        if (!rules.ignores(rel, true)) await walk(rel);
+        continue;
+      }
+      if (rules.ignores(rel)) continue;
+      const st = await lstat(join(root, rel));
+      if (st.isSymbolicLink()) {
+        const linkname = await readlink(join(root, rel));
+        files.set(rel, { path: rel, type: 'symlink', size: Buffer.byteLength(linkname), mtime: Math.floor(st.mtimeMs / 1000), mode: 0o777, linkname });
+      } else if (st.isFile()) {
+        files.set(rel, { path: rel, type: 'file', size: st.size, mtime: Math.floor(st.mtimeMs / 1000), mode: st.mode & 0o777 });
+      }
+      // sockets, fifos, devices: skipped
+    }
+  };
+  await walk('');
+  return { files, rules };
+}
+
+/** Parse `find -printf '%P\0%s\0%T@\0'` output. */
+export function parseRemoteListing(out: Buffer): Map<string, { size: number; mtime: number }> {
+  const map = new Map<string, { size: number; mtime: number }>();
+  const parts = out.toString('utf8').split('\0');
+  for (let i = 0; i + 2 < parts.length; i += 3) {
+    map.set(parts[i]!, { size: Number(parts[i + 1]), mtime: Math.floor(Number(parts[i + 2])) });
+  }
+  return map;
+}
+
+export interface SyncPlan {
+  upload: FileEntry[];
+  remove: string[];
+}
+
+export function planSync(
+  local: Map<string, FileEntry>,
+  remote: Map<string, { size: number; mtime: number }>,
+  rules: IgnoreRules,
+): SyncPlan {
+  const upload: FileEntry[] = [];
+  for (const f of local.values()) {
+    const r = remote.get(f.path);
+    if (!r || r.size !== f.size || r.mtime !== f.mtime) upload.push(f);
+  }
+  const remove = [...remote.keys()].filter((p) => !local.has(p) && !rules.ignores(p)).sort();
+  return { upload, remove };
+}
+
+function ancestors(path: string): string[] {
+  const out: string[] = [];
+  for (let d = posix.dirname(path); d !== '.' && d !== '/'; d = posix.dirname(d)) out.push(d);
+  return out;
+}
+
+/** A tar stream of `files` (plus their parent dirs), all owned by OWNER. */
+export function packTar(root: string, files: readonly FileEntry[]): Readable {
+  const pack = tarStream.pack();
+  const owner = { uname: OWNER, gname: OWNER, uid: 0, gid: 0 };
+  void (async () => {
+    try {
+      const dirs = new Set<string>();
+      for (const f of files) for (const d of ancestors(f.path)) dirs.add(d);
+      for (const d of [...dirs].sort()) {
+        pack.entry({ name: d, type: 'directory', mode: 0o755, ...owner });
+      }
+      for (const f of files) {
+        const mtime = new Date(f.mtime * 1000);
+        if (f.type === 'symlink') {
+          pack.entry({ name: f.path, type: 'symlink', linkname: f.linkname, mode: 0o777, mtime, ...owner });
+          continue;
+        }
+        const entry = pack.entry({ name: f.path, type: 'file', size: f.size, mode: f.mode, mtime, ...owner });
+        await pipeline(createReadStream(join(root, f.path)), entry);
+      }
+      pack.finalize();
+    } catch (err) {
+      pack.destroy(err as Error);
+    }
+  })();
+  return Readable.from(pack);
+}
+
+const q = (s: string): string => `'${s.replace(/'/g, `'\\''`)}'`;
+
+/** Seconds the app must stay running after a restart to count as started. */
+export const APP_SETTLE_SECONDS = 5;
+/** Exit code the restart script uses for "started, then stopped/crashed". */
+const APP_NOT_RUNNING = 86;
+
+export const REMOTE = {
+  list: `sudo mkdir -p ${q(REMOTE_APP_DIR)} && cd ${q(REMOTE_APP_DIR)} && sudo find . -mindepth 1 \\( -type f -o -type l \\) -printf '%P\\0%s\\0%T@\\0'`,
+  extract: `sudo tar -x -f - -C ${q(REMOTE_APP_DIR)}`,
+  remove: `cd ${q(REMOTE_APP_DIR)} && sudo xargs -0 -r rm -f --`,
+  pruneDirs: `cd ${q(REMOTE_APP_DIR)} && sudo xargs -0 -r rmdir -p --ignore-fail-on-non-empty -- 2>/dev/null; true`,
+  /**
+   * Follow the journal (live install/build output) while restarting; exit
+   * non-zero if the restart fails (ExecStartPre install/build failed) or the
+   * app isn't still active after the settle period (crashed on start).
+   */
+  restart: [
+    'sudo journalctl -u app.service -o cat -f -n 0 & j=$!',
+    'sleep 1',
+    'sudo systemctl restart app.service; rc=$?',
+    `if [ $rc -eq 0 ]; then sleep ${APP_SETTLE_SECONDS}; sudo systemctl is-active --quiet app.service || rc=${APP_NOT_RUNNING}; fi`,
+    'sleep 1; sudo kill $j 2>/dev/null; kill $j 2>/dev/null; wait $j 2>/dev/null',
+    'exit $rc',
+  ].join('\n'),
+  /** Recent journal, shown when the restart fails. */
+  logs: 'sudo journalctl -u app.service -o cat --no-pager -n 50',
+};
+
+async function run(shell: RemoteShell, what: string, cmd: string, stdin?: Buffer | NodeJS.ReadableStream): Promise<Buffer> {
+  const res = await shell.exec(cmd, stdin);
+  if (res.code !== 0) {
+    throw new Error(`Remote ${what} failed (exit ${res.code})${res.stderr.trim() ? `: ${res.stderr.trim()}` : ''}`);
+  }
+  return res.stdout;
+}
+
+function human(n: number): string {
+  return n < 1024 ? `${n} B` : n < 1024 ** 2 ? `${(n / 1024).toFixed(1)} KiB` : `${(n / 1024 ** 2).toFixed(1)} MiB`;
+}
+
+/** Restart app.service, streaming its output; throw if it doesn't come up. */
+export async function restartApp(shell: RemoteShell, logger: DeployLogger, signal: AbortSignal): Promise<void> {
+  let pending = '';
+  const code = await shell.stream(
+    REMOTE.restart,
+    (chunk, which) => {
+      if (which === 'stderr') {
+        // sudo/systemctl errors; surface them as-is.
+        for (const l of chunk.toString('utf8').split('\n')) if (l.trim()) logger.warn(`  ${l}`);
+        return;
+      }
+      const lines = (pending + chunk.toString('utf8')).split('\n');
+      pending = lines.pop() ?? '';
+      for (const l of lines) logger.info(`  | ${l}`);
+    },
+    signal,
+  );
+  if (pending) logger.info(`  | ${pending}`);
+  if (code === 0) return;
+  if (code === -1) throw signal.reason ?? new Error('Restart aborted');
+  const tail = await shell.exec(REMOTE.logs).catch(() => null);
+  const recent = tail?.code === 0 ? tail.stdout.toString('utf8').trim() : '';
+  if (recent) logger.error(`Recent app.service logs:\n${recent}`);
+  throw new Error(
+    code === APP_NOT_RUNNING
+      ? `The app started but stopped within ${APP_SETTLE_SECONDS}s; see the logs above (\`mieweb tail\` for more)`
+      : `Restarting the app failed (exit ${code}): dependency install or build failed; see the logs above`,
+  );
+}
+
+/** Sync `root` into the container and restart the app. */
+export async function syncWorktree(
+  root: string,
+  shell: RemoteShell,
+  logger: DeployLogger,
+  signal: AbortSignal = new AbortController().signal,
+): Promise<SyncPlan> {
+  const [{ files, rules }, listing] = await Promise.all([scanLocal(root), run(shell, 'listing', REMOTE.list)]);
+  const plan = planSync(files, parseRemoteListing(listing), rules);
+  const bytes = plan.upload.reduce((n, f) => n + (f.type === 'file' ? f.size : 0), 0);
+  logger.info(
+    `Syncing ${root} → ${REMOTE_APP_DIR}: ${files.size} files, ` +
+      `${plan.upload.length} to upload (${human(bytes)}), ${plan.remove.length} to delete`,
+  );
+
+  if (plan.upload.length > 0) await run(shell, 'extract', REMOTE.extract, packTar(root, plan.upload));
+  if (plan.remove.length > 0) {
+    const nul = (xs: string[]): Buffer => Buffer.from(xs.map((x) => `${x}\0`).join(''));
+    await run(shell, 'delete', REMOTE.remove, nul(plan.remove));
+    const dirs = [...new Set(plan.remove.map((p) => posix.dirname(p)).filter((d) => d !== '.'))];
+    if (dirs.length > 0) await run(shell, 'cleanup', REMOTE.pruneDirs, nul(dirs));
+  }
+  logger.info('Code synced; restarting the app (install/build output follows)');
+  await restartApp(shell, logger, signal);
+  logger.info('App restarted and running');
+  return plan;
+}
diff --git a/packages/os-cloud-provider/test/config.test.ts b/packages/os-cloud-provider/test/config.test.ts
new file mode 100644
index 00000000..c79907d4
--- /dev/null
+++ b/packages/os-cloud-provider/test/config.test.ts
@@ -0,0 +1,113 @@
+import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+import type { DeployContext } from '@mieweb/deploy-contract';
+import {
+  appName,
+  ConfigError,
+  DEFAULT_IMAGE,
+  instanceFromArgv,
+  normalizeInstanceUrl,
+  resolveInstanceUrl,
+  resolveTargetSettings,
+} from '../src/config.ts';
+
+function ctx(manifest: Record<string, unknown>, targetConfig: Record<string, unknown> = {}): DeployContext {
+  return {
+    root: '/tmp',
+    target: 'mieweb',
+    manifest,
+    mieweb: {},
+    targetConfig,
+    argv: [],
+    logger: { info() {}, warn() {}, error() {} },
+    signal: new AbortController().signal,
+  };
+}
+
+describe('normalizeInstanceUrl', () => {
+  test('canonicalizes host case, trailing slash and /api/v1', () => {
+    assert.equal(normalizeInstanceUrl('https://OS.mieweb.org/'), 'https://os.mieweb.org');
+    assert.equal(normalizeInstanceUrl('http://localhost:3000/api/v1/'), 'http://localhost:3000');
+    assert.equal(normalizeInstanceUrl('https://x.test/manager'), 'https://x.test/manager');
+  });
+  test('rejects non-http and credentials', () => {
+    assert.throws(() => normalizeInstanceUrl('ftp://x'), ConfigError);
+    assert.throws(() => normalizeInstanceUrl('https://u:p@x'), ConfigError);
+    assert.throws(() => normalizeInstanceUrl('not a url'), ConfigError);
+  });
+});
+
+test('instance URL precedence: env → targetConfig → default', () => {
+  assert.equal(resolveInstanceUrl({ MIEWEB_OS_URL: 'http://a.test' }, { instanceUrl: 'http://b.test' }), 'http://a.test');
+  assert.equal(resolveInstanceUrl({}, { instanceUrl: 'http://b.test' }), 'http://b.test');
+  assert.equal(resolveInstanceUrl({}, {}), 'https://os.mieweb.org');
+});
+
+test('instanceFromArgv', () => {
+  assert.equal(instanceFromArgv(['--instance', 'http://a.test']), 'http://a.test');
+  assert.equal(instanceFromArgv(['-x', '--instance=http://b.test']), 'http://b.test');
+  assert.equal(instanceFromArgv([]), undefined);
+});
+
+describe('appName', () => {
+  test('must be a DNS label', () => {
+    assert.equal(appName({ name: 'my-app1' }), 'my-app1');
+    for (const bad of [undefined, '', 'My_App', '-x', 'x-', 'a'.repeat(64)]) {
+      assert.throws(() => appName({ name: bad }), ConfigError, String(bad));
+    }
+  });
+});
+
+describe('resolveTargetSettings', () => {
+  test('siteId is optional (chosen at deploy time), env overrides config, must be an integer', () => {
+    assert.equal(resolveTargetSettings(ctx({ name: 'app' }), {}).siteId, undefined);
+    assert.equal(resolveTargetSettings(ctx({ name: 'app' }, { siteId: 3 }), { MIEWEB_OS_SITE_ID: '5' }).siteId, 5);
+    assert.throws(() => resolveTargetSettings(ctx({ name: 'app' }), { MIEWEB_OS_SITE_ID: 'x' }), /MIEWEB_OS_SITE_ID must be/);
+    assert.throws(() => resolveTargetSettings(ctx({ name: 'app' }, { siteId: 'one' }), {}), /positive integer/);
+  });
+
+  test('defaults', () => {
+    const s = resolveTargetSettings(ctx({ name: 'app' }, { siteId: 3 }), {});
+    assert.equal(s.siteId, 3);
+    assert.equal(s.image, DEFAULT_IMAGE);
+    assert.equal(s.port, 8787);
+    assert.equal(s.externalHostname, 'app');
+    assert.equal(s.authRequired, false);
+    assert.deepEqual(s.services, []);
+    assert.equal(s.instanceUrl, 'https://os.mieweb.org');
+  });
+
+  test('overrides and extra services', () => {
+    const s = resolveTargetSettings(
+      ctx(
+        { name: 'app' },
+        {
+          siteId: '4',
+          image: 'ghcr.io/x/y:pr-1',
+          port: 3000,
+          externalHostname: 'www-app',
+          domain: 'apps.example.test',
+          authRequired: true,
+          services: [{ type: 'tcp', internalPort: 22 }, { type: 'srv', internalPort: 5060, dnsName: '_sip._udp' }],
+        },
+      ),
+      { MIEWEB_OS_URL: 'http://localhost:3000' },
+    );
+    assert.equal(s.siteId, 4);
+    assert.equal(s.image, 'ghcr.io/x/y:pr-1');
+    assert.equal(s.port, 3000);
+    assert.equal(s.externalHostname, 'www-app');
+    assert.equal(s.domain, 'apps.example.test');
+    assert.equal(s.authRequired, true);
+    assert.equal(s.services.length, 2);
+    assert.equal(s.instanceUrl, 'http://localhost:3000');
+  });
+
+  test('rejects bad service/port config', () => {
+    const base = { siteId: 1 };
+    assert.throws(() => resolveTargetSettings(ctx({ name: 'a' }, { ...base, port: 70000 }), {}), /TCP port/);
+    assert.throws(() => resolveTargetSettings(ctx({ name: 'a' }, { ...base, services: [{ type: 'http', internalPort: 1 }] }), {}), /tcp, udp or srv/);
+    assert.throws(() => resolveTargetSettings(ctx({ name: 'a' }, { ...base, services: [{ type: 'srv', internalPort: 1 }] }), {}), /dnsName/);
+    assert.throws(() => resolveTargetSettings(ctx({ name: 'a' }, { ...base, authRequired: 'yes' }), {}), /boolean/);
+  });
+});
diff --git a/packages/os-cloud-provider/test/deploy-helpers.test.ts b/packages/os-cloud-provider/test/deploy-helpers.test.ts
new file mode 100644
index 00000000..6cee7d21
--- /dev/null
+++ b/packages/os-cloud-provider/test/deploy-helpers.test.ts
@@ -0,0 +1,134 @@
+import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+import type { Container } from '../src/api-types.ts';
+import { buildEnv, envUnchanged, MANAGED_ENV, normalizeImageRef, pickDomain, planServices, servicesUnchanged } from '../src/deploy.ts';
+
+describe('normalizeImageRef (mirrors the Manager)', () => {
+  const cases: [string, string][] = [
+    ['nginx', 'docker.io/library/nginx:latest'],
+    ['nginx:1.27', 'docker.io/library/nginx:1.27'],
+    ['bitnami/redis', 'docker.io/bitnami/redis:latest'],
+    ['ghcr.io/mieweb/opensource-server/cloud', 'ghcr.io/mieweb/opensource-server/cloud:latest'],
+    ['ghcr.io/mieweb/opensource-server/cloud:sha-abc', 'ghcr.io/mieweb/opensource-server/cloud:sha-abc'],
+    ['localhost:5000/app', 'localhost:5000/library/app:latest'],
+  ];
+  for (const [input, want] of cases) {
+    test(input, () => assert.equal(normalizeImageRef(input), want));
+  }
+  test('idempotent', () => {
+    for (const [, want] of cases) assert.equal(normalizeImageRef(want), want);
+  });
+});
+
+describe('pickDomain', () => {
+  const form = { siteId: 1, nvidiaAvailable: false, externalDomains: [{ id: 3, name: 'a.test' }, { id: 4, name: 'b.test' }] };
+  test('defaults to the first (site default) domain', () => assert.deepEqual(pickDomain(form, undefined), { id: 3, name: 'a.test' }));
+  test('by name or id', () => {
+    assert.equal(pickDomain(form, 'b.test').id, 4);
+    assert.equal(pickDomain(form, 3).name, 'a.test');
+  });
+  test('unknown / none', () => {
+    assert.throws(() => pickDomain(form, 'c.test'), /not available.*a\.test \(3\)/);
+    assert.throws(() => pickDomain({ ...form, externalDomains: [] }, undefined), /no external domains/);
+  });
+});
+
+describe('buildEnv', () => {
+  const base = {
+    settings: { port: 8787, start: undefined },
+  };
+
+  test('vars + secrets + managed keys, full set', () => {
+    const warnings: string[] = [];
+    const env = buildEnv({
+      ...base,
+      manifest: { vars: { GREETING: 'hi', FLAGS: { a: 1 }, PORT: '1' } },
+      env: { MIEWEB_OS_SECRET_API_KEY: 's3cret', MIEWEB_OS_SECRET_: 'ignored', OTHER: 'x' },
+      warn: (m) => warnings.push(m),
+    });
+    const map = Object.fromEntries(env.map((e) => [e.key, e.value]));
+    assert.equal(map.GREETING, 'hi');
+    assert.equal(map.FLAGS, '{"a":1}');
+    assert.equal(map.API_KEY, 's3cret');
+    assert.equal(map.OTHER, undefined);
+    assert.equal(map[''], undefined);
+    assert.equal(map.PORT, '8787');
+    assert.equal(map.MIEWEB_S3_SECRET_ACCESS_KEY, map.MINIO_ROOT_PASSWORD);
+    assert.ok(map.MINIO_ROOT_PASSWORD!.length >= 24);
+    assert.equal(map.MIEWEB_LIBSQL_URL, 'http://127.0.0.1:8080');
+    assert.equal(map.MIEWEB_APP_START, undefined);
+    assert.deepEqual(warnings, ['Env var PORT is managed by the provider; ignoring the app\'s value']);
+  });
+
+  test('reuses the existing MinIO credentials', () => {
+    const env = buildEnv({
+      ...base,
+      manifest: {},
+      env: {},
+      existing: { [MANAGED_ENV.minioPassword]: 'keep-me', [MANAGED_ENV.minioUser]: 'u' },
+      warn: () => {},
+    });
+    const map = Object.fromEntries(env.map((e) => [e.key, e.value]));
+    assert.equal(map.MINIO_ROOT_PASSWORD, 'keep-me');
+    assert.equal(map.MINIO_ROOT_USER, 'u');
+    assert.equal(map.MIEWEB_S3_ACCESS_KEY_ID, 'u');
+  });
+});
+
+describe('planServices', () => {
+  const http = { internalPort: 8787, externalHostname: 'app', externalDomainId: 7, authRequired: false };
+  const svc = (id: number, port: number, host = 'app', domainId = 7): NonNullable<Container['services']>[number] => ({
+    id,
+    type: 'http',
+    internalPort: port,
+    httpService: { externalHostname: host, externalDomainId: domainId, backendProtocol: 'http', authRequired: true },
+  });
+
+  test('empty → create http', () => {
+    assert.deepEqual(planServices([], http, []), { http: { type: 'http', ...http } });
+  });
+
+  test('matching http is kept (authRequired toggled)', () => {
+    assert.deepEqual(planServices([svc(1, 8787)], http, []), {
+      'keep-1': { id: 1, type: 'http', internalPort: 8787, authRequired: false },
+    });
+  });
+
+  test('changed port / host / duplicates are replaced', () => {
+    const plan = planServices([svc(1, 3000), svc(2, 8787, 'other'), svc(3, 8787), svc(4, 8787)], http, []);
+    assert.deepEqual(Object.keys(plan).sort(), ['del-1', 'del-2', 'del-4', 'keep-3']);
+    assert.equal(plan['del-1']!.deleted, true);
+  });
+
+  test('non-http services are preserved; missing extras added', () => {
+    const current: Container['services'] = [
+      svc(1, 8787),
+      { id: 2, type: 'transport', internalPort: 22, transportService: { protocol: 'tcp', externalPort: 2222 } },
+    ];
+    const plan = planServices(current, http, [
+      { type: 'tcp', internalPort: 22 },
+      { type: 'udp', internalPort: 53 },
+      { type: 'srv', internalPort: 5060, dnsName: '_sip._udp' },
+    ]);
+    assert.deepEqual(plan['extra-1'], { type: 'udp', internalPort: 53 });
+    assert.deepEqual(plan['extra-2'], { type: 'srv', internalPort: 5060, dnsName: '_sip._udp' });
+    assert.equal(plan['extra-0'], undefined);
+    assert.equal(Object.values(plan).some((p) => p.id === 2), false);
+  });
+});
+
+describe('change detection', () => {
+  test('servicesUnchanged', () => {
+    const cur: Container['services'] = [
+      { id: 1, type: 'http', internalPort: 8787, httpService: { externalHostname: 'a', externalDomainId: 7, backendProtocol: 'http', authRequired: false } },
+    ];
+    assert.equal(servicesUnchanged(cur, { 'keep-1': { id: 1, type: 'http', internalPort: 8787, authRequired: false } }), true);
+    assert.equal(servicesUnchanged(cur, { 'keep-1': { id: 1, type: 'http', internalPort: 8787, authRequired: true } }), false);
+    assert.equal(servicesUnchanged(cur, { http: { type: 'http', internalPort: 1 } }), false);
+  });
+  test('envUnchanged', () => {
+    assert.equal(envUnchanged({ A: '1', B: '2' }, [{ key: 'B', value: '2' }, { key: 'A', value: '1' }]), true);
+    assert.equal(envUnchanged({ A: '1', B: '2' }, [{ key: 'A', value: '1' }]), false);
+    assert.equal(envUnchanged({ A: '1' }, [{ key: 'A', value: '2' }]), false);
+  });
+});
diff --git a/packages/os-cloud-provider/test/fake-manager.ts b/packages/os-cloud-provider/test/fake-manager.ts
new file mode 100644
index 00000000..7c651769
--- /dev/null
+++ b/packages/os-cloud-provider/test/fake-manager.ts
@@ -0,0 +1,303 @@
+/**
+ * In-memory fake of the Manager API surface the provider uses, served over
+ * real HTTP so the provider's fetch/abort/error handling is exercised as-is.
+ * Shapes follow create-a-container/openapi.v1.yaml.
+ */
+
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
+
+export interface FakeService {
+  id: number;
+  type: 'http' | 'transport' | 'dns';
+  internalPort: number;
+  httpService?: { externalHostname: string; externalDomainId: number; backendProtocol: 'http' | 'https'; authRequired: boolean };
+  transportService?: { protocol: 'tcp' | 'udp'; externalPort: number };
+  dnsService?: { recordType: 'SRV'; dnsName: string };
+}
+
+export interface FakeContainer {
+  id: number;
+  hostname: string;
+  owner: string;
+  template: string;
+  containerId: string | null;
+  nvidiaRequested: boolean;
+  entrypoint: string | null;
+  environmentVars: Record<string, string>;
+  services: FakeService[];
+  volumes: { id: number; name: string; mountPath: string; mode: 'ro' | 'rw' }[];
+  status?: string;
+  creationJobId?: number | null;
+}
+
+export interface FakeJob {
+  id: number;
+  status: 'pending' | 'running' | 'success' | 'failure' | 'cancelled';
+  polls: number;
+  logs: string[];
+  onSuccess?: () => void;
+}
+
+export interface RequestLog {
+  method: string;
+  path: string;
+  body?: any;
+}
+
+export class FakeManager {
+  readonly tokens = new Map<string, { user: string; keyId: string }>();
+  readonly containers: FakeContainer[] = [];
+  readonly jobs = new Map<number, FakeJob>();
+  readonly requests: RequestLog[] = [];
+  readonly domains = [{ id: 7, name: 'apps.example.test', siteId: 1 }];
+  readonly siteId = 1;
+  /** What GET /sites returns. */
+  sites: { id: number; name: string }[] = [{ id: 1, name: 'site-one' }];
+  nvidiaAvailable = false;
+  /** Emulate a Manager that predates volumes (#421). */
+  noVolumes = false;
+  /** Drop the connection for this many upcoming GET /jobs/:id requests. */
+  dropJobPolls = 0;
+  /** Status new jobs end in. */
+  jobOutcome: FakeJob['status'] = 'success';
+  /** Polls before a job leaves `running`. */
+  jobPolls = 1;
+  /** Called before POST /containers is processed (to simulate races). */
+  beforeCreate?: (hostname: string) => void;
+  /** Resolve GET /jobs/:id only after this promise (to test aborts). */
+  jobGate?: Promise<void>;
+  /** Handoff params the fake CLI-auth route will embed. */
+  nextKey = { key: 'minted-key', id: 'key-2', user: 'alice' };
+
+  private nextId = 100;
+  private nextVmid = 1000;
+  private nextPort = 2000;
+  private server = createServer((req, res) => {
+    this.handle(req, res).catch((err) => {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: { code: 'internal_error', message: String(err) } }));
+    });
+  });
+  url = '';
+
+  async start(): Promise<this> {
+    await new Promise<void>((r) => this.server.listen(0, '127.0.0.1', () => r()));
+    const addr = this.server.address() as { port: number };
+    this.url = `http://127.0.0.1:${addr.port}`;
+    return this;
+  }
+
+  async stop(): Promise<void> {
+    this.server.closeAllConnections();
+    await new Promise<void>((r) => this.server.close(() => r()));
+  }
+
+  addToken(token: string, user = 'alice', keyId = 'key-1'): void {
+    this.tokens.set(token, { user, keyId });
+  }
+
+  seedContainer(c: Partial<FakeContainer> & { hostname: string }): FakeContainer {
+    const full: FakeContainer = {
+      id: this.nextId++,
+      owner: 'alice',
+      template: 'ghcr.io/mieweb/opensource-server/cloud:latest',
+      containerId: String(this.nextVmid++),
+      nvidiaRequested: false,
+      entrypoint: null,
+      environmentVars: {},
+      services: [],
+      volumes: [],
+      ...c,
+    };
+    this.containers.push(full);
+    return full;
+  }
+
+  private newJob(): FakeJob {
+    const job: FakeJob = { id: this.nextId++, status: 'pending', polls: 0, logs: ['starting', 'done'] };
+    this.jobs.set(job.id, job);
+    return job;
+  }
+
+  private serialize(c: FakeContainer) {
+    const { volumes, ...rest } = c;
+    return {
+      ...rest,
+      ...(this.noVolumes ? {} : { volumes }),
+      status: c.status ?? (c.containerId ? 'running' : 'creating'),
+      sshPort: c.services.find((s) => s.type === 'transport' && s.internalPort === 22)?.transportService?.externalPort ?? null,
+      sshHost: 'ssh.example.test',
+      httpEntries: c.services
+        .filter((s) => s.type === 'http')
+        .map((s) => {
+          const d = this.domains.find((x) => x.id === s.httpService!.externalDomainId);
+          return { port: s.internalPort, externalUrl: d ? `https://${s.httpService!.externalHostname}.${d.name}` : null };
+        }),
+      services: c.services.map((s) => ({ ...s, lastAccessedAt: null })),
+    };
+  }
+
+  private addServices(c: FakeContainer, services: Record<string, any>): void {
+    for (const s of Object.values(services ?? {})) {
+      if (s.id || s.deleted) continue;
+      const id = this.nextId++;
+      if (s.type === 'http' || s.type === 'https') {
+        c.services.push({
+          id,
+          type: 'http',
+          internalPort: s.internalPort,
+          httpService: {
+            externalHostname: s.externalHostname,
+            externalDomainId: s.externalDomainId,
+            backendProtocol: s.type === 'https' ? 'https' : 'http',
+            authRequired: !!s.authRequired,
+          },
+        });
+      } else if (s.type === 'srv') {
+        c.services.push({ id, type: 'dns', internalPort: s.internalPort, dnsService: { recordType: 'SRV', dnsName: s.dnsName } });
+      } else {
+        c.services.push({ id, type: 'transport', internalPort: s.internalPort, transportService: { protocol: s.type, externalPort: this.nextPort++ } });
+      }
+    }
+  }
+
+  private async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const url = new URL(req.url!, 'http://x');
+    const path = url.pathname.replace(/^\/api\/v1/, '');
+    let raw = '';
+    for await (const chunk of req) raw += chunk;
+    const ctype = req.headers['content-type'] ?? '';
+    const body = raw ? (ctype.includes('json') ? JSON.parse(raw) : raw) : undefined;
+    this.requests.push({ method: req.method!, path: `${path}${url.search}`, body });
+
+    const send = (status: number, payload: unknown): void => {
+      res.writeHead(status, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(payload));
+    };
+    const ok = (data: unknown, status = 200): void => send(status, { data });
+    const fail = (status: number, code: string, message = code): void => send(status, { error: { code, message } });
+
+    if (req.method === 'GET' && path === '/health') return ok({ status: 'ok', oidcEnabled: false });
+
+    // Browser-facing CLI handoff (the real route requires a session + confirm;
+    // the fake just "approves" immediately).
+    if (path === '/auth/cli/callback' && req.method === 'GET') {
+      const port = url.searchParams.get('port');
+      const state = url.searchParams.get('state')!;
+      const frag = new URLSearchParams({ ...this.nextKey, state });
+      this.tokens.set(this.nextKey.key, { user: this.nextKey.user, keyId: this.nextKey.id });
+      res.writeHead(303, { Location: `http://127.0.0.1:${port}/callback#${frag}` });
+      res.end();
+      return;
+    }
+
+    const auth = req.headers.authorization ?? '';
+    const who = auth.startsWith('Bearer ') ? this.tokens.get(auth.slice(7)) : undefined;
+    if (!who) return fail(401, 'unauthorized', 'Authentication required');
+
+    if (req.method === 'GET' && path === '/session') return ok({ user: who.user, isAdmin: false });
+
+    let m = /^\/apikeys\/([^/]+)$/.exec(path);
+    if (m && req.method === 'DELETE') {
+      const id = decodeURIComponent(m[1]!);
+      for (const [tok, v] of this.tokens) if (v.keyId === id) this.tokens.delete(tok);
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    m = /^\/jobs\/(\d+)(\/status)?$/.exec(path);
+    if (m && req.method === 'GET' && !m[2] && this.dropJobPolls > 0) {
+      this.dropJobPolls -= 1;
+      req.socket.destroy();
+      return;
+    }
+    if (m && req.method === 'GET') {
+      const job = this.jobs.get(Number(m[1]));
+      if (!job) return fail(404, 'not_found');
+      if (m[2]) {
+        const offset = Number(url.searchParams.get('offset') ?? 0);
+        const rows = job.status === 'pending' ? [] : job.logs.map((output, i) => ({ id: i + 1, output }));
+        return ok(rows.slice(offset));
+      }
+      if (this.jobGate) await this.jobGate;
+      job.polls += 1;
+      if (job.status === 'pending') job.status = 'running';
+      else if (job.status === 'running' && job.polls > this.jobPolls) {
+        job.status = this.jobOutcome;
+        if (job.status === 'success') job.onSuccess?.();
+      }
+      return ok({ id: job.id, status: job.status });
+    }
+
+    if (path === '/sites' && req.method === 'GET') return ok(this.sites);
+
+    m = /^\/sites\/(\d+)\/containers(?:\/(new|\d+))?$/.exec(path);
+    if (!m) return fail(404, 'not_found');
+    if (Number(m[1]) !== this.siteId) return fail(404, 'site_not_found');
+    const sub = m[2];
+
+    if (sub === 'new' && req.method === 'GET') {
+      return ok({ siteId: this.siteId, externalDomains: this.domains, nvidiaAvailable: this.nvidiaAvailable });
+    }
+    if (!sub && req.method === 'GET') {
+      const hostname = url.searchParams.get('hostname');
+      return ok(
+        this.containers
+          .filter((c) => c.owner === who.user && (!hostname || c.hostname === hostname))
+          .map((c) => this.serialize(c)),
+      );
+    }
+    if (!sub && req.method === 'POST') {
+      this.beforeCreate?.(body.hostname);
+      if (this.containers.some((c) => c.hostname === body.hostname)) return fail(409, 'conflict', 'hostname taken');
+      const c: FakeContainer = {
+        id: this.nextId++,
+        hostname: body.hostname,
+        owner: who.user,
+        template: body.template,
+        containerId: null,
+        nvidiaRequested: !!body.nvidiaRequested,
+        entrypoint: body.entrypoint ?? null,
+        environmentVars: Object.fromEntries((body.environmentVars ?? []).map((e: any) => [e.key, e.value])),
+        services: [],
+        volumes: this.noVolumes ? [] : (body.volumes ?? []).map((v: any) => ({ id: this.nextId++, ...v })),
+      };
+      this.addServices(c, body.services);
+      this.containers.push(c);
+      const job = this.newJob();
+      // Provisioning "completes" (a VMID appears) when the job succeeds.
+      const vmid = String(this.nextVmid++);
+      job.onSuccess = () => {
+        c.containerId = vmid;
+      };
+      return ok({ containerId: c.id, jobId: job.id, hostname: c.hostname, status: 'creating' }, 201);
+    }
+
+    const c = this.containers.find((x) => x.id === Number(sub));
+    if (!c || c.owner !== who.user) return fail(404, 'not_found');
+    if (req.method === 'GET') return ok(this.serialize(c));
+    if (req.method === 'DELETE') {
+      this.containers.splice(this.containers.indexOf(c), 1);
+      return ok({ deleted: true, dnsWarnings: [] });
+    }
+    if (req.method === 'PUT') {
+      for (const s of Object.values<any>(body.services ?? {})) {
+        if (s.id && s.deleted) c.services = c.services.filter((x) => x.id !== s.id);
+      }
+      for (const s of Object.values<any>(body.services ?? {})) {
+        if (s.id && !s.deleted) {
+          const hit = c.services.find((x) => x.id === s.id);
+          if (hit?.httpService) hit.httpService.authRequired = !!s.authRequired;
+        }
+      }
+      this.addServices(c, body.services);
+      c.environmentVars = Object.fromEntries((body.environmentVars ?? []).map((e: any) => [e.key, e.value]));
+      c.entrypoint = body.entrypoint ?? null;
+      for (const v of body.volumes ?? []) c.volumes.push({ id: this.nextId++, ...v });
+      const job = body.restart ? this.newJob() : null;
+      return ok({ containerId: c.id, jobId: job?.id ?? null, dnsWarnings: [], pendingRestart: !body.restart });
+    }
+    return fail(405, 'method_not_allowed');
+  }
+}
diff --git a/packages/os-cloud-provider/test/fake-shell.ts b/packages/os-cloud-provider/test/fake-shell.ts
new file mode 100644
index 00000000..77b59233
--- /dev/null
+++ b/packages/os-cloud-provider/test/fake-shell.ts
@@ -0,0 +1,128 @@
+/**
+ * RemoteShell fake that executes the sync's remote commands against a local
+ * directory, so sync tests exercise the real tar/diff/delete logic.
+ */
+
+import { lstat, mkdir, readdir, rm, rmdir, symlink, utimes, lutimes, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { Readable } from 'node:stream';
+import tarStream from 'tar-stream';
+import type { ExecResult, RemoteShell } from '../src/ssh.ts';
+import { REMOTE } from '../src/sync.ts';
+
+async function toBuffer(stdin: Buffer | NodeJS.ReadableStream | undefined): Promise<Buffer> {
+  if (!stdin) return Buffer.alloc(0);
+  if (Buffer.isBuffer(stdin)) return stdin;
+  const chunks: Buffer[] = [];
+  for await (const c of stdin as AsyncIterable<Buffer>) chunks.push(Buffer.from(c));
+  return Buffer.concat(chunks);
+}
+
+export class FakeShell implements RemoteShell {
+  readonly commands: string[] = [];
+  readonly owners = new Map<string, string>();
+  closed = false;
+  readonly dir: string;
+  constructor(dir: string) {
+    this.dir = dir;
+  }
+
+  async exec(command: string, stdin?: Buffer | NodeJS.ReadableStream): Promise<ExecResult> {
+    this.commands.push(command);
+    const input = await toBuffer(stdin);
+    const ok = (stdout = Buffer.alloc(0)): ExecResult => ({ code: 0, stdout, stderr: '' });
+
+    if (command === REMOTE.list) {
+      await mkdir(this.dir, { recursive: true });
+      const out: string[] = [];
+      const walk = async (rel: string): Promise<void> => {
+        for (const e of await readdir(join(this.dir, rel), { withFileTypes: true })) {
+          const p = rel ? `${rel}/${e.name}` : e.name;
+          if (e.isDirectory()) await walk(p);
+          else {
+            const st = await lstat(join(this.dir, p));
+            out.push(p, String(st.size), String(st.mtimeMs / 1000));
+          }
+        }
+      };
+      await walk('');
+      return ok(Buffer.from(out.map((x) => `${x}\0`).join('')));
+    }
+    if (command === REMOTE.extract) {
+      const extract = tarStream.extract();
+      const done = (async () => {
+        for await (const entry of extract) {
+          const h = entry.header;
+          const target = join(this.dir, h.name);
+          this.owners.set(h.name, `${h.uname}:${h.gname}`);
+          if (h.type === 'directory') {
+            await mkdir(target, { recursive: true });
+            entry.resume();
+            continue;
+          }
+          await mkdir(dirname(target), { recursive: true });
+          await rm(target, { force: true });
+          if (h.type === 'symlink') {
+            await symlink(h.linkname!, target);
+            entry.resume();
+            await lutimes(target, h.mtime!, h.mtime!);
+            continue;
+          }
+          const chunks: Buffer[] = [];
+          for await (const c of entry) chunks.push(c as Buffer);
+          await writeFile(target, Buffer.concat(chunks), { mode: h.mode });
+          await utimes(target, h.mtime!, h.mtime!);
+        }
+      })();
+      Readable.from(input).pipe(extract as unknown as NodeJS.WritableStream);
+      await done;
+      return ok();
+    }
+    if (command === REMOTE.remove) {
+      for (const p of input.toString().split('\0').filter(Boolean)) await rm(join(this.dir, p), { force: true });
+      return ok();
+    }
+    if (command === REMOTE.pruneDirs) {
+      for (let d of input.toString().split('\0').filter(Boolean)) {
+        while (d && d !== '.') {
+          try {
+            await rmdir(join(this.dir, d));
+          } catch {
+            break;
+          }
+          d = dirname(d);
+        }
+      }
+      return ok();
+    }
+    if (command === REMOTE.logs) return ok(Buffer.from(this.recentLogs));
+    return { code: 127, stdout: Buffer.alloc(0), stderr: `unknown command: ${command}` };
+  }
+
+  /** What the restart stream emits / exits with. */
+  restartScript: { chunks: [string, 'stdout' | 'stderr'][]; code: number } = { chunks: [], code: 0 };
+  /** Output of the recent-logs command. */
+  recentLogs = '';
+
+  /** Chunks `stream()` emits (split across chunk boundaries on purpose), then the exit code. */
+  streamScript: { chunks: [string, 'stdout' | 'stderr'][]; code: number; hang?: boolean } = { chunks: [], code: 0 };
+
+  async stream(
+    command: string,
+    onData: (chunk: Buffer, stream: 'stdout' | 'stderr') => void,
+    signal: AbortSignal,
+  ): Promise<number> {
+    this.commands.push(command);
+    if (command === REMOTE.restart) {
+      for (const [c, w] of this.restartScript.chunks) onData(Buffer.from(c), w);
+      return this.restartScript.code;
+    }
+    for (const [c, w] of this.streamScript.chunks) onData(Buffer.from(c), w);
+    if (!this.streamScript.hang) return this.streamScript.code;
+    return new Promise((resolve) => signal.addEventListener('abort', () => resolve(-1), { once: true }));
+  }
+
+  close(): void {
+    this.closed = true;
+  }
+}
diff --git a/packages/os-cloud-provider/test/live.test.ts b/packages/os-cloud-provider/test/live.test.ts
new file mode 100644
index 00000000..f889f53a
--- /dev/null
+++ b/packages/os-cloud-provider/test/live.test.ts
@@ -0,0 +1,88 @@
+/**
+ * Live inner-loop test against a real Manager (`make dev`: SQLite + the
+ * DummyApi mock hypervisor at http://localhost:3000). Skipped unless
+ * MIEWEB_OS_LIVE=1.
+ *
+ *   MIEWEB_OS_LIVE=1 MIEWEB_OS_URL=http://localhost:3000 \
+ *   MIEWEB_OS_TOKEN=<key from POST /api/v1/apikeys> MIEWEB_OS_SITE_ID=1 \
+ *   pnpm test:live
+ *
+ * MIEWEB_OS_LIVE_IMAGE / MIEWEB_OS_LIVE_IMAGE2 pick the images for the create
+ * and image-change steps (default: the public `nodejs` and `base` images,
+ * since `cloud:latest` only exists after the first release).
+ *
+ * The code sync is disabled here (DummyApi containers have no SSH).
+ * Exercises the real API mapping + job polling end to end (create → update →
+ * image-change recreate → destroy) and runs the contract's live conformance
+ * suite with an `applyIds` hook. It creates and deletes a container named
+ * `os-provider-live-<random>` on that site.
+ */
+
+import { strict as assert } from 'node:assert';
+import { randomBytes } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { describe, test } from 'node:test';
+import type { DeployContext, ResourceHandle } from '@mieweb/deploy-contract';
+import { runProviderConformance } from '@mieweb/deploy-contract/testkit';
+import { createProvider } from '../src/index.ts';
+
+const live = process.env.MIEWEB_OS_LIVE === '1';
+const siteId = Number(process.env.MIEWEB_OS_SITE_ID ?? '1');
+const name = `os-provider-live-${randomBytes(3).toString('hex')}`;
+const image = process.env.MIEWEB_OS_LIVE_IMAGE ?? 'ghcr.io/mieweb/opensource-server/nodejs:latest';
+const image2 = process.env.MIEWEB_OS_LIVE_IMAGE2 ?? 'ghcr.io/mieweb/opensource-server/base:latest';
+// The DummyApi hypervisor has no real SSH endpoint, so skip the code sync.
+const targetConfig = { siteId, image, sync: false };
+
+function ctx(overrides: Partial<DeployContext> = {}): DeployContext {
+  return {
+    root: tmpdir(),
+    target: 'mieweb',
+    manifest: { name, vars: { HELLO: 'world' } },
+    mieweb: {},
+    targetConfig,
+    argv: [],
+    logger: { info: (m) => console.log(m), warn: (m) => console.warn(m), error: (m) => console.error(m) },
+    signal: AbortSignal.timeout(10 * 60 * 1000),
+    ...overrides,
+  };
+}
+
+describe('live Manager', { skip: !live && 'set MIEWEB_OS_LIVE=1 (see file header)' }, () => {
+  const provider = createProvider(process.env, { pollIntervalMs: 500 });
+
+  test('whoami', async () => {
+    const who = await provider.whoami!(ctx());
+    assert.equal(who.authenticated, true);
+  });
+
+  test('deploy → redeploy (same handle) → image change → destroy', async () => {
+    const first = await provider.deploy(ctx());
+    assert.equal(first.resources.length, 1);
+    assert.equal(first.resources[0]!.kind, 'container');
+    assert.match(first.resources[0]!.id, /\S/);
+
+    const second = await provider.deploy(ctx({ manifest: { name, vars: { HELLO: 'again' } } }));
+    assert.deepEqual(second.resources, first.resources);
+
+    const third = await provider.deploy(
+      ctx({ targetConfig: { ...targetConfig, image: image2 } }),
+    );
+    assert.equal(third.resources[0]!.binding, name);
+
+    await provider.destroy!(ctx());
+  });
+
+  test('conformance (live, with applyIds)', async () => {
+    const report = await runProviderConformance(provider, {
+      target: 'mieweb',
+      manifest: { name },
+      targetConfig,
+      root: tmpdir(),
+      live: true,
+      applyIds: (m: Readonly<Record<string, unknown>>, _r: readonly ResourceHandle[]) => ({ ...m }),
+    });
+    await provider.destroy!(ctx());
+    assert.deepEqual(report.failures, []);
+  });
+});
diff --git a/packages/os-cloud-provider/test/provider.test.ts b/packages/os-cloud-provider/test/provider.test.ts
new file mode 100644
index 00000000..bf537ec1
--- /dev/null
+++ b/packages/os-cloud-provider/test/provider.test.ts
@@ -0,0 +1,584 @@
+import { strict as assert } from 'node:assert';
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { after, afterEach, before, beforeEach, describe, test } from 'node:test';
+import { AuthError } from '@mieweb/deploy-contract';
+import type { DeployContext, ProviderEnv, ResourceHandle } from '@mieweb/deploy-contract';
+import { runProviderConformance } from '@mieweb/deploy-contract/testkit';
+import { createProvider, type ProviderOptions } from '../src/index.ts';
+import { SshError, type SshTarget } from '../src/ssh.ts';
+import { FakeManager } from './fake-manager.ts';
+import { FakeShell } from './fake-shell.ts';
+
+const TOKEN = 'test-token';
+
+let fake: FakeManager;
+let dir: string;
+/** The app worktree deployed by the tests, and the fake container's /opt/app/src. */
+let appRoot: string;
+let remoteDir: string;
+/** SSH sessions the provider opened, and SSH readiness waits. */
+let sessions: { target: SshTarget; shell: FakeShell }[];
+let sshWaits: string[];
+let connectError: Error | null;
+/** Errors thrown by the next connect attempts, in order (then success). */
+let connectFailures: Error[];
+/** Applied to each new FakeShell (e.g. to script `stream` output). */
+let setupShell: (s: FakeShell) => void;
+
+before(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'os-cloud-provider-'));
+});
+after(async () => {
+  await rm(dir, { recursive: true, force: true });
+});
+beforeEach(async () => {
+  fake = await new FakeManager().start();
+  fake.addToken(TOKEN);
+  appRoot = await mkdtemp(join(dir, 'app-'));
+  remoteDir = await mkdtemp(join(dir, 'remote-'));
+  await writeFile(join(appRoot, 'package.json'), '{"name":"myapp"}');
+  await writeFile(join(appRoot, '.gitignore'), 'node_modules/\n');
+  sessions = [];
+  sshWaits = [];
+  connectError = null;
+  connectFailures = [];
+  setupShell = () => {};
+});
+afterEach(async () => {
+  await fake.stop();
+});
+
+interface Harness {
+  ctx: DeployContext;
+  logs: string[];
+  abort: AbortController;
+}
+
+function harness(opts: { manifest?: Record<string, unknown>; targetConfig?: Record<string, unknown>; argv?: string[] } = {}): Harness {
+  const logs: string[] = [];
+  const abort = new AbortController();
+  return {
+    logs,
+    abort,
+    ctx: {
+      root: appRoot,
+      target: 'mieweb',
+      manifest: opts.manifest ?? { name: 'myapp', vars: { GREETING: 'hi' } },
+      mieweb: {},
+      targetConfig: opts.targetConfig ?? { siteId: 1 },
+      argv: opts.argv ?? [],
+      logger: {
+        info: (m) => logs.push(`info:${m}`),
+        warn: (m) => logs.push(`warn:${m}`),
+        error: (m) => logs.push(`error:${m}`),
+      },
+      signal: abort.signal,
+    },
+  };
+}
+
+function provider(env: ProviderEnv = {}, options: ProviderOptions = {}) {
+  return createProvider(
+    { HOME: dir, MIEWEB_OS_URL: fake.url, MIEWEB_OS_TOKEN: TOKEN, MIEWEB_OS_CREDENTIALS: join(dir, `creds-${Math.random()}.json`), ...env },
+    {
+      pollIntervalMs: 5,
+      sshRetryDelayMs: 5,
+      connectSsh: async (target) => {
+        if (connectError) throw connectError;
+        const next = connectFailures.shift();
+        if (next) throw next;
+        const shell = new FakeShell(remoteDir);
+        setupShell(shell);
+        sessions.push({ target, shell });
+        return shell;
+      },
+      waitForSsh: async (host, port) => {
+        sshWaits.push(`${host}:${port}`);
+      },
+      ...options,
+    },
+  );
+}
+
+describe('contract', () => {
+  test('passes structural conformance', async () => {
+    const report = await runProviderConformance(provider(), { target: 'mieweb', manifest: { name: 'myapp' } });
+    assert.deepEqual(report.failures, []);
+  });
+
+  test('passes live conformance (handle stability) against the fake Manager', async () => {
+    const report = await runProviderConformance(provider(), {
+      target: 'mieweb',
+      manifest: { name: 'myapp' },
+      targetConfig: { siteId: 1 },
+      root: dir,
+      live: true,
+      // Identity is the hostname, which is already in the manifest.
+      applyIds: (m: Readonly<Record<string, unknown>>, _r: readonly ResourceHandle[]) => ({ ...m }),
+    });
+    assert.deepEqual(report.failures, []);
+    assert.equal(fake.containers.length, 1);
+  });
+
+  test('supports only the mieweb target; dev and tail are omitted', () => {
+    const p = provider();
+    assert.equal(p.name, 'opensource-server');
+    assert.equal(p.supports('mieweb'), true);
+    assert.equal(p.supports('cloudflare'), false);
+    assert.equal(p.dev, undefined);
+    assert.equal(typeof p.tail, 'function');
+  });
+});
+
+describe('deploy', () => {
+  test('creates the container with http + ssh services, env, and the data volume', async () => {
+    await mkdir(join(dir, '.mieweb'), { recursive: true });
+    await writeFile(join(dir, '.mieweb', 'known_hosts'), '[ssh.example.test]:2000 SHA256:stale\n[other]:22 SHA256:keep\n');
+    const h = harness();
+    const result = await provider({ MIEWEB_OS_SECRET_API_KEY: 'k' }).deploy(h.ctx);
+
+    assert.equal(fake.containers.length, 1);
+    const c = fake.containers[0]!;
+    assert.equal(c.hostname, 'myapp');
+    assert.equal(c.template, 'ghcr.io/mieweb/opensource-server/cloud:latest');
+    assert.deepEqual(c.volumes.map(({ name, mountPath, mode }) => ({ name, mountPath, mode })), [
+      { name: 'data', mountPath: '/mnt/data', mode: 'rw' },
+    ]);
+    assert.equal(c.services.length, 2);
+    assert.deepEqual(
+      c.services.filter((x) => x.type === 'transport').map((x) => [x.internalPort, x.transportService!.protocol]),
+      [[22, 'tcp']],
+    );
+    assert.deepEqual(c.services[0]!.httpService, {
+      externalHostname: 'myapp',
+      externalDomainId: 7,
+      backendProtocol: 'http',
+      authRequired: false,
+    });
+    assert.equal(c.services[0]!.internalPort, 8787);
+    assert.equal(c.environmentVars.GREETING, 'hi');
+    assert.equal(c.environmentVars.API_KEY, 'k');
+    assert.equal(c.environmentVars.MIEWEB_APP_SOURCE, undefined);
+
+    // id is the hypervisor VMID read back after the job, not the DB id.
+    assert.deepEqual(result, {
+      url: 'https://myapp.apps.example.test',
+      resources: [{ binding: 'myapp', kind: 'container', id: c.containerId }],
+    });
+    assert.notEqual(c.containerId, String(c.id));
+    assert.ok(h.logs.some((l) => l.includes('[job ')), 'job output is forwarded to the logger');
+    assert.ok(!fake.requests.some((r) => r.path.startsWith('/jobs/') && r.path.endsWith('/stream')));
+
+    // Fresh container: forget the stale host key, wait for SSH, sync, restart.
+    const sshPort = c.services.find((x) => x.internalPort === 22)!.transportService!.externalPort;
+    assert.equal(sshPort, 2000);
+    assert.equal(await readFile(join(dir, '.mieweb', 'known_hosts'), 'utf8'), '[other]:22 SHA256:keep\n');
+    assert.deepEqual(sshWaits, [`ssh.example.test:${sshPort}`]);
+    assert.equal(sessions.length, 1);
+    assert.deepEqual(sessions[0]!.target, { host: 'ssh.example.test', port: sshPort, user: 'alice' }, 'ssh user = Manager account');
+    assert.equal(await readFile(join(remoteDir, 'package.json'), 'utf8'), '{"name":"myapp"}');
+    assert.match(sessions[0]!.shell.commands.at(-1)!, /systemctl restart app\.service/);
+    assert.equal(sessions[0]!.shell.closed, true);
+  });
+
+  test('redeploy with no config change only syncs code (no Manager writes)', async () => {
+    const p = provider();
+    const first = await p.deploy(harness().ctx);
+    const writes = fake.requests.filter((r) => r.method !== 'GET').length;
+    await writeFile(join(appRoot, 'new.js'), 'x');
+
+    const h = harness();
+    const second = await p.deploy(h.ctx);
+    assert.deepEqual(second, first);
+    assert.equal(fake.requests.filter((r) => r.method !== 'GET').length, writes);
+    assert.equal(sessions.length, 2);
+    assert.equal(await readFile(join(remoteDir, 'new.js'), 'utf8'), 'x');
+    assert.ok(h.logs.some((l) => l.includes('configuration is up to date')));
+  });
+
+  test('sync user / host overrides and sync: false', async () => {
+    const p = provider({ MIEWEB_OS_SSH_USER: 'root' });
+    await p.deploy(harness({ targetConfig: { siteId: 1, sshHost: '10.0.0.5' } }).ctx);
+    assert.deepEqual(sessions[0]!.target, { host: '10.0.0.5', port: 2000, user: 'root' });
+
+    const h = harness({ targetConfig: { siteId: 1, sync: false } });
+    await p.deploy(h.ctx);
+    assert.equal(sessions.length, 1);
+    assert.ok(h.logs.some((l) => l.includes('sync disabled')));
+  });
+
+  test('transient SSH failures after create are retried', async () => {
+    connectFailures = [
+      new SshError('network', 'SSH connection to ssh.example.test:2000 failed: connect ECONNREFUSED'),
+      new SshError('network', 'SSH connection to ssh.example.test:2000 failed: Timed out while waiting for handshake'),
+      new SshError('auth', 'SSH authentication as alice@ssh.example.test:2000 failed.'),
+    ];
+    const h = harness();
+    const result = await provider().deploy(h.ctx);
+    assert.equal(result.resources.length, 1);
+    assert.equal(connectFailures.length, 0);
+    assert.equal(sessions.length, 1);
+    assert.equal(h.logs.filter((l) => l.includes('SSH not ready yet')).length, 3);
+  });
+
+  test('SSH retries stop at the time budget', async () => {
+    connectError = new SshError('network', 'SSH connection to ssh.example.test:2000 failed: connect ECONNREFUSED');
+    const p = provider({}, { sshTimeoutMs: 60, sshRetryDelayMs: 10 });
+    await assert.rejects(p.deploy(harness().ctx), /SSH on ssh\.example\.test:2000 was not usable within 0s \(\d+ attempts\)/);
+  });
+
+  test('auth failures on an existing container and host-key changes are not retried', async () => {
+    const p = provider();
+    await p.deploy(harness().ctx);
+    connectFailures = [new SshError('auth', 'SSH authentication as alice failed.')];
+    await assert.rejects(p.deploy(harness().ctx), /SSH authentication as alice failed/);
+    connectFailures = [new SshError('hostkey', 'SSH host key for x changed')];
+    await assert.rejects(p.deploy(harness().ctx), /host key for x changed/);
+  });
+
+  test('an SSH failure fails the deploy', async () => {
+    connectError = new SshError('auth', 'SSH authentication as alice@ssh.example.test:2000 failed.');
+    const p = provider({}, { sshTimeoutMs: 100 });
+    await assert.rejects(p.deploy(harness().ctx), /SSH authentication as alice/);
+  });
+
+  test('old source/ref settings are rejected with an explanation', async () => {
+    await assert.rejects(
+      provider().deploy(harness({ targetConfig: { siteId: 1, source: 'https://x/y' } }).ctx),
+      /syncs your local worktree/,
+    );
+  });
+
+  test('redeploy with the same image updates in place and keeps the MinIO secret', async () => {
+    const p = provider();
+    const first = await p.deploy(harness().ctx);
+    const pw = fake.containers[0]!.environmentVars.MINIO_ROOT_PASSWORD;
+
+    const h = harness({
+      manifest: { name: 'myapp', vars: { GREETING: 'hello' } },
+      targetConfig: { siteId: 1, authRequired: true },
+    });
+    const second = await p.deploy(h.ctx);
+
+    assert.deepEqual(second, first);
+    assert.equal(fake.containers.length, 1);
+    const c = fake.containers[0]!;
+    assert.equal(c.environmentVars.MINIO_ROOT_PASSWORD, pw);
+    assert.equal(c.environmentVars.GREETING, 'hello');
+    assert.equal(c.services.length, 2);
+    assert.equal(c.services.find((x) => x.type === 'http')!.httpService!.authRequired, true);
+    const put = fake.requests.find((r) => r.method === 'PUT')!;
+    assert.equal(put.body.restart, true);
+    assert.equal(put.body.volumes, undefined, 'volume already attached');
+    assert.ok(!fake.requests.some((r) => r.method === 'DELETE'));
+  });
+
+  test('changing the port replaces the http service', async () => {
+    const p = provider();
+    await p.deploy(harness().ctx);
+    const oldId = fake.containers[0]!.services[0]!.id;
+    await p.deploy(harness({ targetConfig: { siteId: 1, port: 3000 } }).ctx);
+    const svcs = fake.containers[0]!.services.filter((x) => x.type === 'http');
+    assert.equal(svcs.length, 1);
+    assert.notEqual(svcs[0]!.id, oldId);
+    assert.equal(svcs[0]!.internalPort, 3000);
+  });
+
+  test('an existing container without the data volume gets it attached', async () => {
+    fake.seedContainer({ hostname: 'myapp' });
+    await provider().deploy(harness().ctx);
+    const put = fake.requests.find((r) => r.method === 'PUT')!;
+    assert.deepEqual(put.body.volumes, [{ name: 'data', mountPath: '/mnt/data', mode: 'rw' }]);
+  });
+
+  test('image change → delete + recreate, carrying the MinIO secret', async () => {
+    fake.seedContainer({
+      hostname: 'myapp',
+      template: 'ghcr.io/mieweb/opensource-server/cloud:old',
+      environmentVars: { MINIO_ROOT_USER: 'mieweb', MINIO_ROOT_PASSWORD: 'persisted' },
+      volumes: [{ id: 1, name: 'data', mountPath: '/mnt/data', mode: 'rw' }],
+    });
+    const h = harness({ targetConfig: { siteId: 1, image: 'ghcr.io/mieweb/opensource-server/cloud:sha-new' } });
+    await provider().deploy(h.ctx);
+    const methods = fake.requests.filter((r) => r.method !== 'GET').map((r) => r.method);
+    assert.deepEqual(methods, ['DELETE', 'POST']);
+    const c = fake.containers[0]!;
+    assert.equal(c.template, 'ghcr.io/mieweb/opensource-server/cloud:sha-new');
+    assert.equal(c.environmentVars.MINIO_ROOT_PASSWORD, 'persisted');
+    assert.ok(h.logs.some((l) => l.includes('Recreating')));
+  });
+
+  test('a container whose create failed is recreated, not updated', async () => {
+    fake.seedContainer({ hostname: 'myapp', containerId: null, status: 'failed' });
+    const h = harness();
+    const result = await provider().deploy(h.ctx);
+    const methods = fake.requests.filter((r) => r.method !== 'GET').map((r) => r.method);
+    assert.deepEqual(methods, ['DELETE', 'POST']);
+    assert.equal(result.resources[0]!.id, fake.containers[0]!.containerId);
+    assert.ok(h.logs.some((l) => l.includes('not provisioned (status failed)')));
+  });
+
+  test('AI binding requests a GPU only when the site has one; nvidia drift recreates', async () => {
+    fake.nvidiaAvailable = true;
+    fake.seedContainer({ hostname: 'myapp' });
+    await provider().deploy(harness({ manifest: { name: 'myapp', ai: { binding: 'AI' } } }).ctx);
+    assert.equal(fake.containers[0]!.nvidiaRequested, true);
+    assert.ok(fake.requests.some((r) => r.method === 'DELETE'));
+  });
+
+  test('a lost create race (409 conflict) is converged with an update', async () => {
+    fake.beforeCreate = (hostname) => {
+      fake.beforeCreate = undefined;
+      fake.seedContainer({ hostname });
+    };
+    await provider().deploy(harness().ctx);
+    assert.equal(fake.containers.length, 1);
+    assert.ok(fake.requests.some((r) => r.method === 'PUT'));
+  });
+
+  test('a hostname owned by someone else is a clear error', async () => {
+    fake.seedContainer({ hostname: 'myapp', owner: 'bob' });
+    await assert.rejects(provider().deploy(harness().ctx), /already taken on site 1/);
+  });
+
+  test('dropped connections while polling are retried', async () => {
+    fake.dropJobPolls = 2;
+    const result = await provider().deploy(harness().ctx);
+    assert.equal(result.resources.length, 1);
+    assert.equal(fake.dropJobPolls, 0);
+  });
+
+  test('a Manager without volume support: warn, and redeploys stay sync-only', async () => {
+    fake.noVolumes = true;
+    const p = provider();
+    await p.deploy(harness().ctx);
+    const writes = fake.requests.filter((r) => r.method !== 'GET').length;
+    const h = harness();
+    await p.deploy(h.ctx);
+    assert.equal(fake.requests.filter((r) => r.method !== 'GET').length, writes, 'no PUT/restart');
+    assert.ok(h.logs.some((l) => l.startsWith('warn:This Manager does not support volumes')));
+    assert.equal(sessions.length, 2);
+  });
+
+  test('a failed job fails the deploy with its output', async () => {
+    fake.jobOutcome = 'failure';
+    await assert.rejects(provider().deploy(harness().ctx), /job \d+ ended with status "failure":\nstarting\ndone/);
+  });
+
+  test('abort cancels job polling', async () => {
+    let release!: () => void;
+    fake.jobGate = new Promise((r) => (release = r));
+    const h = harness();
+    const run = provider().deploy(h.ctx);
+    setTimeout(() => h.abort.abort(new Error('user cancelled')), 50);
+    await assert.rejects(run, /user cancelled/);
+    release();
+  });
+
+  test('config errors are reported before any request', async () => {
+    await assert.rejects(provider().deploy(harness({ manifest: { name: 'Bad_Name' } }).ctx), /DNS label/);
+    await assert.rejects(provider().deploy(harness({ targetConfig: { siteId: 1, domain: 'nope.test' } }).ctx), /not available/);
+    assert.ok(fake.requests.every((r) => r.method === 'GET'));
+  });
+
+  test('no siteId: uses the only site, prompts among several, errors when not interactive', async () => {
+    const only = harness({ targetConfig: {} });
+    await provider().deploy(only.ctx);
+    assert.ok(fake.requests.some((r) => r.path.startsWith('/sites/1/containers')));
+    assert.ok(only.logs.some((l) => l.includes('Set targets.mieweb.siteId to 1')), 'hint when the host cannot persist');
+
+    // Host with persistTargetConfig: the choice is saved, no hint.
+    const saved: Record<string, unknown>[] = [];
+    const h = harness({ targetConfig: {} });
+    await provider().deploy({ ...h.ctx, persistTargetConfig: async (p) => { saved.push({ ...p }); return true; } });
+    assert.deepEqual(saved, [{ siteId: 1 }]);
+    assert.ok(!h.logs.some((l) => l.includes('Set targets.mieweb.siteId')));
+
+    fake.sites = [{ id: 1, name: 'site-one' }, { id: 2, name: 'site-two' }];
+    try {
+      const asked: string[] = [];
+      const answers = ['nope', 'site-one'];
+      const p = provider({}, { prompt: async (q) => { asked.push(q); return answers.shift() ?? null; } });
+      await p.deploy(harness({ targetConfig: {} }).ctx);
+      assert.equal(asked.length, 2);
+      assert.match(asked[0] ?? '', /1\) site-one\n  2\) site-two/);
+
+      await assert.rejects(
+        provider({}, { prompt: async () => null }).deploy(harness({ targetConfig: {} }).ctx),
+        /siteId is required[\s\S]*2\) site-two/,
+      );
+    } finally {
+      fake.sites = [{ id: 1, name: 'site-one' }];
+    }
+  });
+
+  test('401 → AuthError with a login hint; no token → AuthError without a request', async () => {
+    const bad = provider({ MIEWEB_OS_TOKEN: 'wrong' });
+    await assert.rejects(bad.deploy(harness().ctx), (err: unknown) => {
+      assert.ok(err instanceof AuthError);
+      assert.match((err as AuthError).hint ?? '', /MIEWEB_OS_TOKEN/);
+      return true;
+    });
+    const before = fake.requests.length;
+    await assert.rejects(provider({ MIEWEB_OS_TOKEN: '' }).deploy(harness().ctx), AuthError);
+    assert.equal(fake.requests.length, before);
+  });
+
+  test('never reads secrets from targetConfig', async () => {
+    const h = harness({ targetConfig: { siteId: 1, token: TOKEN, apiKey: TOKEN } });
+    await assert.rejects(provider({ MIEWEB_OS_TOKEN: '' }).deploy(h.ctx), AuthError);
+  });
+});
+
+describe('tail', () => {
+  test('streams app.service journal lines to the logger over SSH', async () => {
+    const p = provider();
+    await p.deploy(harness().ctx);
+    setupShell = (s) => {
+      s.streamScript = {
+        chunks: [['line one\nline t', 'stdout'], ['wo\n', 'stdout'], ['oops\n', 'stderr'], ['tail-no-newline', 'stdout']],
+        code: 0,
+      };
+    };
+    const h = harness({ argv: ['-n', '20', '--no-follow', '--since', '-1h'] });
+    await p.tail!(h.ctx);
+    const shell = sessions.at(-1)!.shell;
+    assert.equal(shell.commands.at(-1), "sudo journalctl -u app.service -o cat --no-pager -n 20 --since '-1h'");
+    assert.equal(shell.closed, true);
+    const out = h.logs.filter((l) => !l.includes('Tailing') && !l.includes('Connecting'));
+    assert.deepEqual(out, ['info:line one', 'info:line two', 'warn:oops', 'info:tail-no-newline']);
+  });
+
+  test('follows by default until aborted', async () => {
+    const p = provider();
+    await p.deploy(harness().ctx);
+    setupShell = (s) => {
+      s.streamScript = { chunks: [['hello\n', 'stdout']], code: 0, hang: true };
+    };
+    const h = harness();
+    const run = p.tail!(h.ctx);
+    setTimeout(() => h.abort.abort(), 30);
+    await run;
+    assert.match(sessions.at(-1)!.shell.commands.at(-1)!, / -n 100 -f$/);
+    assert.ok(h.logs.includes('info:hello'));
+  });
+
+  test('errors: no container, bad args, journalctl failure', async () => {
+    const p = provider();
+    await assert.rejects(p.tail!(harness().ctx), /No container "myapp".*mieweb deploy/);
+    await assert.rejects(p.tail!(harness({ argv: ['--bogus'] }).ctx), /Unknown tail option/);
+    await assert.rejects(p.tail!(harness({ argv: ['--since', '$(rm -rf /)'] }).ctx), /not a valid time/);
+    await p.deploy(harness().ctx);
+    setupShell = (s) => {
+      s.streamScript = { chunks: [], code: 1 };
+    };
+    await assert.rejects(p.tail!(harness().ctx), /journalctl exited with code 1/);
+  });
+});
+
+describe('destroy', () => {
+  test('deletes by hostname; no-op when absent', async () => {
+    const p = provider();
+    await p.deploy(harness().ctx);
+    const h = harness();
+    await p.destroy!(h.ctx);
+    assert.equal(fake.containers.length, 0);
+    assert.ok(h.logs.some((l) => l.includes('retained')));
+
+    const h2 = harness();
+    await p.destroy!(h2.ctx);
+    assert.ok(h2.logs.some((l) => l.includes('nothing to destroy')));
+  });
+});
+
+describe('whoami', () => {
+  test('env token', async () => {
+    assert.deepEqual(await provider().whoami!(harness().ctx), { authenticated: true, account: 'alice', method: 'env' });
+  });
+  test('bad token / no token', async () => {
+    assert.deepEqual(await provider({ MIEWEB_OS_TOKEN: 'nope' }).whoami!(harness().ctx), { authenticated: false, method: 'env' });
+    assert.deepEqual(await provider({ MIEWEB_OS_TOKEN: '' }).whoami!(harness().ctx), { authenticated: false });
+  });
+});
+
+describe('login / logout', () => {
+  /** Plays the browser: follow the Manager redirect, load the loopback page, post the fragment. */
+  async function browser(url: string): Promise<void> {
+    const res = await fetch(url, { redirect: 'manual' });
+    const loc = new URL(res.headers.get('location')!);
+    const page = await fetch(`${loc.origin}${loc.pathname}`);
+    assert.match(await page.text(), /Finishing sign-in/);
+    const post = await fetch(`${loc.origin}/token`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'text/plain', Origin: loc.origin },
+      body: loc.hash.slice(1),
+    });
+    assert.equal(post.status, 200);
+  }
+
+  test('loopback handoff stores the key per instance; whoami uses it; logout revokes it', async () => {
+    const creds = join(dir, 'login-creds.json');
+    const env = { MIEWEB_OS_TOKEN: '', MIEWEB_OS_CREDENTIALS: creds };
+    let opened = '';
+    const p = provider(env, {
+      login: {
+        openBrowser: (u) => {
+          opened = u;
+          void browser(u);
+        },
+      },
+    });
+
+    const h = harness({ argv: ['--instance', `${fake.url}/`] });
+    await p.login!(h.ctx);
+    const q = new URL(opened).searchParams;
+    assert.equal(new URL(opened).pathname, '/api/v1/auth/cli/callback');
+    assert.match(q.get('state')!, /^[A-Za-z0-9_-]{32}$/);
+    assert.match(q.get('client')!, /^mieweb-cli@/);
+
+    const stored = JSON.parse(await readFile(creds, 'utf8'));
+    assert.deepEqual(Object.keys(stored.instances), [fake.url]);
+    assert.equal(stored.instances[fake.url].token, 'minted-key');
+    assert.equal(stored.instances[fake.url].apiKeyId, 'key-2');
+    assert.equal((await stat(creds)).mode & 0o777, 0o600);
+
+    assert.deepEqual(await p.whoami!(harness().ctx), { authenticated: true, account: 'alice', method: 'login' });
+
+    // Logging in again revokes the key it replaces.
+    fake.nextKey = { key: 'minted-key-2', id: 'key-3', user: 'alice' };
+    await p.login!(h.ctx);
+    assert.equal(fake.tokens.has('minted-key'), false);
+
+    await p.logout!(harness().ctx);
+    assert.equal(fake.tokens.has('minted-key-2'), false, 'key revoked server-side');
+    assert.deepEqual(JSON.parse(await readFile(creds, 'utf8')).instances, {});
+    assert.deepEqual(await p.whoami!(harness().ctx), { authenticated: false });
+  });
+
+  test('a handoff with the wrong state is rejected', async () => {
+    const env = { MIEWEB_OS_TOKEN: '', MIEWEB_OS_CREDENTIALS: join(dir, 'state-creds.json') };
+    let status = 0;
+    const p = provider(env, {
+      login: {
+        timeoutMs: 300,
+        openBrowser: (u) => {
+          const port = new URL(u).searchParams.get('port');
+          void fetch(`http://127.0.0.1:${port}/token`, { method: 'POST', body: 'key=k&id=i&state=forged' }).then(
+            (r) => (status = r.status),
+          );
+        },
+      },
+    });
+    await assert.rejects(p.login!(harness().ctx), /Timed out/);
+    assert.equal(status, 400);
+  });
+
+  test('logout warns that an env token cannot be cleared', async () => {
+    const h = harness();
+    await provider({ MIEWEB_OS_CREDENTIALS: join(dir, 'none.json') }).logout!(h.ctx);
+    assert.ok(h.logs.some((l) => l.startsWith('warn:MIEWEB_OS_TOKEN')));
+    assert.ok(h.logs.some((l) => l.includes('Not logged in')));
+  });
+});
diff --git a/packages/os-cloud-provider/test/ssh.test.ts b/packages/os-cloud-provider/test/ssh.test.ts
new file mode 100644
index 00000000..22e158ab
--- /dev/null
+++ b/packages/os-cloud-provider/test/ssh.test.ts
@@ -0,0 +1,236 @@
+/**
+ * SshConnection against an in-process ssh2 server: auth fallbacks, host-key
+ * pinning, and exec with stdin.
+ */
+
+import { strict as assert } from 'node:assert';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { after, before, describe, test } from 'node:test';
+import { timingSafeEqual } from 'node:crypto';
+import ssh2 from 'ssh2';
+import type { AuthContext, Connection } from 'ssh2';
+import { forgetHostKey, SshConnection, waitForSsh } from '../src/ssh.ts';
+
+const { Server, utils } = ssh2;
+const logger = { info() {}, warn() {}, error() {} };
+
+interface ServerHandle {
+  port: number;
+  close: () => Promise<void>;
+  authAttempts: string[];
+}
+
+function startServer(opts: { password?: string; publicKey?: Buffer; hostKey: string }): Promise<ServerHandle> {
+  const authAttempts: string[] = [];
+  const allowed = opts.publicKey ? utils.parseKey(opts.publicKey) : null;
+  const server = new Server({ hostKeys: [opts.hostKey] }, (client: Connection) => {
+    client.on('authentication', (ctx: AuthContext) => {
+      authAttempts.push(ctx.method);
+      if (ctx.method === 'password' && opts.password && ctx.password === opts.password) return ctx.accept();
+      if (ctx.method === 'publickey' && allowed && !(allowed instanceof Error)) {
+        const same =
+          ctx.key.algo === allowed.type && timingSafeEqual(ctx.key.data, allowed.getPublicSSH());
+        if (same && (!ctx.signature || allowed.verify(ctx.blob!, ctx.signature, ctx.hashAlgo))) return ctx.accept();
+      }
+      ctx.reject(['password', 'publickey']);
+    });
+    client.on('ready', () => {
+      client.on('session', (accept) => {
+        const session = accept();
+        session.on('exec', (acceptExec, _reject, info) => {
+          const stream = acceptExec();
+          const chunks: Buffer[] = [];
+          stream.on('data', (d: Buffer) => chunks.push(d));
+          stream.on('end', () => {
+            if (info.command === 'follow') {
+              stream.write('a\n');
+              stream.stderr.write('e\n');
+              const t = setInterval(() => stream.write('tick\n'), 10);
+              stream.on('close', () => clearInterval(t));
+              return;
+            }
+            if (info.command === 'fail') {
+              stream.stderr.write('boom');
+              stream.exit(3);
+            } else {
+              stream.write(`${info.command}:${Buffer.concat(chunks).toString()}`);
+              stream.exit(0);
+            }
+            stream.end();
+          });
+        });
+      });
+    });
+    client.on('error', () => {});
+  });
+  return new Promise((resolve) => {
+    server.listen(0, '127.0.0.1', () => {
+      resolve({
+        port: (server.address() as { port: number }).port,
+        authAttempts,
+        close: () => new Promise((r) => server.close(() => r())),
+      });
+    });
+  });
+}
+
+let home: string;
+const hostKeyA = utils.generateKeyPairSync('ed25519').private;
+const hostKeyB = utils.generateKeyPairSync('ed25519').private;
+const userKey = utils.generateKeyPairSync('ed25519');
+
+before(async () => {
+  home = await mkdtemp(join(tmpdir(), 'os-ssh-'));
+});
+after(async () => {
+  await rm(home, { recursive: true, force: true });
+});
+
+const signal = (): AbortSignal => AbortSignal.timeout(20_000);
+
+describe('SshConnection', () => {
+  test('password fallback via prompt (asked once), exec with stdin, host key pinned', async () => {
+    const srv = await startServer({ password: 's3cret', hostKey: hostKeyA });
+    const knownHostsFile = join(home, 'kh1');
+    const prompts: string[] = [];
+    const env = { HOME: join(home, 'nokeys'), SSH_AUTH_SOCK: '' };
+    try {
+      const conn = await SshConnection.connect({
+        target: { host: '127.0.0.1', port: srv.port, user: 'alice' },
+        env,
+        knownHostsFile,
+        interactive: true,
+        prompt: async (q) => {
+          prompts.push(q);
+          return 's3cret';
+        },
+        signal: signal(),
+        logger,
+      });
+      const res = await conn.exec('echo', Buffer.from('hello'));
+      assert.equal(res.code, 0);
+      assert.equal(res.stdout.toString(), 'echo:hello');
+      const bad = await conn.exec('fail');
+      assert.deepEqual([bad.code, bad.stderr], [3, 'boom']);
+      conn.close();
+      assert.deepEqual(prompts, [`alice@127.0.0.1:${srv.port}'s password: `]);
+      assert.match(await readFile(knownHostsFile, 'utf8'), new RegExp(`^\\[127\\.0\\.0\\.1\\]:${srv.port} SHA256:\\S+\\n$`));
+    } finally {
+      await srv.close();
+    }
+  });
+
+  test('uses ~/.ssh keys without prompting; non-interactive password auth is skipped', async () => {
+    const keyHome = join(home, 'withkey');
+    await mkdir(join(keyHome, '.ssh'), { recursive: true });
+    await writeFile(join(keyHome, '.ssh', 'id_ed25519'), userKey.private);
+    const srv = await startServer({ publicKey: Buffer.from(userKey.public), hostKey: hostKeyA });
+    try {
+      const conn = await SshConnection.connect({
+        target: { host: '127.0.0.1', port: srv.port, user: 'alice' },
+        env: { HOME: keyHome, SSH_AUTH_SOCK: '' },
+        knownHostsFile: join(home, 'kh2'),
+        interactive: false,
+        prompt: async () => assert.fail('must not prompt'),
+        signal: signal(),
+        logger,
+      });
+      conn.close();
+      assert.ok(srv.authAttempts.includes('publickey'));
+
+      await assert.rejects(
+        SshConnection.connect({
+          target: { host: '127.0.0.1', port: srv.port, user: 'alice' },
+          env: { HOME: join(home, 'nokeys'), SSH_AUTH_SOCK: '' },
+          knownHostsFile: join(home, 'kh2'),
+          interactive: false,
+          signal: signal(),
+          logger,
+        }),
+        /SSH authentication as alice@127\.0\.0\.1:\d+ failed/,
+      );
+    } finally {
+      await srv.close();
+    }
+  });
+
+  test('a changed host key is rejected until the pin is forgotten', async () => {
+    const knownHostsFile = join(home, 'kh3');
+    const opts = (port: number) => ({
+      target: { host: '127.0.0.1', port, user: 'alice' },
+      env: { HOME: join(home, 'nokeys'), SSH_AUTH_SOCK: '' },
+      knownHostsFile,
+      interactive: true,
+      prompt: async () => 'pw',
+      signal: signal(),
+      logger,
+    });
+    const a = await startServer({ password: 'pw', hostKey: hostKeyA });
+    const port = a.port;
+    (await SshConnection.connect(opts(port))).close();
+    await a.close();
+
+    const b = await new Promise<ServerHandle>((resolve) => {
+      const tryListen = async (): Promise<void> => {
+        // Reuse the same port so the pin applies.
+        const srv = new Server({ hostKeys: [hostKeyB] }, (c: Connection) => {
+          c.on('authentication', (ctx: AuthContext) => (ctx.method === 'password' ? ctx.accept() : ctx.reject(['password'])));
+          c.on('error', () => {});
+        });
+        srv.listen(port, '127.0.0.1', () =>
+          resolve({ port, authAttempts: [], close: () => new Promise((r) => srv.close(() => r())) }),
+        );
+      };
+      void tryListen();
+    });
+    try {
+      await assert.rejects(SshConnection.connect(opts(port)), /host key for \[127\.0\.0\.1\]:\d+ changed/);
+      await forgetHostKey(knownHostsFile, '127.0.0.1', port);
+      (await SshConnection.connect(opts(port))).close();
+    } finally {
+      await b.close();
+    }
+  });
+
+  test('stream delivers output and stops on abort', async () => {
+    const srv = await startServer({ password: 'pw', hostKey: hostKeyA });
+    try {
+      const conn = await SshConnection.connect({
+        target: { host: '127.0.0.1', port: srv.port, user: 'alice' },
+        env: { HOME: join(home, 'nokeys'), SSH_AUTH_SOCK: '' },
+        knownHostsFile: join(home, 'kh4'),
+        interactive: true,
+        prompt: async () => 'pw',
+        signal: signal(),
+        logger,
+      });
+      const ac = new AbortController();
+      const seen: string[] = [];
+      const code = await conn.stream(
+        'follow',
+        (d, w) => {
+          seen.push(`${w}:${d.toString()}`);
+          if (seen.filter((x) => x.includes('tick')).length >= 2) ac.abort();
+        },
+        ac.signal,
+      );
+      conn.close();
+      assert.equal(code, -1);
+      assert.ok(seen.includes('stdout:a\n'));
+      assert.ok(seen.includes('stderr:e\n'));
+    } finally {
+      await srv.close();
+    }
+  });
+
+  test('waitForSsh sees the banner', async () => {
+    const srv = await startServer({ password: 'x', hostKey: hostKeyA });
+    try {
+      await waitForSsh('127.0.0.1', srv.port, signal(), logger, 5000);
+    } finally {
+      await srv.close();
+    }
+  });
+});
diff --git a/packages/os-cloud-provider/test/sync.test.ts b/packages/os-cloud-provider/test/sync.test.ts
new file mode 100644
index 00000000..ad705c90
--- /dev/null
+++ b/packages/os-cloud-provider/test/sync.test.ts
@@ -0,0 +1,170 @@
+import { strict as assert } from 'node:assert';
+import { lstat, mkdir, mkdtemp, readFile, readlink, rm, symlink, utimes, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, test } from 'node:test';
+import { IgnoreRules, planSync, REMOTE, scanLocal, syncWorktree } from '../src/sync.ts';
+import { FakeShell } from './fake-shell.ts';
+
+const logger = { info() {}, warn() {}, error() {} };
+let base: string;
+let local: string;
+let remote: string;
+
+async function put(root: string, rel: string, content: string): Promise<void> {
+  await mkdir(join(root, rel, '..'), { recursive: true });
+  await writeFile(join(root, rel), content);
+}
+
+beforeEach(async () => {
+  base = await mkdtemp(join(tmpdir(), 'os-sync-'));
+  local = join(base, 'local');
+  remote = join(base, 'remote');
+  await put(local, '.gitignore', 'node_modules/\n*.log\ndist\n!keep.log\n');
+  await put(local, 'package.json', '{}');
+  await put(local, 'src/index.js', 'v1');
+  await put(local, 'src/.gitignore', 'secret.txt\n');
+  await put(local, 'src/secret.txt', 'nope');
+  await put(local, 'untracked.txt', 'not staged, still synced');
+  await put(local, 'debug.log', 'ignored');
+  await put(local, 'keep.log', 'unignored by negation');
+  await put(local, 'node_modules/x/index.js', 'local deps');
+  await put(local, 'dist/out.js', 'build');
+  await put(local, '.git/HEAD', 'ref: refs/heads/main');
+  await symlink('src/index.js', join(local, 'link.js'));
+});
+afterEach(async () => {
+  await rm(base, { recursive: true, force: true });
+});
+
+describe('IgnoreRules', () => {
+  test('scoped, nested, negation, ancestors, .git', () => {
+    const r = new IgnoreRules();
+    r.add('', 'node_modules/\n*.log\n!keep.log\n/build\n');
+    r.add('pkg', 'tmp/\n');
+    assert.equal(r.ignores('node_modules/a/b.js'), true);
+    assert.equal(r.ignores('pkg/node_modules/a.js'), true);
+    assert.equal(r.ignores('a/b.log'), true);
+    assert.equal(r.ignores('keep.log'), false);
+    assert.equal(r.ignores('build/x'), true);
+    assert.equal(r.ignores('pkg/build/x'), false);
+    assert.equal(r.ignores('pkg/tmp/x'), true);
+    assert.equal(r.ignores('tmp/x'), false);
+    assert.equal(r.ignores('.git/HEAD'), true);
+    assert.equal(r.ignores('src/.gitkeep'), false);
+  });
+});
+
+describe('scanLocal', () => {
+  test('honors .gitignore, skips .git, includes untracked files and symlinks', async () => {
+    const { files } = await scanLocal(local);
+    assert.deepEqual([...files.keys()].sort(), [
+      '.gitignore',
+      'keep.log',
+      'link.js',
+      'package.json',
+      'src/.gitignore',
+      'src/index.js',
+      'untracked.txt',
+    ]);
+    assert.equal(files.get('link.js')!.type, 'symlink');
+  });
+});
+
+describe('syncWorktree', () => {
+  test('first sync uploads everything, owned by mieweb, and restarts', async () => {
+    const shell = new FakeShell(remote);
+    const plan = await syncWorktree(local, shell, logger);
+    assert.equal(plan.upload.length, 7);
+    assert.equal(await readFile(join(remote, 'src/index.js'), 'utf8'), 'v1');
+    assert.equal(await readlink(join(remote, 'link.js')), 'src/index.js');
+    await assert.rejects(lstat(join(remote, 'src/secret.txt')));
+    await assert.rejects(lstat(join(remote, '.git')));
+    assert.equal(shell.owners.get('src/index.js'), 'mieweb:mieweb');
+    assert.equal(shell.owners.get('src'), 'mieweb:mieweb');
+    assert.equal(shell.commands.at(-1), REMOTE.restart);
+  });
+
+  test('second sync is incremental; deletes removed files; keeps remote ignored paths', async () => {
+    await syncWorktree(local, new FakeShell(remote), logger);
+    await put(remote, 'node_modules/installed/index.js', 'remote deps');
+    await put(remote, 'dist/built.js', 'remote build');
+
+    const same = await syncWorktree(local, new FakeShell(remote), logger);
+    assert.deepEqual(same, { upload: [], remove: [] });
+
+    await writeFile(join(local, 'src/index.js'), 'v2!');
+    const future = new Date(Date.now() + 5000);
+    await utimes(join(local, 'src/index.js'), future, future);
+    await rm(join(local, 'untracked.txt'));
+    await rm(join(local, 'src/.gitignore'));
+    const shell = new FakeShell(remote);
+    const plan = await syncWorktree(local, shell, logger);
+    assert.deepEqual(plan.upload.map((f) => f.path).sort(), ['src/index.js', 'src/secret.txt']);
+    assert.deepEqual(plan.remove, ['src/.gitignore', 'untracked.txt']);
+    assert.equal(await readFile(join(remote, 'src/index.js'), 'utf8'), 'v2!');
+    await assert.rejects(lstat(join(remote, 'untracked.txt')));
+    assert.equal(await readFile(join(remote, 'node_modules/installed/index.js'), 'utf8'), 'remote deps');
+    assert.equal(await readFile(join(remote, 'dist/built.js'), 'utf8'), 'remote build');
+  });
+
+  test('empty directories left by deletions are pruned', async () => {
+    await put(local, 'old/deep/file.txt', 'x');
+    await syncWorktree(local, new FakeShell(remote), logger);
+    await rm(join(local, 'old'), { recursive: true });
+    await syncWorktree(local, new FakeShell(remote), logger);
+    await assert.rejects(lstat(join(remote, 'old')));
+  });
+
+  test('restart output is streamed line by line', async () => {
+    const shell = new FakeShell(remote);
+    shell.restartScript = { chunks: [['Installing depend', 'stdout'], ['encies: npm ci\nadded 3 packages\n', 'stdout']], code: 0 };
+    const logs: string[] = [];
+    await syncWorktree(local, shell, { info: (m) => logs.push(m), warn() {}, error() {} });
+    assert.ok(logs.includes('  | Installing dependencies: npm ci'));
+    assert.ok(logs.includes('  | added 3 packages'));
+    assert.equal(logs.at(-1), 'App restarted and running');
+  });
+
+  test('a failed install/build fails the sync and shows recent logs', async () => {
+    const shell = new FakeShell(remote);
+    shell.restartScript = { chunks: [['npm ERR! missing script\n', 'stdout']], code: 1 };
+    shell.recentLogs = 'npm ERR! missing script\nProcess exited';
+    const errors: string[] = [];
+    await assert.rejects(
+      syncWorktree(local, shell, { info() {}, warn() {}, error: (m) => errors.push(m) }),
+      /Restarting the app failed \(exit 1\): dependency install or build failed/,
+    );
+    assert.match(errors[0]!, /Recent app\.service logs:\nnpm ERR! missing script/);
+  });
+
+  test('an app that crashes right after starting fails the sync', async () => {
+    const shell = new FakeShell(remote);
+    shell.restartScript = { chunks: [], code: 86 };
+    await assert.rejects(syncWorktree(local, shell, logger), /started but stopped within 5s/);
+  });
+
+  test('a failing remote command fails the sync with its stderr', async () => {
+    const shell = new FakeShell(remote);
+    shell.exec = async () => ({ code: 1, stdout: Buffer.alloc(0), stderr: 'sudo: a password is required' });
+    await assert.rejects(syncWorktree(local, shell, logger), /listing failed \(exit 1\): sudo: a password is required/);
+  });
+});
+
+test('planSync diff', () => {
+  const rules = new IgnoreRules();
+  rules.add('', 'node_modules/\n');
+  const localFiles = new Map([
+    ['a', { path: 'a', type: 'file' as const, size: 1, mtime: 10, mode: 0o644 }],
+    ['b', { path: 'b', type: 'file' as const, size: 2, mtime: 10, mode: 0o644 }],
+  ]);
+  const remoteFiles = new Map([
+    ['a', { size: 1, mtime: 10 }],
+    ['b', { size: 2, mtime: 9 }],
+    ['c', { size: 1, mtime: 1 }],
+    ['node_modules/x', { size: 1, mtime: 1 }],
+  ]);
+  const plan = planSync(localFiles, remoteFiles, rules);
+  assert.deepEqual(plan.upload.map((f) => f.path), ['b']);
+  assert.deepEqual(plan.remove, ['c']);
+});
diff --git a/packages/os-cloud-provider/tsconfig.build.json b/packages/os-cloud-provider/tsconfig.build.json
new file mode 100644
index 00000000..e58c0a6d
--- /dev/null
+++ b/packages/os-cloud-provider/tsconfig.build.json
@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": true,
+    "sourceMap": true,
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"]
+}
diff --git a/packages/os-cloud-provider/tsconfig.json b/packages/os-cloud-provider/tsconfig.json
new file mode 100644
index 00000000..115d8e36
--- /dev/null
+++ b/packages/os-cloud-provider/tsconfig.json
@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "types": ["node"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": false,
+    // Node runs the sources directly (native type stripping): erasable syntax
+    // only, type-only imports marked, `.ts` extensions on relative imports.
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true,
+    "allowImportingTsExtensions": true,
+    "rewriteRelativeImportExtensions": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src", "test"]
+}