open-managed-agents 0.1.0 → 0.1.2

package/README.md

@@ -12,17 +12,35 @@ files, and sandboxes live on your machines, under your policies.
 > self-hosted baseline. The orchestration/persistence layer (multi-agent
 > runtime, memory stores,
 > scheduled deployments, webhooks, outcomes) is deliberately deferred. See
-> **[PARITY.md](PARITY.md)** for the full domain-by-domain scorecard and the
-> active parity worklist, and **[ALPHA.md](ALPHA.md)** for the first-user
+> **[PARITY.md](https://github.com/oneryalcin/open-managed-agents/blob/main/PARITY.md)** for the full domain-by-domain scorecard and the
+> active parity worklist, and **[ALPHA.md](https://github.com/oneryalcin/open-managed-agents/blob/main/ALPHA.md)** for the first-user
 > alpha readiness plan.
 
 ## Quickstart
 
-Start with the canonical source-checkout guide:
+> **Public onboarding preview:** the one-command path is shipped, but its
+> three-minute warm-path target has not yet completed the real-user timing
+> study. Docker image downloads are explicitly outside that warm-path target.
 
-**[Getting Started](docs/getting-started.md)**
+Prerequisites: Node.js 22.19 or newer and a running Docker-compatible daemon.
+Then run:
 
-The alpha path is:
+```bash
+npx --yes open-managed-agents@latest
+```
+
+The guided terminal checks local prerequisites, asks which model provider to
+use, reads the API key through a masked prompt, starts an authenticated
+loopback appliance, creates or reuses a starter agent/environment/session, and
+opens that session in the console. The appliance stays attached to the command;
+press Ctrl-C to stop it. State and provider credentials persist under `~/.oma`.
+
+If the pinned sandbox image is not cached, OMA names the image and asks before
+pulling it. Rerunning the same command while its onboarding-owned appliance is
+alive reopens the existing starter session rather than creating duplicates.
+
+For the full source-checkout diagnostics and deterministic smoke tests, use
+the **[Getting Started guide](https://github.com/oneryalcin/open-managed-agents/blob/main/docs/getting-started.md)**:
 
 ```bash
 git clone https://github.com/oneryalcin/open-managed-agents.git
@@ -45,7 +63,8 @@ events, and cleanup.
 Docker-local egress boundary: npm, uv/PyPI, and GitHub must work under the
 reviewed preset while an unrelated HTTPS destination remains denied.
 
-`oma up` starts the durable local appliance in the foreground, stores data
+In the advanced source-checkout flow, `oma up` starts the durable local appliance
+in the foreground, stores data
 under `~/.oma`, and prints the console URL plus the first workspace API key
 once. Docker deployments have the pinned approved-HTTPS sidecar capability,
 but every environment remains offline unless its immutable allowlist selects a
@@ -57,6 +76,12 @@ mint another while the server is running:
 oma keys mint
 ```
 
+When using the public package without a global install, the equivalent is:
+
+```bash
+npx --yes open-managed-agents@latest keys mint
+```
+
 Interactive, air-gap-safe OpenAPI documentation is served at `/docs/`, with
 the same schema available to tools at `/openapi.json`. The documentation lists
 only routes OMA currently ships; workspace and admin credentials entered in the
@@ -69,7 +94,7 @@ import anthropic
 
 client = anthropic.Anthropic(
     base_url="http://127.0.0.1:4180",
-    api_key="oma_...",  # printed on first boot
+    api_key="oma_...",  # returned by `oma keys mint`
     default_headers={"anthropic-beta": "managed-agents-2026-04-01"},
 )
 

package/bin/oma.mjs

@@ -20,7 +20,9 @@ const { resolveOmaUpEgressEnvironment } = await import(
 
 checkNode();
 
-const command = args[0];
+// `npx open-managed-agents` is the public one-command path. Keep an installed
+// bare `oma` invocation as help so existing CLI discovery remains stable.
+const command = args[0] ?? (process.env.npm_command === "exec" ? "onboard" : undefined);
 if (command === undefined || command === "help" || command === "--help" || command === "-h") {
   if (command === "help" && args.length > 1) {
     printCommandHelp(args.slice(1));
@@ -33,7 +35,7 @@ if ((command === "version" && args.length === 1) || command === "--version" || c
   console.log(`oma ${packageJson.version}`);
   process.exit(0);
 }
-const commandArgs = args.slice(1);
+const commandArgs = command === "onboard" && args.length === 0 ? [] : args.slice(1);
 const helpIndex = commandArgs.findIndex((arg) => arg === "--help" || arg === "-h");
 if (helpIndex !== -1) {
   if (helpIndex !== commandArgs.length - 1) fail(`Help must be the last argument. Run \`oma help ${[command, ...commandArgs.slice(0, helpIndex)].join(" ")}\`.`);
@@ -57,6 +59,8 @@ if (command === "up") {
   await runModels(args.slice(1));
 } else if (command === "auth") {
   await runAuth(args.slice(1));
+} else if (command === "onboard") {
+  await runOnboard(commandArgs);
 } else if (command === "doctor") {
   await runDoctor(args.slice(1));
 } else if (command === "down" || command === "logs" || command === "status") {
@@ -77,6 +81,21 @@ async function runDoctor(commandArgs) {
   );
 }
 
+async function runOnboard(commandArgs) {
+  const childEnv = commandArgs.includes("--json")
+    ? { ...process.env, OMA_LOG_LEVEL: "error" }
+    : process.env;
+  await runChild(
+    process.execPath,
+    [
+      ...runtimeNodeFlags(),
+      runtimeFile("scripts", "oma-onboard"),
+      ...commandArgs,
+    ],
+    childEnv,
+  );
+}
+
 async function runUp(commandArgs) {
   let sandbox = "docker-local";
   for (let index = 0; index < commandArgs.length; index += 1) {
@@ -415,6 +434,7 @@ Usage:
   oma auth set <provider> [--stdin]
   oma auth status [provider]
   oma auth remove <provider>
+  oma onboard [--provider name] [--stdin] [--sandbox docker|microsandbox] [--pull] [--json]
   oma doctor [--sandbox docker|microsandbox] [--json]
   oma admin init
   oma admin status
@@ -429,6 +449,7 @@ Commands:
   providers   Inspect enabled Pi model providers and credential readiness.
   models      List or validate enabled Pi models.
   auth        Store, remove, or inspect model provider API-key credentials.
+  onboard     Prepare credentials, start or resume local OMA, and open a starter console session.
   doctor      Run secret-safe, read-only local readiness diagnostics.
   admin       Initialize or inspect local appliance admin mode.
   version     Print the installed OMA version.
@@ -478,6 +499,7 @@ function commandHelpFor(key) {
   "auth set": ["Usage: oma auth set <provider> [--stdin]", "Store a provider key without accepting it as a command-line argument.", "Example: printf '%s\\n' \"$OPENAI_API_KEY\" | oma auth set openai --stdin"],
   "auth status": ["Usage: oma auth status [provider]", "Show credential readiness without secret values.", "Example: oma auth status openai"],
   "auth remove": ["Usage: oma auth remove <provider>", "Remove a stored provider credential idempotently.", "Example: oma auth remove openai"],
+  onboard: ["Usage: oma onboard [--provider name] [--stdin] [--sandbox docker|microsandbox] [--pull] [--json]", "Verify warm-path prerequisites, select or store a provider credential, start or resume the attached local appliance, and open its starter console session. --pull explicitly permits a missing Docker sandbox image to be downloaded.", "Examples: oma onboard; oma onboard --pull; printf '%s\\n' \"$ANTHROPIC_API_KEY\" | oma onboard --provider anthropic --stdin"],
   admin: ["Usage: oma admin <init|status>", "Initialize or inspect appliance-wide admin mode.", "Examples: oma admin init; oma admin status"],
   "admin init": ["Usage: oma admin init [--file path]", "Create a new owner-only admin key file; existing files are never overwritten.", "Example: oma admin init"],
   "admin status": ["Usage: oma admin status", "Inspect admin configuration without printing the key.", "Example: oma admin status"],

package/dist/scripts/oma-onboard.js

@@ -0,0 +1,544 @@
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { stdin as input } from "node:process";
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { inspectOma, } from "./oma-doctor.js";
+import { runModelsCli } from "./oma-models.js";
+import { DEFAULT_OMA_SANDBOX_IMAGE } from "../src/control-plane/sessions/pi/sandbox/image.js";
+import { resolveOmaUpEgressEnvironment } from "../src/control-plane/egress/image.js";
+import { ConsoleBootstrapService } from "../src/control-plane/console/bootstrap.js";
+import { startAppliance } from "../src/main.js";
+import { ensureStarterResources } from "./oma-onboarding-resources.js";
+export const ONBOARD_CANCELLED = Symbol("oma-onboard-cancelled");
+const PROVIDER_LABELS = {
+    anthropic: "Anthropic",
+    openai: "OpenAI",
+    openrouter: "OpenRouter",
+};
+export async function runOnboard(argv, runtime) {
+    const wantsJson = argv.includes("--json");
+    let options;
+    try {
+        options = parseOnboardArgs(argv);
+    }
+    catch (error) {
+        emitFailure(runtime, wantsJson, error instanceof Error ? error.message : String(error));
+        return { code: 2, credential: "not_reached" };
+    }
+    if (!options.json)
+        runtime.terminal.intro(pc.bgCyan(pc.black(" Open Managed Agents ")));
+    if (options.provider === undefined && !options.stdin) {
+        try {
+            const resumed = await runtime.resume({ json: options.json });
+            if (resumed !== undefined) {
+                emitResumed(runtime, options.json, resumed.sessionId);
+                return { code: 0, credential: "reused", sessionId: resumed.sessionId };
+            }
+        }
+        catch (error) {
+            emitFailure(runtime, options.json, safeMessage(error));
+            return { code: 1, credential: "not_reached" };
+        }
+    }
+    if (!runtime.interactive && !options.stdin && options.provider === undefined) {
+        emitFailure(runtime, options.json, "Non-interactive onboarding requires --provider and either --stdin or an existing stored credential.");
+        return { code: 2, credential: "not_reached" };
+    }
+    if (options.stdin && options.provider === undefined) {
+        emitFailure(runtime, options.json, "--stdin requires --provider so OMA knows which credential to store.");
+        return { code: 2, credential: "not_reached" };
+    }
+    let report = await runtime.inspect({ sandbox: options.sandbox });
+    const imageMissing = options.sandbox === "docker-local"
+        && report.checks.find((check) => check.id === "sandbox.image")?.status !== "pass";
+    const failures = onboardingPreflightFailures(report, options.sandbox, { allowMissingImage: imageMissing });
+    if (failures.length > 0) {
+        const detail = failures.join("\n");
+        emitFailure(runtime, options.json, detail);
+        return { code: 1, credential: "not_reached", report };
+    }
+    if (imageMissing) {
+        let approved = options.pull;
+        if (!approved && runtime.interactive && !options.json) {
+            const answer = await runtime.terminal.confirm({
+                message: `The cached OMA image is missing. Pull it now? This download is outside the three-minute warm-path target.`,
+                initialValue: true,
+            });
+            if (answer === ONBOARD_CANCELLED)
+                return cancelled(runtime, options.json, report);
+            approved = answer;
+        }
+        if (!approved) {
+            emitFailure(runtime, options.json, `Pull the cached prerequisite image, then retry: docker pull ${DEFAULT_OMA_SANDBOX_IMAGE}`);
+            return { code: 1, credential: "not_reached", report };
+        }
+        if (!options.json)
+            runtime.terminal.step(`Pulling ${DEFAULT_OMA_SANDBOX_IMAGE}`);
+        try {
+            await runtime.pullImage(DEFAULT_OMA_SANDBOX_IMAGE);
+            report = await runtime.inspect({ sandbox: options.sandbox });
+        }
+        catch (error) {
+            emitFailure(runtime, options.json, safeMessage(error));
+            return { code: 1, credential: "not_reached", report };
+        }
+        const afterPull = onboardingPreflightFailures(report, options.sandbox);
+        if (afterPull.length > 0) {
+            emitFailure(runtime, options.json, afterPull.join("\n"));
+            return { code: 1, credential: "not_reached", report };
+        }
+    }
+    if (!options.json)
+        runtime.terminal.step("Docker and the cached OMA sandbox image are ready.");
+    let provider = options.provider;
+    let providerState;
+    try {
+        providerState = await runtime.providerStatus(provider);
+    }
+    catch (error) {
+        emitFailure(runtime, options.json, safeMessage(error));
+        return { code: 2, credential: "not_reached", report };
+    }
+    if (providerState.providers.length === 0) {
+        emitFailure(runtime, options.json, "No enabled model providers are available for onboarding.");
+        return { code: 2, credential: "not_reached", report };
+    }
+    if (provider === undefined) {
+        if (!runtime.interactive) {
+            emitFailure(runtime, options.json, "Non-interactive onboarding requires --provider.");
+            return { code: 2, credential: "not_reached", report };
+        }
+        const selected = await runtime.terminal.select({
+            message: "Choose a model provider",
+            options: providerState.providers.map((value) => ({
+                value,
+                label: PROVIDER_LABELS[value] ?? value,
+            })),
+        });
+        if (selected === ONBOARD_CANCELLED)
+            return cancelled(runtime, options.json, report);
+        provider = selected;
+        try {
+            providerState = await runtime.providerStatus(provider);
+        }
+        catch (error) {
+            emitFailure(runtime, options.json, safeMessage(error));
+            return { code: 2, credential: "not_reached", report };
+        }
+    }
+    if (!providerState.providers.includes(provider)) {
+        emitFailure(runtime, options.json, `Model provider ${JSON.stringify(provider)} is not enabled. Enabled providers: ${providerState.providers.join(", ")}.`);
+        return { code: 2, credential: "not_reached", report };
+    }
+    if (providerState.stored) {
+        if (!runtime.interactive || options.json) {
+            return finishOnboarding(runtime, options, provider, "reused", report);
+        }
+        const reuse = await runtime.terminal.confirm({
+            message: `Use the saved ${PROVIDER_LABELS[provider] ?? provider} credential?`,
+            initialValue: true,
+        });
+        if (reuse === ONBOARD_CANCELLED)
+            return cancelled(runtime, options.json, report);
+        if (reuse) {
+            return finishOnboarding(runtime, options, provider, "reused", report);
+        }
+    }
+    let key;
+    if (options.stdin) {
+        try {
+            key = await runtime.readStdin();
+        }
+        catch (error) {
+            emitFailure(runtime, options.json, safeMessage(error));
+            return { code: 2, credential: "not_reached", report };
+        }
+    }
+    else if (runtime.interactive) {
+        key = await runtime.terminal.password({
+            message: `Paste API key for ${PROVIDER_LABELS[provider] ?? provider}`,
+            validate(value) {
+                return value.trim() === "" ? "API key must not be empty." : undefined;
+            },
+        });
+    }
+    else {
+        emitFailure(runtime, options.json, "Non-interactive onboarding requires --stdin when no stored credential exists.");
+        return { code: 2, credential: "not_reached", report };
+    }
+    if (key === ONBOARD_CANCELLED)
+        return cancelled(runtime, options.json, report);
+    if (key.trim() === "") {
+        emitFailure(runtime, options.json, "API key must not be empty.");
+        return { code: 2, credential: "not_reached", report };
+    }
+    try {
+        await runtime.storeCredential(provider, key.trim());
+    }
+    catch (error) {
+        emitFailure(runtime, options.json, safeMessage(error));
+        return { code: 1, credential: "not_reached", report };
+    }
+    return finishOnboarding(runtime, options, provider, "stored", report);
+}
+async function finishOnboarding(runtime, options, provider, credential, report) {
+    try {
+        let readyEmitted = false;
+        const launched = await runtime.launch(provider, options.sandbox, {
+            json: options.json,
+            onReady(sessionId) {
+                readyEmitted = true;
+                emitSuccess(runtime, options.json, provider, credential, sessionId);
+            },
+        });
+        if (!readyEmitted)
+            emitSuccess(runtime, options.json, provider, credential, launched.sessionId);
+        return { code: 0, provider, credential, report, sessionId: launched.sessionId };
+    }
+    catch (error) {
+        emitFailure(runtime, options.json, safeMessage(error));
+        return { code: 1, provider, credential, report };
+    }
+}
+export function createProcessOnboardRuntime() {
+    return {
+        env: process.env,
+        interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+        terminal: createClackTerminal(),
+        inspect: (options) => inspectOma(options, { env: process.env }),
+        async providerStatus(provider) {
+            const status = await runModelsCli(["providers-status"], { env: process.env });
+            if (status.code !== 0)
+                throw new Error(status.stderr.trim());
+            const providers = parseProviderStatus(status.stdout);
+            if (provider === undefined)
+                return { providers, stored: undefined };
+            const auth = await runModelsCli(["auth-status", provider], { env: process.env });
+            if (auth.code !== 0)
+                throw new Error(auth.stderr.trim());
+            return { providers, stored: parseStoredCredential(auth.stdout, provider) };
+        },
+        async storeCredential(provider, key) {
+            const result = await runModelsCli(["auth-set", provider], {
+                env: process.env,
+                promptSecret: async () => key,
+            });
+            if (result.code !== 0)
+                throw new Error(result.stderr.trim());
+        },
+        readStdin: readOneSecretFromStdin,
+        async pullImage(image) {
+            const result = spawnSync("docker", ["pull", image], { stdio: "inherit" });
+            if (result.status !== 0)
+                throw new Error(`docker pull failed for ${image}`);
+        },
+        resume: (options) => tryResumeLocalOnboarding(process.env, createClackTerminal(), options.json),
+        launch: (provider, sandbox, options) => launchLocalOnboarding(provider, sandbox, process.env, createClackTerminal(), options),
+    };
+}
+export async function launchLocalOnboarding(provider, sandbox, env, terminal, options) {
+    const bootstrap = new ConsoleBootstrapService();
+    const controlToken = `oct_${randomBytes(32).toString("base64url")}`;
+    const runtimeEnv = resolveOmaUpEgressEnvironment(env, sandbox);
+    const applianceEnv = {
+        ...runtimeEnv,
+        OMA_AUTH_MODE: "api-key",
+        OMA_HOST: "127.0.0.1",
+        OMA_PORT: runtimeEnv.OMA_PORT ?? "0",
+        OMA_TLS_TERMINATED: "0",
+        OMA_SANDBOX_PROVIDER: sandbox,
+        ...(sandbox === "docker-local"
+            ? { OMA_ALLOW_DOCKER_LOCAL: "true" }
+            : { OMA_ALLOW_MICROSANDBOX_LOCAL: "true" }),
+    };
+    if (!options.json)
+        terminal.step("Starting local OMA");
+    const appliance = await startAppliance(applianceEnv, {
+        log: () => undefined,
+        onboarding: { bootstrap, controlToken },
+    });
+    let resumeStateWritten = false;
+    try {
+        if (appliance.onboarding === undefined)
+            throw new Error("Local onboarding requires workspace authentication");
+        if (!options.json)
+            terminal.step("Preparing your first session");
+        const starter = await ensureStarterResources({
+            baseUrl: appliance.baseUrl,
+            workspaceKey: appliance.onboarding.workspaceKey,
+            provider,
+        });
+        if (!options.json)
+            for (const warning of starter.warnings)
+                terminal.warn(warning);
+        writeResumeState(env, {
+            schema_version: 1,
+            pid: process.pid,
+            base_url: appliance.baseUrl,
+            session_id: starter.sessionId,
+            control_token: controlToken,
+        });
+        resumeStateWritten = true;
+        const url = `${appliance.baseUrl}/console/#bootstrap=${encodeURIComponent(appliance.onboarding.bootstrapNonce)}&session=${encodeURIComponent(starter.sessionId)}`;
+        const opened = openBrowser(url);
+        if (!opened && !options.json)
+            terminal.warn(`Browser launch failed. Open this local URL manually: ${url}`);
+        options.onReady(starter.sessionId);
+        if (!options.json)
+            terminal.outro(`Ready — ${opened ? "console opened" : "console available"} at ${appliance.baseUrl}/console/\nPress Ctrl-C to stop OMA.`);
+        await waitForShutdownSignal();
+        return { sessionId: starter.sessionId };
+    }
+    finally {
+        if (resumeStateWritten)
+            removeResumeState(env, controlToken);
+        await appliance.close();
+    }
+}
+export async function tryResumeLocalOnboarding(env, terminal, json, dependencies = {}) {
+    const fetchImpl = dependencies.fetch ?? fetch;
+    const openBrowserImpl = dependencies.openBrowser ?? openBrowser;
+    const state = readResumeState(env);
+    if (state === undefined)
+        return undefined;
+    const health = await fetchImpl(new URL("/health", state.base_url), {
+        signal: AbortSignal.timeout(1_000),
+    }).catch(() => undefined);
+    if (health?.ok !== true) {
+        removeResumeState(env, state.control_token);
+        return undefined;
+    }
+    const renewed = await fetchImpl(new URL("/console/auth/bootstrap/renew", state.base_url), {
+        method: "POST",
+        headers: { "x-oma-onboarding-token": state.control_token },
+        signal: AbortSignal.timeout(1_000),
+    }).catch(() => undefined);
+    if (renewed?.ok !== true) {
+        removeResumeState(env, state.control_token);
+        return undefined;
+    }
+    const body = await renewed.json();
+    if (typeof body.nonce !== "string" || !body.nonce.startsWith("ocb_")) {
+        throw new Error("The running OMA appliance returned an invalid onboarding resume response");
+    }
+    const url = `${state.base_url}/console/#bootstrap=${encodeURIComponent(body.nonce)}&session=${encodeURIComponent(state.session_id)}`;
+    const opened = openBrowserImpl(url);
+    if (!opened && !json)
+        terminal.warn(`Browser launch failed. Open this local URL manually: ${url}`);
+    return { sessionId: state.session_id };
+}
+function writeResumeState(env, state) {
+    const path = resumeStatePath(env);
+    const directory = dirname(path);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const directoryStat = lstatSync(directory);
+    if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink()) {
+        throw new Error(`OMA onboarding state directory is unsafe: ${directory}`);
+    }
+    const temporary = `${path}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+    try {
+        writeFileSync(temporary, `${JSON.stringify(state)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+        renameSync(temporary, path);
+        chmodSync(path, 0o600);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+function readResumeState(env) {
+    const path = resumeStatePath(env);
+    if (!existsSync(path))
+        return undefined;
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0) {
+        throw new Error(`OMA onboarding resume state is unsafe: ${path} must be a private regular file`);
+    }
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new Error(`OMA onboarding resume state is invalid: ${path}`);
+    }
+    if (value.schema_version !== 1
+        || typeof value.pid !== "number"
+        || typeof value.base_url !== "string"
+        || typeof value.session_id !== "string"
+        || typeof value.control_token !== "string") {
+        throw new Error(`OMA onboarding resume state is invalid: ${path}`);
+    }
+    const url = new URL(value.base_url);
+    if (url.protocol !== "http:" || !isLoopbackHostname(url.hostname) || url.username || url.password) {
+        throw new Error(`OMA onboarding resume state has an unsafe appliance URL: ${value.base_url}`);
+    }
+    return value;
+}
+function removeResumeState(env, expectedControlToken) {
+    const path = resumeStatePath(env);
+    if (!existsSync(path))
+        return;
+    try {
+        const current = readResumeState(env);
+        if (current?.control_token === expectedControlToken)
+            rmSync(path, { force: true });
+    }
+    catch {
+        // Never delete a state file that failed validation or may belong to a
+        // newer onboarding process.
+    }
+}
+function resumeStatePath(env) {
+    return join(env.OMA_HOME?.trim() || join(homedir(), ".oma"), "onboarding-resume.json");
+}
+function isLoopbackHostname(hostname) {
+    return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "[::1]" || hostname === "::1";
+}
+function openBrowser(url) {
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    return spawnSync(command, args, { stdio: "ignore" }).status === 0;
+}
+function waitForShutdownSignal() {
+    return new Promise((resolve) => {
+        const done = () => {
+            process.off("SIGINT", done);
+            process.off("SIGTERM", done);
+            resolve();
+        };
+        process.once("SIGINT", done);
+        process.once("SIGTERM", done);
+    });
+}
+function createClackTerminal() {
+    return {
+        intro: p.intro,
+        step: (message) => p.log.success(message),
+        warn: (message) => p.log.warn(message),
+        error: (message) => p.log.error(message),
+        outro: p.outro,
+        cancel: p.cancel,
+        async select(options) {
+            const selected = await p.select(options);
+            return p.isCancel(selected) ? ONBOARD_CANCELLED : selected;
+        },
+        async confirm(options) {
+            const confirmed = await p.confirm(options);
+            return p.isCancel(confirmed) ? ONBOARD_CANCELLED : confirmed;
+        },
+        async password(options) {
+            const key = await p.password({
+                ...options,
+                validate: (value) => options.validate(value ?? ""),
+            });
+            return p.isCancel(key) ? ONBOARD_CANCELLED : key;
+        },
+    };
+}
+function parseOnboardArgs(argv) {
+    const options = { stdin: false, json: false, pull: false, sandbox: "docker-local" };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--provider") {
+            const provider = argv[++index];
+            if (provider === undefined || provider.startsWith("-"))
+                throw new Error("--provider requires a provider name");
+            options.provider = provider;
+        }
+        else if (arg === "--stdin") {
+            options.stdin = true;
+        }
+        else if (arg === "--json") {
+            options.json = true;
+        }
+        else if (arg === "--pull") {
+            options.pull = true;
+        }
+        else if (arg === "--sandbox") {
+            const sandbox = argv[++index];
+            if (sandbox === "docker" || sandbox === "docker-local")
+                options.sandbox = "docker-local";
+            else if (sandbox === "microsandbox" || sandbox === "microsandbox-local")
+                options.sandbox = "microsandbox-local";
+            else
+                throw new Error("--sandbox requires docker or microsandbox");
+        }
+        else {
+            throw new Error(`Unknown option for oma onboard: ${arg}`);
+        }
+    }
+    return options;
+}
+function onboardingPreflightFailures(report, sandbox, options = {}) {
+    const required = ["node.version", "models.catalog", "sandbox.runtime", "server.port"];
+    if (sandbox === "docker-local" && !options.allowMissingImage)
+        required.push("sandbox.image");
+    const failures = report.checks
+        .filter((check) => required.includes(check.id) && check.status !== "pass")
+        .map((check) => check.summary);
+    if (sandbox === "docker-local" && !options.allowMissingImage && report.checks.find((check) => check.id === "sandbox.image")?.status !== "pass") {
+        failures.push(`Pull the cached prerequisite image, then retry: docker pull ${DEFAULT_OMA_SANDBOX_IMAGE}`);
+    }
+    return [...new Set(failures)];
+}
+function parseProviderStatus(output) {
+    const rows = output.trim().split("\n").slice(1).filter(Boolean);
+    return rows.map((row) => row.split("\t", 1)[0]).filter(Boolean);
+}
+function parseStoredCredential(output, provider) {
+    const row = output.trim().split("\n").slice(1).find((line) => line.startsWith(`${provider}\t`));
+    if (row === undefined)
+        throw new Error(`Provider ${provider} was not returned by auth status`);
+    return row.split("\t")[1] === "true";
+}
+async function readOneSecretFromStdin() {
+    let value = "";
+    input.setEncoding("utf8");
+    for await (const chunk of input)
+        value += chunk;
+    value = value.replace(/\r?\n$/, "");
+    if (value.includes("\n") || value.includes("\r"))
+        throw new Error("--stdin accepts exactly one API key value");
+    return value;
+}
+function cancelled(runtime, json, report) {
+    if (json)
+        console.log(JSON.stringify({ schema_version: 1, status: "cancelled" }));
+    else
+        runtime.terminal.cancel("Onboarding cancelled before changing OMA credentials.");
+    return { code: 130, credential: "not_reached", report };
+}
+function emitFailure(runtime, json, message) {
+    if (json)
+        console.log(JSON.stringify({ schema_version: 1, status: "failed", error: message }));
+    else
+        runtime.terminal.error(message);
+}
+function emitSuccess(runtime, json, provider, credential, sessionId) {
+    if (json) {
+        console.log(JSON.stringify({ schema_version: 1, status: "ready", provider, credential, session_id: sessionId }));
+        return;
+    }
+    const verb = credential === "stored" ? "stored securely" : "already stored";
+    runtime.terminal.step(`Credential ${verb}.`);
+}
+function emitResumed(runtime, json, sessionId) {
+    if (json) {
+        console.log(JSON.stringify({ schema_version: 1, status: "ready", resumed: true, session_id: sessionId }));
+    }
+    else {
+        runtime.terminal.outro("Existing local OMA session reopened.");
+    }
+}
+function safeMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function main() {
+    const result = await runOnboard(process.argv.slice(2), createProcessOnboardRuntime());
+    process.exitCode = result.code;
+}
+if (import.meta.main)
+    void main();

package/dist/scripts/oma-onboarding-resources.js

@@ -0,0 +1,131 @@
+import { createHash } from "node:crypto";
+import { MANAGED_AGENTS_BETA } from "../src/control-plane/api-constants.js";
+const MARKER = "oma.onboarding";
+const MARKER_VERSION = "starter-v1";
+export async function ensureStarterResources(input) {
+    const request = createApiRequest(input.baseUrl, input.workspaceKey, input.fetch ?? fetch);
+    const warnings = [];
+    const created = [];
+    const models = await listAll(request, `/v1/model-catalog?available=true&provider=${encodeURIComponent(input.provider)}`);
+    const model = models.find((item) => item.default) ?? models[0];
+    if (model === undefined)
+        throw new Error(`No credential-ready model is available for provider ${input.provider}`);
+    const agentRows = await listAll(request, "/v1/agents?include_archived=true");
+    const markedAgents = agentRows.filter((item) => hasMarker(item, "agent"));
+    let agent = markedAgents.find((item) => item.archived_at === null && item.model.provider === model.provider && item.model.id === model.id);
+    if (agent === undefined) {
+        if (markedAgents.length > 0)
+            warnings.push("The previous starter agent was archived or used a different model; a compatible starter agent was created.");
+        agent = await request("/v1/agents", {
+            method: "POST",
+            body: {
+                name: "OMA Starter",
+                model: { provider: model.provider, id: model.id },
+                description: "Local starter agent created by oma onboard.",
+                system: "You are the local Open Managed Agents starter. Help the operator explore this workspace clearly and safely.",
+                tools: [], skills: [], mcp_servers: [],
+                metadata: marker("agent"),
+            },
+        });
+        created.push("agent");
+    }
+    const environmentRows = await listAll(request, "/v1/environments?include_archived=true");
+    const markedEnvironments = environmentRows.filter((item) => hasMarker(item, "environment"));
+    let environment = markedEnvironments.find((item) => item.archived_at === null && isOffline(item.config));
+    if (environment === undefined) {
+        if (markedEnvironments.length > 0)
+            warnings.push("The previous starter environment was archived or no longer offline; a new offline environment was created.");
+        environment = await request("/v1/environments", {
+            method: "POST",
+            body: {
+                name: "OMA Starter (offline)",
+                config: { type: "cloud", networking: { type: "limited", allowed_hosts: [] } },
+                metadata: marker("environment"),
+            },
+        });
+        created.push("environment");
+    }
+    const sessionRows = await listAll(request, "/v1/sessions?include_archived=true");
+    const markedSessions = sessionRows.filter((item) => hasMarker(item, "session"));
+    let session = markedSessions.find((item) => item.archived_at === null && item.agent.id === agent.id && item.environment_id === environment.id);
+    if (session === undefined) {
+        if (markedSessions.length > 0)
+            warnings.push("The previous starter session was archived or referenced older starter resources; a new session was created.");
+        session = await request("/v1/sessions", {
+            method: "POST",
+            headers: { "idempotency-key": idempotencyKey(agent.id, environment.id) },
+            body: {
+                agent: agent.id,
+                environment_id: environment.id,
+                title: "Your first OMA session",
+                metadata: marker("session"),
+            },
+        });
+        created.push("session");
+    }
+    return {
+        agentId: agent.id,
+        environmentId: environment.id,
+        sessionId: session.id,
+        model: { provider: model.provider, id: model.id },
+        created,
+        warnings,
+    };
+}
+function marker(resource) {
+    return { [MARKER]: MARKER_VERSION, "oma.onboarding.resource": resource };
+}
+function hasMarker(resource, kind) {
+    return resource.metadata?.[MARKER] === MARKER_VERSION && resource.metadata["oma.onboarding.resource"] === kind;
+}
+function isOffline(config) {
+    const networking = config.networking;
+    return networking?.type === "limited" && Array.isArray(networking.allowed_hosts) && networking.allowed_hosts.length === 0;
+}
+function idempotencyKey(agentId, environmentId) {
+    return `oma-onboard-${createHash("sha256").update(`${MARKER_VERSION}:${agentId}:${environmentId}`).digest("hex").slice(0, 32)}`;
+}
+function createApiRequest(baseUrl, workspaceKey, fetchImpl) {
+    return async function request(path, options = {}) {
+        const response = await fetchImpl(new URL(path, baseUrl), {
+            method: options.method ?? "GET",
+            headers: {
+                accept: "application/json",
+                "anthropic-beta": MANAGED_AGENTS_BETA,
+                "x-api-key": workspaceKey,
+                ...(options.body === undefined ? {} : { "content-type": "application/json" }),
+                ...options.headers,
+            },
+            ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+        });
+        const body = await response.json().catch(() => undefined);
+        if (!response.ok) {
+            const message = typeof body === "object" && body !== null && "error" in body
+                ? body.error?.message
+                : undefined;
+            throw new Error(message ?? `OMA API ${options.method ?? "GET"} ${path} failed with HTTP ${response.status}`);
+        }
+        return body;
+    };
+}
+async function listAll(request, initialPath) {
+    const data = [];
+    let path = addLimit(initialPath);
+    for (let pageCount = 0; path !== undefined && pageCount < 100; pageCount += 1) {
+        const page = await request(path);
+        data.push(...page.data);
+        path = page.has_more && page.next_page ? addPage(initialPath, page.next_page) : undefined;
+    }
+    return data;
+}
+function addLimit(path) {
+    const url = new URL(path, "http://oma.local");
+    url.searchParams.set("limit", "100");
+    return `${url.pathname}${url.search}`;
+}
+function addPage(path, page) {
+    const url = new URL(path, "http://oma.local");
+    url.searchParams.set("limit", "100");
+    url.searchParams.set("page", page);
+    return `${url.pathname}${url.search}`;
+}

package/dist/src/control-plane/app.js

@@ -274,6 +274,32 @@ function registerConsoleSessionRoutes(app, services) {
         c.header("cache-control", "no-store");
         return c.json({ workspace: consoleWorkspace(session.workspaceId, consoleAuth.service) });
     });
+    if (consoleAuth.bootstrap !== undefined) {
+        app.post("/console/auth/bootstrap/renew", async (c) => {
+            const controlToken = c.req.header("x-oma-onboarding-token");
+            if (controlToken === undefined)
+                return consoleAuthenticationFailed(c);
+            const nonce = consoleAuth.bootstrap.issueForControlToken(controlToken);
+            if (nonce === undefined)
+                return consoleAuthenticationFailed(c);
+            c.header("cache-control", "no-store");
+            return c.json({ nonce });
+        });
+        app.post("/console/auth/bootstrap", async (c) => {
+            if (!sameOriginForCookieWrite(c))
+                return c.text("Forbidden\n", 403);
+            const nonce = stringField(await parseJsonBody(c.req), "nonce");
+            const workspaceKey = consoleAuth.bootstrap.consume(nonce);
+            if (workspaceKey === undefined)
+                return consoleAuthenticationFailed(c);
+            const session = consoleAuth.service.createWorkspaceSession(workspaceKey);
+            if (session === undefined)
+                return consoleAuthenticationFailed(c);
+            setConsoleCookie(c, CONSOLE_WORKSPACE_COOKIE, session.token, consoleAuth.secureCookies, 30 * 24 * 60 * 60);
+            c.header("cache-control", "no-store");
+            return c.json({ workspace: consoleWorkspace(session.workspaceId, consoleAuth.service) });
+        });
+    }
     app.post("/console/auth/admin", async (c) => {
         if (!sameOriginForCookieWrite(c) || services.admin === undefined)
             return c.text("Not found\n", 404);
@@ -359,6 +385,12 @@ export function createDeploymentControlPlaneApp(env = process.env, opts = {}) {
 // tests that boot twice against one OMA_HOME) can close them and release the
 // .oma.lock instead of leaking them until process exit.
 export function createDeploymentControlPlane(env = process.env, opts = {}, internal = {}) {
+    if (opts.consoleBootstrap !== undefined && !isLoopbackHost(env.OMA_HOST)) {
+        throw new Error("Console bootstrap is available only on a loopback appliance bind");
+    }
+    if (opts.consoleBootstrap !== undefined && env.OMA_TLS_TERMINATED === "1") {
+        throw new Error("Console bootstrap is not available behind TLS termination");
+    }
     const runtimeConfig = parseDeploymentRuntimeConfigFromEnv(env);
     const modelConfig = parseModelDeploymentConfigFromEnv(env);
     const authMode = parseDeploymentAuthMode(env);
@@ -642,6 +674,7 @@ export function createDeploymentControlPlane(env = process.env, opts = {}, inter
         consoleSessionAuth: {
             service: consoleSessionAuth,
             secureCookies: tlsTerminated,
+            ...(opts.consoleBootstrap === undefined ? {} : { bootstrap: opts.consoleBootstrap }),
         },
         ...(openapiRoot === undefined ? {} : { openapi: { root: openapiRoot } }),
         ...(authMode === "api-key"

package/dist/src/control-plane/console/bootstrap.js

@@ -0,0 +1,59 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+const DEFAULT_TTL_MS = 10 * 60 * 1000;
+/**
+ * Process-local bearer grants used only to exchange the onboarding browser
+ * handoff for the ordinary opaque console cookie. Grants are never persisted,
+ * are stored by hash, and are removed before their workspace key is returned.
+ */
+export class ConsoleBootstrapService {
+    now;
+    ttlMs;
+    grants = new Map();
+    authority;
+    constructor(now = Date.now, ttlMs = DEFAULT_TTL_MS) {
+        this.now = now;
+        this.ttlMs = ttlMs;
+    }
+    issue(workspaceKey) {
+        const nonce = `ocb_${randomBytes(32).toString("base64url")}`;
+        this.grants.set(hash(nonce), {
+            workspaceKey,
+            expiresAt: this.now() + this.ttlMs,
+        });
+        return nonce;
+    }
+    bindResumeAuthority(workspaceKey, controlToken) {
+        this.authority = {
+            workspaceKey,
+            controlTokenHash: digest(controlToken),
+        };
+    }
+    issueForControlToken(controlToken) {
+        if (this.authority === undefined)
+            return undefined;
+        const candidate = digest(controlToken);
+        if (!timingSafeEqual(candidate, this.authority.controlTokenHash))
+            return undefined;
+        return this.issue(this.authority.workspaceKey);
+    }
+    consume(nonce) {
+        const key = hash(nonce);
+        const grant = this.grants.get(key);
+        // Delete before validating/returning so every attempted consumption is
+        // terminal, including an expired grant or an invalid downstream key.
+        this.grants.delete(key);
+        if (grant === undefined || grant.expiresAt <= this.now())
+            return undefined;
+        return grant.workspaceKey;
+    }
+    clear() {
+        this.grants.clear();
+        this.authority = undefined;
+    }
+}
+function hash(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function digest(value) {
+    return createHash("sha256").update(value).digest();
+}

package/dist/src/control-plane/environments/service.js

@@ -18,6 +18,7 @@ export class DefaultEnvironmentService {
             type: "environment",
             name: req.name,
             config: req.config,
+            metadata: req.metadata ?? {},
             created_at: now,
             updated_at: now,
             archived_at: null,
@@ -83,7 +84,7 @@ function parseCreateEnvironment(input) {
         }
         throw error;
     }
-    return { name, config: canonicalConfig };
+    return { name, config: canonicalConfig, metadata: metadataField(obj) };
 }
 function toManagedEnvironment(row) {
     return {
@@ -91,11 +92,26 @@ function toManagedEnvironment(row) {
         type: row.type,
         name: row.name,
         config: row.config,
+        metadata: row.metadata ?? {},
         created_at: row.created_at,
         updated_at: row.updated_at,
         archived_at: row.archived_at,
     };
 }
+function metadataField(obj) {
+    const value = obj.metadata;
+    if (value === undefined)
+        return undefined;
+    if (!isJsonObject(value))
+        throw invalidRequest("`metadata` must be an object");
+    const metadata = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (typeof item !== "string")
+            throw invalidRequest("`metadata` values must be strings");
+        metadata[key] = item;
+    }
+    return metadata;
+}
 function objectInput(input) {
     if (!isJsonObject(input)) {
         throw invalidRequest("Request body must be a JSON object");

package/dist/src/control-plane/environments/store.js

@@ -6,6 +6,7 @@ CREATE TABLE IF NOT EXISTS environments (
   type          TEXT NOT NULL,
   name          TEXT NOT NULL,
   config        TEXT NOT NULL,
+  metadata      TEXT NOT NULL DEFAULT '{}',
   created_at    TEXT NOT NULL,
   updated_at    TEXT NOT NULL,
   archived_at   TEXT
@@ -26,9 +27,10 @@ export class SqliteEnvironmentStore {
     constructor(db) {
         this.db = db;
         this.db.exec(SCHEMA);
+        migrateMetadata(this.db);
         this.insertStmt = this.db.prepare(`INSERT INTO environments (
-        id, workspace_id, type, name, config, created_at, updated_at, archived_at
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+        id, workspace_id, type, name, config, metadata, created_at, updated_at, archived_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
         this.retrieveActiveStmt = this.db.prepare(`SELECT * FROM environments
        WHERE workspace_id = ? AND id = ? AND archived_at IS NULL`);
         this.retrieveAnyStmt = this.db.prepare(`SELECT * FROM environments WHERE workspace_id = ? AND id = ?`);
@@ -59,7 +61,7 @@ export class SqliteEnvironmentStore {
     }
     create(record) {
         const e = record.row;
-        this.insertStmt.run(e.id, e.workspace_id, e.type, e.name, JSON.stringify(e.config), e.created_at, e.updated_at, e.archived_at);
+        this.insertStmt.run(e.id, e.workspace_id, e.type, e.name, JSON.stringify(e.config), JSON.stringify(e.metadata ?? {}), e.created_at, e.updated_at, e.archived_at);
         return e;
     }
     retrieve(workspaceId, environmentId) {
@@ -125,8 +127,15 @@ function deserialize(row) {
         type: "environment",
         name: row.name,
         config: JSON.parse(row.config),
+        metadata: JSON.parse(row.metadata),
         created_at: row.created_at,
         updated_at: row.updated_at,
         archived_at: row.archived_at,
     };
 }
+function migrateMetadata(db) {
+    const columns = db.prepare("PRAGMA table_info(environments)").all();
+    if (!columns.some((column) => column.name === "metadata")) {
+        db.exec("ALTER TABLE environments ADD COLUMN metadata TEXT NOT NULL DEFAULT '{}'");
+    }
+}

package/dist/src/control-plane/openapi/document.js

@@ -167,8 +167,8 @@ const schemas = {
     CreateAgentRequest: { type: "object", required: ["name", "model"], properties: { name: { type: "string", minLength: 1 }, model: ref("ModelInput"), system: ref("NullableString"), description: ref("NullableString"), tools: { type: "array", items: ref("JsonObject") }, skills: { type: "array", items: ref("JsonObject") }, mcp_servers: { type: "array", items: ref("JsonObject") }, metadata: ref("StringMap"), multiagent: { type: "null", description: "Full multi-agent runtime is not implemented. Omit this field or send null." } }, additionalProperties: false },
     UpdateAgentRequest: { type: "object", required: ["version"], properties: { version: { type: "integer", minimum: 1 }, name: { type: "string", minLength: 1 }, model: ref("ModelInput"), system: ref("NullableString"), description: ref("NullableString"), tools: { type: ["array", "null"], items: ref("JsonObject") }, skills: { type: ["array", "null"], items: ref("JsonObject") }, mcp_servers: { type: ["array", "null"], items: ref("JsonObject") }, metadata: { type: "object", additionalProperties: { type: ["string", "null"] } }, multiagent: { type: "null", description: "Full multi-agent runtime is not implemented. Omit this field or send null." } }, additionalProperties: false },
     Agent: { type: "object", required: ["id", "type", "name", "model", "version", "created_at", "updated_at", "archived_at"], properties: { id: { type: "string" }, type: { const: "agent" }, name: { type: "string" }, model: { type: "object", required: ["provider", "id", "speed"], properties: { provider: { type: "string" }, id: { type: "string" }, speed: { enum: ["standard", "fast"] } }, additionalProperties: false }, system: ref("NullableString"), description: ref("NullableString"), tools: { type: "array", items: ref("JsonObject") }, skills: { type: "array", items: ref("JsonObject") }, mcp_servers: { type: "array", items: ref("JsonObject") }, metadata: ref("StringMap"), multiagent: { type: ["object", "null"] }, version: { type: "integer", minimum: 1 }, created_at: { type: "string", format: "date-time" }, updated_at: { type: "string", format: "date-time" }, archived_at: { type: ["string", "null"], format: "date-time" } }, additionalProperties: false },
-    CreateEnvironmentRequest: { type: "object", required: ["name", "config"], properties: { name: { type: "string", minLength: 1 }, config: ref("JsonObject") }, additionalProperties: false },
-    Environment: { type: "object", required: ["id", "type", "name", "config", "created_at", "updated_at", "archived_at"], properties: { id: { type: "string" }, type: { const: "environment" }, name: { type: "string" }, config: ref("JsonObject"), created_at: { type: "string", format: "date-time" }, updated_at: { type: "string", format: "date-time" }, archived_at: { type: ["string", "null"], format: "date-time" } } },
+    CreateEnvironmentRequest: { type: "object", required: ["name", "config"], properties: { name: { type: "string", minLength: 1 }, config: ref("JsonObject"), metadata: ref("StringMap") }, additionalProperties: false },
+    Environment: { type: "object", required: ["id", "type", "name", "config", "metadata", "created_at", "updated_at", "archived_at"], properties: { id: { type: "string" }, type: { const: "environment" }, name: { type: "string" }, config: ref("JsonObject"), metadata: ref("StringMap"), created_at: { type: "string", format: "date-time" }, updated_at: { type: "string", format: "date-time" }, archived_at: { type: ["string", "null"], format: "date-time" } } },
     DeletedEnvironment: { type: "object", required: ["type", "id"], properties: { type: { const: "environment_deleted" }, id: { type: "string" } }, additionalProperties: false },
     EnvironmentNetworkingPresetCatalog: { type: "object", required: ["type", "deployment", "presets", "custom"], properties: { type: { const: "environment_networking_presets" }, deployment: { type: "object", required: ["provider", "egress_supported", "reason"], properties: { provider: { type: ["string", "null"] }, egress_supported: { type: "boolean" }, reason: { type: ["string", "null"] } }, additionalProperties: false }, presets: { type: "array", items: { type: "object", required: ["id", "version", "name", "description", "networking"], properties: { id: { type: "string" }, version: { type: "integer", minimum: 1 }, name: { type: "string" }, description: { type: "string" }, networking: { type: "object", required: ["type", "allowed_hosts"], properties: { type: { const: "limited" }, allowed_hosts: { type: "array", items: { type: "string" } } }, additionalProperties: false } }, additionalProperties: false } }, custom: { type: "object", required: ["https_only", "wildcard_matches_bare_domain"], properties: { https_only: { const: true }, wildcard_matches_bare_domain: { const: false } }, additionalProperties: false } }, additionalProperties: false },
     ValidateEnvironmentNetworkingHostsRequest: { type: "object", required: ["allowed_hosts"], properties: { allowed_hosts: { type: "array", items: { type: "string" } } }, additionalProperties: false },

package/dist/src/main.js

@@ -50,7 +50,9 @@ export async function startAppliance(env = process.env, opts = {}) {
     const resolved = resolveApplianceEnv(env);
     const port = parseAppliancePort(resolved.OMA_PORT);
     const host = resolved.OMA_HOST ?? "127.0.0.1";
-    const plane = createDeploymentControlPlane(resolved);
+    const plane = createDeploymentControlPlane(resolved, {
+        ...(opts.onboarding === undefined ? {} : { consoleBootstrap: opts.onboarding.bootstrap }),
+    });
     const { app, stores, authMode } = plane;
     let server;
     try {
@@ -70,7 +72,13 @@ export async function startAppliance(env = process.env, opts = {}) {
         // skip minting — an unprinted key locking the operator out. A key that
         // prints but never serves only costs a retry; the reverse costs the
         // quickstart.
-        const minted = authMode === "api-key" && stores.workspaces.countApiKeys() === 0
+        const onboardingKey = authMode === "api-key" && opts.onboarding !== undefined
+            ? mintOnboardingKey(stores.workspaces)
+            : undefined;
+        if (onboardingKey !== undefined) {
+            opts.onboarding.bootstrap.bindResumeAuthority(onboardingKey.plaintextKey, opts.onboarding.controlToken);
+        }
+        const minted = onboardingKey === undefined && authMode === "api-key" && stores.workspaces.countApiKeys() === 0
             ? stores.workspaces.mintKey(DEFAULT_WORKSPACE_ID, "first-boot")
             : undefined;
         const baseUrl = `http://${host}:${boundPort}`;
@@ -93,13 +101,26 @@ export async function startAppliance(env = process.env, opts = {}) {
         }
         return {
             port: boundPort,
+            baseUrl,
+            ...(onboardingKey === undefined
+                ? {}
+                : {
+                    onboarding: {
+                        workspaceKey: onboardingKey.plaintextKey,
+                        bootstrapNonce: opts.onboarding.bootstrap.issue(onboardingKey.plaintextKey),
+                    },
+                }),
             close: async () => {
+                opts.onboarding?.bootstrap.clear();
+                if (onboardingKey !== undefined)
+                    stores.workspaces.revokeKey(onboardingKey.keySha256);
                 await closeServer(bound.server);
                 await plane.close();
             },
         };
     }
     catch (error) {
+        opts.onboarding?.bootstrap.clear();
         // Failed startups must release everything (notably .oma.lock) so the
         // operator's retry is a clean boot, not a lock error.
         if (server !== undefined) {
@@ -109,6 +130,14 @@ export async function startAppliance(env = process.env, opts = {}) {
         throw error;
     }
 }
+function mintOnboardingKey(workspaces) {
+    for (const key of workspaces.listKeys(DEFAULT_WORKSPACE_ID)) {
+        if (key.label === "onboarding-console" && key.revoked_at === null) {
+            workspaces.revokeKey(key.key_sha256);
+        }
+    }
+    return workspaces.mintKey(DEFAULT_WORKSPACE_ID, "onboarding-console");
+}
 function closeServer(server) {
     return new Promise((resolvePromise, reject) => {
         server.close((err) => (err ? reject(err) : resolvePromise()));

package/dist/ui/managed-agents-console/src/api.js

@@ -299,6 +299,10 @@ export function loginConsoleWorkspace(apiKey) {
   return request("/console/auth/workspace", { method: "POST", body: { api_key: apiKey } });
 }
 
+export function consumeConsoleBootstrap(nonce) {
+  return request("/console/auth/bootstrap", { method: "POST", body: { nonce } });
+}
+
 export function loginConsoleAdmin(adminKey) {
   return request("/console/auth/admin", { method: "POST", body: { admin_key: adminKey } });
 }
@@ -707,6 +711,9 @@ function toUiEnvironment(environment) {
     allowedHosts,
     created: shortDate(environment.created_at),
     config: environment.config ?? {},
+    metadata: environment.metadata && typeof environment.metadata === "object"
+      ? environment.metadata
+      : {},
     archived: Boolean(environment.archived_at),
   };
 }
@@ -1010,6 +1017,7 @@ if (typeof window !== "undefined") {
     revokeKey,
     getConsoleAuthStatus,
     loginConsoleWorkspace,
+    consumeConsoleBootstrap,
     loginConsoleAdmin,
     selectConsoleWorkspace,
     logoutConsole,

package/dist/ui/managed-agents-console/src/app.jsx

@@ -127,6 +127,19 @@ function readRouteTarget(sessions, agents) {
   return null;
 }
 
+function takeBootstrapHandoff() {
+  const rawHash = window.location.hash.replace(/^#/, '');
+  const params = new URLSearchParams(rawHash);
+  const nonce = params.get('bootstrap');
+  if (!nonce) return null;
+  params.delete('bootstrap');
+  const nextHash = params.toString();
+  // Clear the bearer value before the network exchange so reload, copy/paste,
+  // browser history, and later application code cannot recover it.
+  window.history.replaceState(null, '', `${window.location.pathname}${window.location.search}${nextHash ? `#${nextHash}` : '#start'}`);
+  return nonce;
+}
+
 function App() {
   const [t, setTweak] = useTweaks(TWEAK_DEFAULTS);
   const demoMode = new URLSearchParams(window.location.search).get('mode') === 'demo';
@@ -191,7 +204,12 @@ function App() {
       if (target) setRoute(target);
       return () => { alive = false; };
     }
-    OmaConsoleApi.getConsoleAuthStatus()
+    const bootstrapNonce = takeBootstrapHandoff();
+    const bootstrap = bootstrapNonce
+      ? OmaConsoleApi.consumeConsoleBootstrap(bootstrapNonce)
+      : Promise.resolve(undefined);
+    bootstrap
+      .then(() => OmaConsoleApi.getConsoleAuthStatus())
       .then((status) => {
         if (!alive) return undefined;
         setAuth({ phase: status.workspace || !status.auth_required || status.admin ? 'ready' : 'login', admin:status.admin, workspace:status.workspace, error:null, busy:false });

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "open-managed-agents",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Self-hostable implementation of Anthropic's Managed Agents API surface.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oneryalcin/open-managed-agents.git"
+  },
+  "homepage": "https://github.com/oneryalcin/open-managed-agents#readme",
+  "bugs": {
+    "url": "https://github.com/oneryalcin/open-managed-agents/issues"
+  },
   "type": "module",
   "bin": {
     "oma": "bin/oma.mjs"
@@ -21,6 +29,7 @@
     "typecheck": "tsc --noEmit",
     "build:package": "node scripts/package-build.mjs",
     "package:verify": "node scripts/package-verify.mjs",
+    "npm:publish": "node scripts/npm-publish.mjs",
     "prepack": "npm run build:package",
     "alpha:smoke": "node scripts/alpha-smoke.mjs",
     "alpha:smoke:providers": "node scripts/alpha-provider-smoke-matrix.mjs",
@@ -28,11 +37,13 @@
     "ui:dev": "node ui/managed-agents-console/serve.mjs"
   },
   "dependencies": {
+    "@clack/prompts": "1.7.0",
     "@earendil-works/pi-coding-agent": "0.80.6",
     "@hono/node-server": "2.0.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "hono": "4.12.29",
     "node-forge": "1.4.0",
+    "picocolors": "1.1.1",
     "proper-lockfile": "4.1.2",
     "typebox": "1.1.29",
     "undici": "7.28.0",