The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
Introduce bind presets for deployment setup
dotta2a84e53c1b82
diff --git a/README.md b/README.mdindex 21edf20abc..bff4b1c71a 100644--- a/README.md+++ b/README.md@@ -177,6 +177,14 @@ Open source. Self-hosted. No Paperclip account required.npx paperclipai onboard --yes```+That quickstart path now defaults to trusted local loopback mode for the fastest first run. To start in authenticated/private mode instead, choose a bind preset explicitly:++```bash+npx paperclipai onboard --yes --bind lan+# or:+npx paperclipai onboard --yes --bind tailnet+```+If you already have Paperclip configured, rerunning `onboard` keeps the existing config in place. Use `paperclipai configure` to edit settings.Or manually:diff --git a/cli/README.md b/cli/README.mdindex 1826e3769b..4de796b5d8 100644--- a/cli/README.md+++ b/cli/README.md@@ -177,6 +177,14 @@ Open source. Self-hosted. No Paperclip account required.npx paperclipai onboard --yes```+That quickstart path now defaults to trusted local loopback mode for the fastest first run. To start in authenticated/private mode instead, choose a bind preset explicitly:++```bash+npx paperclipai onboard --yes --bind lan+# or:+npx paperclipai onboard --yes --bind tailnet+```+If you already have Paperclip configured, rerunning `onboard` keeps the existing config in place. Use `paperclipai configure` to edit settings.Or manually:diff --git a/cli/src/__tests__/network-bind.test.ts b/cli/src/__tests__/network-bind.test.tsnew file mode 100644index 0000000000..4c2bc555b3--- /dev/null+++ b/cli/src/__tests__/network-bind.test.ts@@ -0,0 +1,35 @@+import { describe, expect, it } from "vitest";+import { resolveRuntimeBind, validateConfiguredBindMode } from "@paperclipai/shared";++describe("network bind helpers", () => {+ it("rejects non-loopback bind modes in local_trusted", () => {+ expect(+ validateConfiguredBindMode({+ deploymentMode: "local_trusted",+ deploymentExposure: "private",+ bind: "lan",+ host: "0.0.0.0",+ }),+ ).toContain("local_trusted requires server.bind=loopback");+ });++ it("resolves tailnet bind using the detected tailscale address", () => {+ const resolved = resolveRuntimeBind({+ bind: "tailnet",+ host: "127.0.0.1",+ tailnetBindHost: "100.64.0.8",+ });++ expect(resolved.errors).toEqual([]);+ expect(resolved.host).toBe("100.64.0.8");+ });++ it("requires a custom bind host when bind=custom", () => {+ const resolved = resolveRuntimeBind({+ bind: "custom",+ host: "127.0.0.1",+ });++ expect(resolved.errors).toContain("server.customBindHost is required when server.bind=custom");+ });+});diff --git a/cli/src/__tests__/onboard.test.ts b/cli/src/__tests__/onboard.test.tsindex df1a91b810..f686e071b4 100644--- a/cli/src/__tests__/onboard.test.ts+++ b/cli/src/__tests__/onboard.test.ts@@ -74,6 +74,11 @@ function createExistingConfigFixture() {return { configPath, configText: fs.readFileSync(configPath, "utf8") };}+function createFreshConfigPath() {+ const root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-onboard-fresh-"));+ return path.join(root, ".paperclip", "config.json");+}+describe("onboard", () => {beforeEach(() => {process.env = { ...ORIGINAL_ENV };@@ -105,4 +110,43 @@ describe("onboard", () => {expect(fs.existsSync(`${fixture.configPath}.backup`)).toBe(false);expect(fs.existsSync(path.join(path.dirname(fixture.configPath), ".env"))).toBe(true);});++ it("keeps --yes onboarding on local trusted loopback defaults", async () => {+ const configPath = createFreshConfigPath();+ process.env.HOST = "0.0.0.0";+ process.env.PAPERCLIP_BIND = "lan";++ await onboard({ config: configPath, yes: true, invokedByRun: true });++ const raw = JSON.parse(fs.readFileSync(configPath, "utf8")) as PaperclipConfig;+ expect(raw.server.deploymentMode).toBe("local_trusted");+ expect(raw.server.exposure).toBe("private");+ expect(raw.server.bind).toBe("loopback");+ expect(raw.server.host).toBe("127.0.0.1");+ });++ it("supports authenticated/private quickstart bind presets", async () => {+ const configPath = createFreshConfigPath();++ await onboard({ config: configPath, yes: true, invokedByRun: true, bind: "tailnet" });++ const raw = JSON.parse(fs.readFileSync(configPath, "utf8")) as PaperclipConfig;+ expect(raw.server.deploymentMode).toBe("authenticated");+ expect(raw.server.exposure).toBe("private");+ expect(raw.server.bind).toBe("tailnet");+ expect(raw.server.host).toBe("0.0.0.0");+ });++ it("ignores deployment env overrides during --yes quickstart", async () => {+ const configPath = createFreshConfigPath();+ process.env.PAPERCLIP_DEPLOYMENT_MODE = "authenticated";++ await onboard({ config: configPath, yes: true, invokedByRun: true });++ const raw = JSON.parse(fs.readFileSync(configPath, "utf8")) as PaperclipConfig;+ expect(raw.server.deploymentMode).toBe("local_trusted");+ expect(raw.server.exposure).toBe("private");+ expect(raw.server.bind).toBe("loopback");+ expect(raw.server.host).toBe("127.0.0.1");+ });});diff --git a/cli/src/checks/deployment-auth-check.ts b/cli/src/checks/deployment-auth-check.tsindex 580e7e08f3..6434ede07c 100644--- a/cli/src/checks/deployment-auth-check.ts+++ b/cli/src/checks/deployment-auth-check.ts@@ -1,24 +1,21 @@+import { inferBindModeFromHost } from "@paperclipai/shared";import type { PaperclipConfig } from "../config/schema.js";import type { CheckResult } from "./index.js";-function isLoopbackHost(host: string) {- const normalized = host.trim().toLowerCase();- return normalized === "127.0.0.1" || normalized === "localhost" || normalized === "::1";-}-export function deploymentAuthCheck(config: PaperclipConfig): CheckResult {const mode = config.server.deploymentMode;const exposure = config.server.exposure;const auth = config.auth;+ const bind = config.server.bind ?? inferBindModeFromHost(config.server.host);if (mode === "local_trusted") {- if (!isLoopbackHost(config.server.host)) {+ if (bind !== "loopback") {return {name: "Deployment/auth mode",status: "fail",- message: `local_trusted requires loopback host binding (found ${config.server.host})`,+ message: `local_trusted requires loopback binding (found ${bind})`,canRepair: false,- repairHint: "Run `paperclipai configure --section server` and set host to 127.0.0.1",+ repairHint: "Run `paperclipai configure --section server` and choose Local trusted / loopback reachability",};}return {@@ -86,6 +83,6 @@ export function deploymentAuthCheck(config: PaperclipConfig): CheckResult {return {name: "Deployment/auth mode",status: "pass",- message: `Mode ${mode}/${exposure} with auth URL mode ${auth.baseUrlMode}`,+ message: `Mode ${mode}/${exposure} with bind ${bind} and auth URL mode ${auth.baseUrlMode}`,};}diff --git a/cli/src/commands/auth-bootstrap-ceo.ts b/cli/src/commands/auth-bootstrap-ceo.tsindex dc720f63d8..d07b9a7039 100644--- a/cli/src/commands/auth-bootstrap-ceo.ts+++ b/cli/src/commands/auth-bootstrap-ceo.ts@@ -3,6 +3,7 @@ import * as p from "@clack/prompts";import pc from "picocolors";import { and, eq, gt, isNull } from "drizzle-orm";import { createDb, instanceUserRoles, invites } from "@paperclipai/db";+import { inferBindModeFromHost } from "@paperclipai/shared";import { loadPaperclipEnvFile } from "../config/env.js";import { readConfig, resolveConfigPath } from "../config/store.js";@@ -40,9 +41,13 @@ function resolveBaseUrl(configPath?: string, explicitBaseUrl?: string) {if (config?.auth.baseUrlMode === "explicit" && config.auth.publicBaseUrl) {return config.auth.publicBaseUrl.replace(/\/+$/, "");}- const host = config?.server.host ?? "localhost";+ const bind = config?.server.bind ?? inferBindModeFromHost(config?.server.host);+ const host =+ bind === "custom"+ ? config?.server.customBindHost ?? config?.server.host ?? "localhost"+ : config?.server.host ?? "localhost";const port = config?.server.port ?? 3100;- const publicHost = host === "0.0.0.0" ? "localhost" : host;+ const publicHost = host === "0.0.0.0" || bind === "lan" ? "localhost" : host;return `http://${publicHost}:${port}`;}diff --git a/cli/src/commands/configure.ts b/cli/src/commands/configure.tsindex 83ff089be6..b7d2dcbc07 100644--- a/cli/src/commands/configure.ts+++ b/cli/src/commands/configure.ts@@ -54,6 +54,7 @@ function defaultConfig(): PaperclipConfig {server: {deploymentMode: "local_trusted",exposure: "private",+ bind: "loopback",host: "127.0.0.1",port: 3100,allowedHostnames: [],diff --git a/cli/src/commands/onboard.ts b/cli/src/commands/onboard.tsindex d9b325a8c1..0fabfd0ac4 100644--- a/cli/src/commands/onboard.ts+++ b/cli/src/commands/onboard.ts@@ -3,10 +3,14 @@ import path from "node:path";import pc from "picocolors";import {AUTH_BASE_URL_MODES,+ BIND_MODES,DEPLOYMENT_EXPOSURES,DEPLOYMENT_MODES,SECRET_PROVIDERS,STORAGE_PROVIDERS,+ inferBindModeFromHost,+ resolveRuntimeBind,+ type BindMode,type AuthBaseUrlMode,type DeploymentExposure,type DeploymentMode,@@ -23,6 +27,7 @@ import { promptLogging } from "../prompts/logging.js";import { defaultSecretsConfig } from "../prompts/secrets.js";import { defaultStorageConfig, promptStorage } from "../prompts/storage.js";import { promptServer } from "../prompts/server.js";+import { buildPresetServerConfig } from "../config/server-bind.js";import {describeLocalInstancePaths,expandHomePrefix,@@ -46,6 +51,7 @@ type OnboardOptions = {run?: boolean;yes?: boolean;invokedByRun?: boolean;+ bind?: BindMode;};type OnboardDefaults = Pick<PaperclipConfig, "database" | "logging" | "server" | "auth" | "storage" | "secrets">;@@ -59,6 +65,9 @@ const ONBOARD_ENV_KEYS = ["PAPERCLIP_DB_BACKUP_DIR","PAPERCLIP_DEPLOYMENT_MODE","PAPERCLIP_DEPLOYMENT_EXPOSURE",+ "PAPERCLIP_BIND",+ "PAPERCLIP_BIND_HOST",+ "PAPERCLIP_TAILNET_BIND_HOST","HOST","PORT","SERVE_UI",@@ -104,29 +113,62 @@ function resolvePathFromEnv(rawValue: string | undefined): string | null {return path.resolve(expandHomePrefix(rawValue.trim()));}-function quickstartDefaultsFromEnv(): {+function describeServerBinding(server: Pick<PaperclipConfig["server"], "bind" | "customBindHost" | "host" | "port">): string {+ const bind = server.bind ?? inferBindModeFromHost(server.host);+ const detail =+ bind === "custom"+ ? server.customBindHost ?? server.host+ : bind === "tailnet"+ ? "detected tailscale address"+ : server.host;+ return `${bind}${detail ? ` (${detail})` : ""}:${server.port}`;+}++function quickstartDefaultsFromEnv(opts?: { preferTrustedLocal?: boolean }): {defaults: OnboardDefaults;usedEnvKeys: string[];ignoredEnvKeys: Array<{ key: string; reason: string }>;} {+ const preferTrustedLocal = opts?.preferTrustedLocal ?? false;const instanceId = resolvePaperclipInstanceId();const defaultStorage = defaultStorageConfig();const defaultSecrets = defaultSecretsConfig();const databaseUrl = process.env.DATABASE_URL?.trim() || undefined;- const publicUrl =- process.env.PAPERCLIP_PUBLIC_URL?.trim() ||- process.env.PAPERCLIP_AUTH_PUBLIC_BASE_URL?.trim() ||- process.env.BETTER_AUTH_URL?.trim() ||- process.env.BETTER_AUTH_BASE_URL?.trim() ||- undefined;- const deploymentMode =- parseEnumFromEnv<DeploymentMode>(process.env.PAPERCLIP_DEPLOYMENT_MODE, DEPLOYMENT_MODES) ?? "local_trusted";+ const publicUrl = preferTrustedLocal+ ? undefined+ : (+ process.env.PAPERCLIP_PUBLIC_URL?.trim() ||+ process.env.PAPERCLIP_AUTH_PUBLIC_BASE_URL?.trim() ||+ process.env.BETTER_AUTH_URL?.trim() ||+ process.env.BETTER_AUTH_BASE_URL?.trim() ||+ undefined+ );+ const deploymentMode = preferTrustedLocal+ ? "local_trusted"+ : (parseEnumFromEnv<DeploymentMode>(process.env.PAPERCLIP_DEPLOYMENT_MODE, DEPLOYMENT_MODES) ?? "local_trusted");const deploymentExposureFromEnv = parseEnumFromEnv<DeploymentExposure>(process.env.PAPERCLIP_DEPLOYMENT_EXPOSURE,DEPLOYMENT_EXPOSURES,);const deploymentExposure =deploymentMode === "local_trusted" ? "private" : (deploymentExposureFromEnv ?? "private");+ const bindFromEnv = parseEnumFromEnv<BindMode>(process.env.PAPERCLIP_BIND, BIND_MODES);+ const customBindHostFromEnv = process.env.PAPERCLIP_BIND_HOST?.trim() || undefined;+ const hostFromEnv = process.env.HOST?.trim() || undefined;+ const configuredBindHost = customBindHostFromEnv ?? hostFromEnv;+ const bind = preferTrustedLocal+ ? "loopback"+ : (+ deploymentMode === "local_trusted"+ ? "loopback"+ : (bindFromEnv ?? (configuredBindHost ? inferBindModeFromHost(configuredBindHost) : "lan"))+ );+ const resolvedBind = resolveRuntimeBind({+ bind,+ host: hostFromEnv ?? (bind === "loopback" ? "127.0.0.1" : "0.0.0.0"),+ customBindHost: customBindHostFromEnv,+ tailnetBindHost: process.env.PAPERCLIP_TAILNET_BIND_HOST?.trim(),+ });const authPublicBaseUrl = publicUrl;const authBaseUrlModeFromEnv = parseEnumFromEnv<AuthBaseUrlMode>(process.env.PAPERCLIP_AUTH_BASE_URL_MODE,@@ -183,7 +225,9 @@ function quickstartDefaultsFromEnv(): {server: {deploymentMode,exposure: deploymentExposure,- host: process.env.HOST ?? "127.0.0.1",+ bind: resolvedBind.bind,+ ...(resolvedBind.customBindHost ? { customBindHost: resolvedBind.customBindHost } : {}),+ host: resolvedBind.host,port: Number(process.env.PORT) || 3100,allowedHostnames: Array.from(new Set([...allowedHostnamesFromEnv, ...(hostnameFromPublicUrl ? [hostnameFromPublicUrl] : [])])),serveUi: parseBooleanFromEnv(process.env.SERVE_UI) ?? true,@@ -220,12 +264,49 @@ function quickstartDefaultsFromEnv(): {},};const ignoredEnvKeys: Array<{ key: string; reason: string }> = [];+ if (preferTrustedLocal) {+ const forcedLocalReason = "Ignored because --yes quickstart forces trusted local loopback defaults";+ for (const key of [+ "PAPERCLIP_DEPLOYMENT_MODE",+ "PAPERCLIP_DEPLOYMENT_EXPOSURE",+ "PAPERCLIP_BIND",+ "PAPERCLIP_BIND_HOST",+ "HOST",+ "PAPERCLIP_AUTH_BASE_URL_MODE",+ "PAPERCLIP_AUTH_PUBLIC_BASE_URL",+ "PAPERCLIP_PUBLIC_URL",+ "BETTER_AUTH_URL",+ "BETTER_AUTH_BASE_URL",+ ] as const) {+ if (process.env[key] !== undefined) {+ ignoredEnvKeys.push({ key, reason: forcedLocalReason });+ }+ }+ }if (deploymentMode === "local_trusted" && process.env.PAPERCLIP_DEPLOYMENT_EXPOSURE !== undefined) {ignoredEnvKeys.push({key: "PAPERCLIP_DEPLOYMENT_EXPOSURE",reason: "Ignored because deployment mode local_trusted always forces private exposure",});}+ if (deploymentMode === "local_trusted" && process.env.PAPERCLIP_BIND !== undefined) {+ ignoredEnvKeys.push({+ key: "PAPERCLIP_BIND",+ reason: "Ignored because deployment mode local_trusted always uses loopback reachability",+ });+ }+ if (deploymentMode === "local_trusted" && process.env.PAPERCLIP_BIND_HOST !== undefined) {+ ignoredEnvKeys.push({+ key: "PAPERCLIP_BIND_HOST",+ reason: "Ignored because deployment mode local_trusted always uses loopback reachability",+ });+ }+ if (deploymentMode === "local_trusted" && process.env.HOST !== undefined) {+ ignoredEnvKeys.push({+ key: "HOST",+ reason: "Ignored because deployment mode local_trusted always uses loopback reachability",+ });+ }const ignoredKeySet = new Set(ignoredEnvKeys.map((entry) => entry.key));const usedEnvKeys = ONBOARD_ENV_KEYS.filter(@@ -239,6 +320,10 @@ function canCreateBootstrapInviteImmediately(config: Pick<PaperclipConfig, "data}export async function onboard(opts: OnboardOptions): Promise<void> {+ if (opts.bind && !["loopback", "lan", "tailnet"].includes(opts.bind)) {+ throw new Error(`Unsupported bind preset for onboard: ${opts.bind}. Use loopback, lan, or tailnet.`);+ }+printPaperclipCliBanner();p.intro(pc.bgCyan(pc.black(" paperclipai onboard ")));const configPath = resolveConfigPath(opts.config);@@ -293,7 +378,7 @@ export async function onboard(opts: OnboardOptions): Promise<void> {`Database: ${existingConfig.database.mode}`,existingConfig.llm ? `LLM: ${existingConfig.llm.provider}` : "LLM: not configured",`Logging: ${existingConfig.logging.mode} -> ${existingConfig.logging.logDir}`,- `Server: ${existingConfig.server.deploymentMode}/${existingConfig.server.exposure} @ ${existingConfig.server.host}:${existingConfig.server.port}`,+ `Server: ${existingConfig.server.deploymentMode}/${existingConfig.server.exposure} @ ${describeServerBinding(existingConfig.server)}`,`Allowed hosts: ${existingConfig.server.allowedHostnames.length > 0 ? existingConfig.server.allowedHostnames.join(", ") : "(loopback only)"}`,`Auth URL mode: ${existingConfig.auth.baseUrlMode}${existingConfig.auth.publicBaseUrl ? ` (${existingConfig.auth.publicBaseUrl})` : ""}`,`Storage: ${existingConfig.storage.provider}`,@@ -336,7 +421,13 @@ export async function onboard(opts: OnboardOptions): Promise<void> {let setupMode: SetupMode = "quickstart";if (opts.yes) {- p.log.message(pc.dim("`--yes` enabled: using Quickstart defaults."));+ p.log.message(+ pc.dim(+ opts.bind+ ? `\`--yes\` enabled: using Quickstart defaults with bind=${opts.bind}.`+ : "`--yes` enabled: using Quickstart defaults.",+ ),+ );} else {const setupModeChoice = await p.select({message: "Choose setup path",@@ -365,7 +456,9 @@ export async function onboard(opts: OnboardOptions): Promise<void> {if (tc) trackInstallStarted(tc);let llm: PaperclipConfig["llm"] | undefined;- const { defaults: derivedDefaults, usedEnvKeys, ignoredEnvKeys } = quickstartDefaultsFromEnv();+ const { defaults: derivedDefaults, usedEnvKeys, ignoredEnvKeys } = quickstartDefaultsFromEnv({+ preferTrustedLocal: opts.yes === true && !opts.bind,+ });let {database,logging,@@ -375,6 +468,16 @@ export async function onboard(opts: OnboardOptions): Promise<void> {secrets,} = derivedDefaults;+ if (opts.bind === "loopback" || opts.bind === "lan" || opts.bind === "tailnet") {+ const preset = buildPresetServerConfig(opts.bind, {+ port: server.port,+ allowedHostnames: server.allowedHostnames,+ serveUi: server.serveUi,+ });+ server = preset.server;+ auth = preset.auth;+ }+if (setupMode === "advanced") {p.log.step(pc.bold("Database"));database = await promptDatabase(database);@@ -462,7 +565,13 @@ export async function onboard(opts: OnboardOptions): Promise<void> {);} else {p.log.step(pc.bold("Quickstart"));- p.log.message(pc.dim("Using quickstart defaults."));+ p.log.message(+ pc.dim(+ opts.bind+ ? `Using quickstart defaults with bind=${opts.bind}.`+ : `Using quickstart defaults: ${server.deploymentMode}/${server.exposure} @ ${describeServerBinding(server)}.`,+ ),+ );if (usedEnvKeys.length > 0) {p.log.message(pc.dim(`Environment-aware defaults active (${usedEnvKeys.length} env var(s) detected).`));} else {@@ -521,7 +630,7 @@ export async function onboard(opts: OnboardOptions): Promise<void> {`Database: ${database.mode}`,llm ? `LLM: ${llm.provider}` : "LLM: not configured",`Logging: ${logging.mode} -> ${logging.logDir}`,- `Server: ${server.deploymentMode}/${server.exposure} @ ${server.host}:${server.port}`,+ `Server: ${server.deploymentMode}/${server.exposure} @ ${describeServerBinding(server)}`,`Allowed hosts: ${server.allowedHostnames.length > 0 ? server.allowedHostnames.join(", ") : "(loopback only)"}`,`Auth URL mode: ${auth.baseUrlMode}${auth.publicBaseUrl ? ` (${auth.publicBaseUrl})` : ""}`,`Storage: ${storage.provider}`,diff --git a/cli/src/commands/run.ts b/cli/src/commands/run.tsindex b39ab06cee..9bc9655b44 100644--- a/cli/src/commands/run.ts+++ b/cli/src/commands/run.ts@@ -22,6 +22,7 @@ interface RunOptions {instance?: string;repair?: boolean;yes?: boolean;+ bind?: "loopback" | "lan" | "tailnet";}interface StartedServer {@@ -58,7 +59,7 @@ export async function runCommand(opts: RunOptions): Promise<void> {}p.log.step("No config found. Starting onboarding...");- await onboard({ config: configPath, invokedByRun: true });+ await onboard({ config: configPath, invokedByRun: true, bind: opts.bind });}p.log.step("Running doctor checks...");diff --git a/cli/src/commands/worktree-lib.ts b/cli/src/commands/worktree-lib.tsindex d2b6c5f734..5d4a072119 100644--- a/cli/src/commands/worktree-lib.ts+++ b/cli/src/commands/worktree-lib.ts@@ -214,6 +214,8 @@ export function buildWorktreeConfig(input: {server: {deploymentMode: source?.server.deploymentMode ?? "local_trusted",exposure: source?.server.exposure ?? "private",+ ...(source?.server.bind ? { bind: source.server.bind } : {}),+ ...(source?.server.customBindHost ? { customBindHost: source.server.customBindHost } : {}),host: source?.server.host ?? "127.0.0.1",port: serverPort,allowedHostnames: source?.server.allowedHostnames ?? [],diff --git a/cli/src/config/server-bind.ts b/cli/src/config/server-bind.tsnew file mode 100644index 0000000000..93cd3effd0--- /dev/null+++ b/cli/src/config/server-bind.ts@@ -0,0 +1,156 @@+import {+ ALL_INTERFACES_BIND_HOST,+ LOOPBACK_BIND_HOST,+ inferBindModeFromHost,+ isAllInterfacesHost,+ isLoopbackHost,+ type BindMode,+ type DeploymentExposure,+ type DeploymentMode,+} from "@paperclipai/shared";+import type { AuthConfig, ServerConfig } from "./schema.js";++type BaseServerInput = {+ port: number;+ allowedHostnames: string[];+ serveUi: boolean;+};++export function inferConfiguredBind(server?: Partial<ServerConfig>): BindMode {+ if (server?.bind) return server.bind;+ return inferBindModeFromHost(server?.customBindHost ?? server?.host);+}++export function buildPresetServerConfig(+ bind: Exclude<BindMode, "custom">,+ input: BaseServerInput,+): { server: ServerConfig; auth: AuthConfig } {+ const host = bind === "loopback" ? LOOPBACK_BIND_HOST : ALL_INTERFACES_BIND_HOST;++ return {+ server: {+ deploymentMode: bind === "loopback" ? "local_trusted" : "authenticated",+ exposure: "private",+ bind,+ customBindHost: undefined,+ host,+ port: input.port,+ allowedHostnames: input.allowedHostnames,+ serveUi: input.serveUi,+ },+ auth: {+ baseUrlMode: "auto",+ disableSignUp: false,+ },+ };+}++export function buildCustomServerConfig(input: BaseServerInput & {+ deploymentMode: DeploymentMode;+ exposure: DeploymentExposure;+ host: string;+ publicBaseUrl?: string;+}): { server: ServerConfig; auth: AuthConfig } {+ const normalizedHost = input.host.trim();+ const bind = isLoopbackHost(normalizedHost)+ ? "loopback"+ : isAllInterfacesHost(normalizedHost)+ ? "lan"+ : "custom";++ return {+ server: {+ deploymentMode: input.deploymentMode,+ exposure: input.deploymentMode === "local_trusted" ? "private" : input.exposure,+ bind,+ customBindHost: bind === "custom" ? normalizedHost : undefined,+ host: normalizedHost,+ port: input.port,+ allowedHostnames: input.allowedHostnames,+ serveUi: input.serveUi,+ },+ auth:+ input.deploymentMode === "authenticated" && input.exposure === "public"+ ? {+ baseUrlMode: "explicit",+ disableSignUp: false,+ publicBaseUrl: input.publicBaseUrl,+ }+ : {+ baseUrlMode: "auto",+ disableSignUp: false,+ },+ };+}++export function resolveQuickstartServerConfig(input: {+ bind?: BindMode | null;+ deploymentMode?: DeploymentMode | null;+ exposure?: DeploymentExposure | null;+ host?: string | null;+ port: number;+ allowedHostnames: string[];+ serveUi: boolean;+ publicBaseUrl?: string;+}): { server: ServerConfig; auth: AuthConfig } {+ const trimmedHost = input.host?.trim();+ const explicitBind = input.bind ?? null;++ if (explicitBind === "loopback" || explicitBind === "lan" || explicitBind === "tailnet") {+ return buildPresetServerConfig(explicitBind, {+ port: input.port,+ allowedHostnames: input.allowedHostnames,+ serveUi: input.serveUi,+ });+ }++ if (explicitBind === "custom") {+ return buildCustomServerConfig({+ deploymentMode: input.deploymentMode ?? "authenticated",+ exposure: input.exposure ?? "private",+ host: trimmedHost || LOOPBACK_BIND_HOST,+ port: input.port,+ allowedHostnames: input.allowedHostnames,+ serveUi: input.serveUi,+ publicBaseUrl: input.publicBaseUrl,+ });+ }++ if (trimmedHost) {+ return buildCustomServerConfig({+ deploymentMode: input.deploymentMode ?? (isLoopbackHost(trimmedHost) ? "local_trusted" : "authenticated"),+ exposure: input.exposure ?? "private",+ host: trimmedHost,+ port: input.port,+ allowedHostnames: input.allowedHostnames,+ serveUi: input.serveUi,+ publicBaseUrl: input.publicBaseUrl,+ });+ }++ if (input.deploymentMode === "authenticated") {+ if (input.exposure === "public") {+ return buildCustomServerConfig({+ deploymentMode: "authenticated",+ exposure: "public",+ host: ALL_INTERFACES_BIND_HOST,+ port: input.port,+ allowedHostnames: input.allowedHostnames,+ serveUi: input.serveUi,+ publicBaseUrl: input.publicBaseUrl,+ });+ }++ return buildPresetServerConfig("lan", {+ port: input.port,+ allowedHostnames: input.allowedHostnames,+ serveUi: input.serveUi,+ });+ }++ return buildPresetServerConfig("loopback", {+ port: input.port,+ allowedHostnames: input.allowedHostnames,+ serveUi: input.serveUi,+ });+}diff --git a/cli/src/index.ts b/cli/src/index.tsindex 1173945961..b2208798a7 100644--- a/cli/src/index.ts+++ b/cli/src/index.ts@@ -50,7 +50,8 @@ program.description("Interactive first-run setup wizard").option("-c, --config <path>", "Path to config file").option("-d, --data-dir <path>", DATA_DIR_OPTION_HELP)- .option("-y, --yes", "Accept defaults (quickstart + start immediately)", false)+ .option("--bind <mode>", "Quickstart reachability preset (loopback, lan, tailnet)")+ .option("-y, --yes", "Accept quickstart defaults (trusted local loopback unless --bind is set) and start immediately", false).option("--run", "Start Paperclip immediately after saving config", false).action(onboard);@@ -108,6 +109,7 @@ program.option("-c, --config <path>", "Path to config file").option("-d, --data-dir <path>", DATA_DIR_OPTION_HELP).option("-i, --instance <id>", "Local instance id (default: default)")+ .option("--bind <mode>", "On first run, use onboarding reachability preset (loopback, lan, tailnet)").option("--repair", "Attempt automatic repairs during doctor", true).option("--no-repair", "Disable automatic repairs during doctor").action(runCommand);diff --git a/cli/src/prompts/server.ts b/cli/src/prompts/server.tsindex e5c2618068..7881018806 100644--- a/cli/src/prompts/server.ts+++ b/cli/src/prompts/server.ts@@ -1,6 +1,17 @@import * as p from "@clack/prompts";+import { isLoopbackHost, type BindMode } from "@paperclipai/shared";import type { AuthConfig, ServerConfig } from "../config/schema.js";import { parseHostnameCsv } from "../config/hostnames.js";+import {+ buildCustomServerConfig,+ buildPresetServerConfig,+ inferConfiguredBind,+} from "../config/server-bind.js";++function cancelled(): never {+ p.cancel("Setup cancelled.");+ process.exit(0);+}export async function promptServer(opts?: {currentServer?: Partial<ServerConfig>;@@ -8,28 +19,107 @@ export async function promptServer(opts?: {}): Promise<{ server: ServerConfig; auth: AuthConfig }> {const currentServer = opts?.currentServer;const currentAuth = opts?.currentAuth;+ const currentBind = inferConfiguredBind(currentServer);++ const bindSelection = await p.select({+ message: "Reachability",+ options: [+ {+ value: "loopback" as const,+ label: "Trusted local",+ hint: "Recommended for first run: localhost only, no login friction",+ },+ {+ value: "lan" as const,+ label: "Private network",+ hint: "Broad private bind for LAN, VPN, or legacy --tailscale-auth style access",+ },+ {+ value: "tailnet" as const,+ label: "Tailnet",+ hint: "Private authenticated access using the machine's detected Tailscale address",+ },+ {+ value: "custom" as const,+ label: "Custom",+ hint: "Choose exact auth mode, exposure, and host manually",+ },+ ],+ initialValue: currentBind,+ });++ if (p.isCancel(bindSelection)) cancelled();+ const bind = bindSelection as BindMode;++ const portStr = await p.text({+ message: "Server port",+ defaultValue: String(currentServer?.port ?? 3100),+ placeholder: "3100",+ validate: (val) => {+ const n = Number(val);+ if (isNaN(n) || n < 1 || n > 65535 || !Number.isInteger(n)) {+ return "Must be an integer between 1 and 65535";+ }+ },+ });++ if (p.isCancel(portStr)) cancelled();+ const port = Number(portStr) || 3100;+ const serveUi = currentServer?.serveUi ?? true;++ if (bind === "loopback") {+ return buildPresetServerConfig("loopback", {+ port,+ allowedHostnames: [],+ serveUi,+ });+ }++ if (bind === "lan" || bind === "tailnet") {+ const allowedHostnamesInput = await p.text({+ message: "Allowed private hostnames (comma-separated, optional)",+ defaultValue: (currentServer?.allowedHostnames ?? []).join(", "),+ placeholder:+ bind === "tailnet"+ ? "your-machine.tailnet.ts.net"+ : "dotta-macbook-pro, host.docker.internal",+ validate: (val) => {+ try {+ parseHostnameCsv(val);+ return;+ } catch (err) {+ return err instanceof Error ? err.message : "Invalid hostname list";+ }+ },+ });++ if (p.isCancel(allowedHostnamesInput)) cancelled();++ return buildPresetServerConfig(bind, {+ port,+ allowedHostnames: parseHostnameCsv(allowedHostnamesInput),+ serveUi,+ });+ }const deploymentModeSelection = await p.select({- message: "Deployment mode",+ message: "Auth mode",options: [{value: "local_trusted",label: "Local trusted",- hint: "Easiest for local setup (no login, localhost-only)",+ hint: "No login required; only safe with loopback-only or similarly trusted access",},{value: "authenticated",label: "Authenticated",- hint: "Login required; use for private network or public hosting",+ hint: "Login required; supports both private-network and public deployments",},],- initialValue: currentServer?.deploymentMode ?? "local_trusted",+ initialValue: currentServer?.deploymentMode ?? "authenticated",});- if (p.isCancel(deploymentModeSelection)) {- p.cancel("Setup cancelled.");- process.exit(0);- }+ if (p.isCancel(deploymentModeSelection)) cancelled();const deploymentMode = deploymentModeSelection as ServerConfig["deploymentMode"];let exposure: ServerConfig["exposure"] = "private";@@ -40,59 +130,42 @@ export async function promptServer(opts?: {{value: "private",label: "Private network",- hint: "Private access (for example Tailscale), lower setup friction",+ hint: "Private access only, with automatic URL handling",},{value: "public",label: "Public internet",- hint: "Internet-facing deployment with stricter requirements",+ hint: "Internet-facing deployment with explicit public URL requirements",},],initialValue: currentServer?.exposure ?? "private",});- if (p.isCancel(exposureSelection)) {- p.cancel("Setup cancelled.");- process.exit(0);- }+ if (p.isCancel(exposureSelection)) cancelled();exposure = exposureSelection as ServerConfig["exposure"];}- const hostDefault = deploymentMode === "local_trusted" ? "127.0.0.1" : "0.0.0.0";- const hostStr = await p.text({+ const defaultHost =+ currentServer?.customBindHost ??+ currentServer?.host ??+ (deploymentMode === "local_trusted" ? "127.0.0.1" : "0.0.0.0");+ const host = await p.text({message: "Bind host",- defaultValue: currentServer?.host ?? hostDefault,- placeholder: hostDefault,+ defaultValue: defaultHost,+ placeholder: defaultHost,validate: (val) => {if (!val.trim()) return "Host is required";- },- });-- if (p.isCancel(hostStr)) {- p.cancel("Setup cancelled.");- process.exit(0);- }-- const portStr = await p.text({- message: "Server port",- defaultValue: String(currentServer?.port ?? 3100),- placeholder: "3100",- validate: (val) => {- const n = Number(val);- if (isNaN(n) || n < 1 || n > 65535 || !Number.isInteger(n)) {- return "Must be an integer between 1 and 65535";+ if (deploymentMode === "local_trusted" && !isLoopbackHost(val.trim())) {+ return "Local trusted mode requires a loopback host such as 127.0.0.1";}},});- if (p.isCancel(portStr)) {- p.cancel("Setup cancelled.");- process.exit(0);- }+ if (p.isCancel(host)) cancelled();let allowedHostnames: string[] = [];if (deploymentMode === "authenticated" && exposure === "private") {const allowedHostnamesInput = await p.text({- message: "Allowed hostnames (comma-separated, optional)",+ message: "Allowed private hostnames (comma-separated, optional)",defaultValue: (currentServer?.allowedHostnames ?? []).join(", "),placeholder: "dotta-macbook-pro, your-host.tailnet.ts.net",validate: (val) => {@@ -105,15 +178,11 @@ export async function promptServer(opts?: {},});- if (p.isCancel(allowedHostnamesInput)) {- p.cancel("Setup cancelled.");- process.exit(0);- }+ if (p.isCancel(allowedHostnamesInput)) cancelled();allowedHostnames = parseHostnameCsv(allowedHostnamesInput);}- const port = Number(portStr) || 3100;- let auth: AuthConfig = { baseUrlMode: "auto", disableSignUp: false };+ let publicBaseUrl: string | undefined;if (deploymentMode === "authenticated" && exposure === "public") {const urlInput = await p.text({message: "Public base URL",@@ -133,32 +202,17 @@ export async function promptServer(opts?: {}},});- if (p.isCancel(urlInput)) {- p.cancel("Setup cancelled.");- process.exit(0);- }- auth = {- baseUrlMode: "explicit",- disableSignUp: false,- publicBaseUrl: urlInput.trim().replace(/\/+$/, ""),- };- } else if (currentAuth?.baseUrlMode === "explicit" && currentAuth.publicBaseUrl) {- auth = {- baseUrlMode: "explicit",- disableSignUp: false,- publicBaseUrl: currentAuth.publicBaseUrl,- };+ if (p.isCancel(urlInput)) cancelled();+ publicBaseUrl = urlInput.trim().replace(/\/+$/, "");}- return {- server: {- deploymentMode,- exposure,- host: hostStr.trim(),- port,- allowedHostnames,- serveUi: currentServer?.serveUi ?? true,- },- auth,- };+ return buildCustomServerConfig({+ deploymentMode,+ exposure,+ host: host.trim(),+ port,+ allowedHostnames,+ serveUi,+ publicBaseUrl,+ });}diff --git a/doc/CLI.md b/doc/CLI.mdindex 6f945656d4..c124b44745 100644--- a/doc/CLI.md+++ b/doc/CLI.md@@ -32,10 +32,12 @@ Mode taxonomy and design intent are documented in `doc/DEPLOYMENT-MODES.md`.Current CLI behavior:- `paperclipai onboard` and `paperclipai configure --section server` set deployment mode in config+- server onboarding/configure ask for reachability intent and write `server.bind`+- `paperclipai run --bind <loopback|lan|tailnet>` passes a quickstart bind preset into first-run onboarding when config is missing- runtime can override mode with `PAPERCLIP_DEPLOYMENT_MODE`-- `paperclipai run` and `paperclipai doctor` do not yet expose a direct `--mode` flag+- `paperclipai run` and `paperclipai doctor` still do not expose a direct low-level `--mode` flag-Target behavior (planned) is documented in `doc/DEPLOYMENT-MODES.md` section 5.+Canonical behavior is documented in `doc/DEPLOYMENT-MODES.md`.Allow an authenticated/private hostname (for example custom Tailscale DNS):diff --git a/doc/DEPLOYMENT-MODES.md b/doc/DEPLOYMENT-MODES.mdindex 9d58d50a74..a7b8d7fb0a 100644--- a/doc/DEPLOYMENT-MODES.md+++ b/doc/DEPLOYMENT-MODES.md@@ -17,6 +17,11 @@ Paperclip supports two runtime modes:This keeps one authenticated auth stack while still separating low-friction private-network defaults from internet-facing hardening requirements.+Paperclip now treats **bind** as a separate concern from auth:++- auth model: `local_trusted` vs `authenticated`, plus `private/public`+- reachability model: `server.bind = loopback | lan | tailnet | custom`+## 2. Canonical Model| Runtime Mode | Exposure | Human auth | Primary use |@@ -25,6 +30,15 @@ This keeps one authenticated auth stack while still separating low-friction priv| `authenticated` | `private` | Login required | Private-network access (for example Tailscale/VPN/LAN) || `authenticated` | `public` | Login required | Internet-facing/cloud deployment |+## Reachability Model++| Bind | Meaning | Typical use |+|---|---|---|+| `loopback` | Listen on localhost only | default local usage, reverse-proxy deployments |+| `lan` | Listen on all interfaces (`0.0.0.0`) | LAN/VPN/private-network access |+| `tailnet` | Listen on a detected Tailscale IP | Tailscale-only access |+| `custom` | Listen on an explicit host/IP | advanced interface-specific setups |+## 3. Security Policy## `local_trusted`@@ -38,12 +52,14 @@ This keeps one authenticated auth stack while still separating low-friction priv- login required- low-friction URL handling (`auto` base URL mode)- private-host trust policy required+- bind can be `loopback`, `lan`, `tailnet`, or `custom`## `authenticated + public`- login required- explicit public URL required- stricter deployment checks and failures in doctor+- recommended bind is `loopback` behind a reverse proxy; direct `lan/custom` is advanced## 4. Onboarding UX Contract@@ -55,14 +71,22 @@ pnpm paperclipai onboardServer prompt behavior:-1. ask mode, default `local_trusted`-2. option copy:-- `local_trusted`: "Easiest for local setup (no login, localhost-only)"-- `authenticated`: "Login required; use for private network or public hosting"-3. if `authenticated`, ask exposure:-- `private`: "Private network access (for example Tailscale), lower setup friction"-- `public`: "Internet-facing deployment, stricter security requirements"-4. ask explicit public URL only for `authenticated + public`+1. quickstart `--yes` defaults to `server.bind=loopback` and therefore `local_trusted/private`+2. advanced server setup asks reachability first:+- `Trusted local` → `bind=loopback`, `local_trusted/private`+- `Private network` → `bind=lan`, `authenticated/private`+- `Tailnet` → `bind=tailnet`, `authenticated/private`+- `Custom` → manual mode/exposure/host entry+3. raw host entry is only required for the `Custom` path+4. explicit public URL is only required for `authenticated + public`++Examples:++```sh+pnpm paperclipai onboard --yes+pnpm paperclipai onboard --yes --bind lan+pnpm paperclipai run --bind tailnet+````configure --section server` follows the same interactive behavior.diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.mdindex f7e17195a3..dd20319657 100644--- a/doc/DEVELOPING.md+++ b/doc/DEVELOPING.md@@ -55,10 +55,23 @@ pnpm dev:stopTailscale/private-auth dev mode:```sh-pnpm dev --tailscale-auth+pnpm dev --bind lan+```++This runs dev as `authenticated/private` with a private-network bind preset.++For Tailscale-only reachability on a detected tailnet address:++```sh+pnpm dev --bind tailnet```-This runs dev as `authenticated/private` and binds the server to `0.0.0.0` for private-network access.+Legacy aliases still map to the old broad private-network behavior:++```sh+pnpm dev --tailscale-auth+pnpm dev --authenticated-private+```Allow additional private hostnames (for example custom Tailscale hostnames):diff --git a/doc/OPENCLAW_ONBOARDING.md b/doc/OPENCLAW_ONBOARDING.mdindex bdb098b371..32f27ea989 100644--- a/doc/OPENCLAW_ONBOARDING.md+++ b/doc/OPENCLAW_ONBOARDING.md@@ -3,7 +3,7 @@ Use this exact checklist.1. Start Paperclip in auth mode.```bashcd <paperclip-repo-root>-pnpm dev --tailscale-auth+pnpm dev --bind lan```Then verify:```bashdiff --git a/docs/cli/setup-commands.md b/docs/cli/setup-commands.mdindex 448ab7bbc4..bb3cf17f11 100644--- a/docs/cli/setup-commands.md+++ b/docs/cli/setup-commands.md@@ -89,6 +89,8 @@ Show resolved environment configuration:pnpm paperclipai env```+This now includes bind-oriented deployment settings such as `PAPERCLIP_BIND` and `PAPERCLIP_BIND_HOST` when configured.+## `paperclipai allowed-hostname`Allow a private hostname for authenticated/private mode:diff --git a/docs/deploy/deployment-modes.md b/docs/deploy/deployment-modes.mdindex ae567f49b5..7d5e6032f6 100644--- a/docs/deploy/deployment-modes.md+++ b/docs/deploy/deployment-modes.md@@ -3,13 +3,14 @@ title: Deployment Modessummary: local_trusted vs authenticated (private/public)----Paperclip supports two runtime modes with different security profiles.+Paperclip supports two runtime modes with different security profiles. Reachability is configured separately with `bind`.## `local_trusted`The default mode. Optimized for single-operator local use.- **Host binding**: loopback only (localhost)+- **Bind**: `loopback`- **Authentication**: no login required- **Use case**: local development, solo experimentation- **Board identity**: auto-created local board user@@ -31,6 +32,7 @@ For private network access (Tailscale, VPN, LAN).- **Authentication**: login required via Better Auth- **URL handling**: auto base URL mode (lower friction)- **Host trust**: private-host trust policy required+- **Bind**: choose `loopback`, `lan`, `tailnet`, or `custom````shpnpm paperclipai onboard@@ -50,6 +52,7 @@ For internet-facing deployment.- **Authentication**: login required- **URL**: explicit public URL required- **Security**: stricter deployment checks in doctor+- **Bind**: usually `loopback` behind a reverse proxy; `lan/custom` is advanced```shpnpm paperclipai onboard@@ -81,5 +84,5 @@ pnpm paperclipai configure --section serverRuntime override via environment variable:```sh-PAPERCLIP_DEPLOYMENT_MODE=authenticated pnpm paperclipai run+PAPERCLIP_DEPLOYMENT_MODE=authenticated PAPERCLIP_BIND=lan pnpm paperclipai run```diff --git a/docs/deploy/environment-variables.md b/docs/deploy/environment-variables.mdindex bc5e4bcc13..5ebef72826 100644--- a/docs/deploy/environment-variables.md+++ b/docs/deploy/environment-variables.md@@ -10,11 +10,14 @@ All environment variables that Paperclip uses for server configuration.| Variable | Default | Description ||----------|---------|-------------|| `PORT` | `3100` | Server port |-| `HOST` | `127.0.0.1` | Server host binding |+| `PAPERCLIP_BIND` | `loopback` | Reachability preset: `loopback`, `lan`, `tailnet`, or `custom` |+| `PAPERCLIP_BIND_HOST` | (unset) | Required when `PAPERCLIP_BIND=custom` |+| `HOST` | `127.0.0.1` | Legacy host override; prefer `PAPERCLIP_BIND` for new setups || `DATABASE_URL` | (embedded) | PostgreSQL connection string || `PAPERCLIP_HOME` | `~/.paperclip` | Base directory for all Paperclip data || `PAPERCLIP_INSTANCE_ID` | `default` | Instance identifier (for multiple local instances) || `PAPERCLIP_DEPLOYMENT_MODE` | `local_trusted` | Runtime mode override |+| `PAPERCLIP_DEPLOYMENT_EXPOSURE` | `private` | Exposure policy when deployment mode is `authenticated` |## Secretsdiff --git a/docs/deploy/local-development.md b/docs/deploy/local-development.mdindex 874477c133..3bc423341e 100644--- a/docs/deploy/local-development.md+++ b/docs/deploy/local-development.md@@ -38,19 +38,26 @@ This does:2. Runs `paperclipai doctor` with repair enabled3. Starts the server when checks pass-## Tailscale/Private Auth Dev Mode+## Bind Presets In Dev-To run in `authenticated/private` mode for network access:+Default `pnpm dev` stays in `local_trusted` with loopback-only binding.++To open Paperclip to a private network with login enabled:```sh-pnpm dev --tailscale-auth+pnpm dev --bind lan```-This binds the server to `0.0.0.0` for private-network access.+For Tailscale-only binding on a detected tailnet address:++```sh+pnpm dev --bind tailnet+```-Alias:+Legacy aliases still work and map to the older broad private-network behavior:```sh+pnpm dev --tailscale-authpnpm dev --authenticated-private```diff --git a/docs/deploy/tailscale-private-access.md b/docs/deploy/tailscale-private-access.mdindex 1e0d246752..bb40fa305a 100644--- a/docs/deploy/tailscale-private-access.md+++ b/docs/deploy/tailscale-private-access.md@@ -1,6 +1,6 @@---title: Tailscale Private Access-summary: Run Paperclip with Tailscale-friendly host binding and connect from other devices+summary: Run Paperclip with Tailscale-friendly bind presets and connect from other devices---Use this when you want to access Paperclip over Tailscale (or a private LAN/VPN) instead of only `localhost`.@@ -8,20 +8,25 @@ Use this when you want to access Paperclip over Tailscale (or a private LAN/VPN)## 1. Start Paperclip in private authenticated mode```sh-pnpm dev --tailscale-auth+pnpm dev --bind tailnet```-This configures:+Recommended behavior:- `PAPERCLIP_DEPLOYMENT_MODE=authenticated`- `PAPERCLIP_DEPLOYMENT_EXPOSURE=private`-- `PAPERCLIP_AUTH_BASE_URL_MODE=auto`-- `HOST=0.0.0.0` (bind on all interfaces)+- `PAPERCLIP_BIND=tailnet`-Equivalent flag:+If you want the old broad private-network behavior instead, use:```sh+pnpm dev --bind lan+```++Legacy aliases still map to `authenticated/private + bind=lan`:+pnpm dev --authenticated-private+pnpm dev --tailscale-auth```## 2. Find your reachable Tailscale address@@ -73,5 +78,5 @@ Expected result:## Troubleshooting- Login or redirect errors on a private hostname: add it with `paperclipai allowed-hostname`.-- App only works on `localhost`: make sure you started with `--tailscale-auth` (or set `HOST=0.0.0.0` in private mode).+- App only works on `localhost`: make sure you started with `--bind lan` or `--bind tailnet` instead of plain `pnpm dev`.- Can connect locally but not remotely: verify both devices are on the same Tailscale network and port `3100` is reachable.diff --git a/packages/adapters/openclaw-gateway/doc/ONBOARDING_AND_TEST_PLAN.md b/packages/adapters/openclaw-gateway/doc/ONBOARDING_AND_TEST_PLAN.mdindex 66ff2a4aac..7382c67af7 100644--- a/packages/adapters/openclaw-gateway/doc/ONBOARDING_AND_TEST_PLAN.md+++ b/packages/adapters/openclaw-gateway/doc/ONBOARDING_AND_TEST_PLAN.md@@ -66,7 +66,7 @@ OPENCLAW_RESET_STATE=1 OPENCLAW_BUILD=1 ./scripts/smoke/openclaw-docker-ui.sh### 1) Start Paperclip```bash-pnpm dev --tailscale-auth+pnpm dev --bind lancurl -fsS http://127.0.0.1:3100/api/health```diff --git a/packages/shared/src/config-schema.ts b/packages/shared/src/config-schema.tsindex 2399ceaec2..efa1bdee1d 100644--- a/packages/shared/src/config-schema.ts+++ b/packages/shared/src/config-schema.ts@@ -1,11 +1,13 @@import { z } from "zod";import {AUTH_BASE_URL_MODES,+ BIND_MODES,DEPLOYMENT_EXPOSURES,DEPLOYMENT_MODES,SECRET_PROVIDERS,STORAGE_PROVIDERS,} from "./constants.js";+import { validateConfiguredBindMode } from "./network-bind.js";export const configMetaSchema = z.object({version: z.literal(1),@@ -46,6 +48,8 @@ export const loggingConfigSchema = z.object({export const serverConfigSchema = z.object({deploymentMode: z.enum(DEPLOYMENT_MODES).default("local_trusted"),exposure: z.enum(DEPLOYMENT_EXPOSURES).default("private"),+ bind: z.enum(BIND_MODES).optional(),+ customBindHost: z.string().optional(),host: z.string().default("127.0.0.1"),port: z.number().int().min(1).max(65535).default(3100),allowedHostnames: z.array(z.string().min(1)).default([]),@@ -132,15 +136,26 @@ export const paperclipConfigSchema = z}),}).superRefine((value, ctx) => {- if (value.server.deploymentMode === "local_trusted") {- if (value.server.exposure !== "private") {- ctx.addIssue({- code: z.ZodIssueCode.custom,- message: "server.exposure must be private when deploymentMode is local_trusted",- path: ["server", "exposure"],- });- }- return;+ if (value.server.deploymentMode === "local_trusted" && value.server.exposure !== "private") {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ message: "server.exposure must be private when deploymentMode is local_trusted",+ path: ["server", "exposure"],+ });+ }++ for (const message of validateConfiguredBindMode({+ deploymentMode: value.server.deploymentMode,+ deploymentExposure: value.server.exposure,+ bind: value.server.bind,+ host: value.server.host,+ customBindHost: value.server.customBindHost,+ })) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ message,+ path: message.includes("customBindHost") ? ["server", "customBindHost"] : ["server", "bind"],+ });}if (value.auth.baseUrlMode === "explicit" && !value.auth.publicBaseUrl) {diff --git a/packages/shared/src/constants.ts b/packages/shared/src/constants.tsindex 521ccf38ec..f62d2777a0 100644--- a/packages/shared/src/constants.ts+++ b/packages/shared/src/constants.ts@@ -7,6 +7,9 @@ export type DeploymentMode = (typeof DEPLOYMENT_MODES)[number];export const DEPLOYMENT_EXPOSURES = ["private", "public"] as const;export type DeploymentExposure = (typeof DEPLOYMENT_EXPOSURES)[number];+export const BIND_MODES = ["loopback", "lan", "tailnet", "custom"] as const;+export type BindMode = (typeof BIND_MODES)[number];+export const AUTH_BASE_URL_MODES = ["auto", "explicit"] as const;export type AuthBaseUrlMode = (typeof AUTH_BASE_URL_MODES)[number];diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.tsindex 36505ece76..8ec63026c9 100644--- a/packages/shared/src/index.ts+++ b/packages/shared/src/index.ts@@ -3,6 +3,7 @@ export {COMPANY_STATUSES,DEPLOYMENT_MODES,DEPLOYMENT_EXPOSURES,+ BIND_MODES,AUTH_BASE_URL_MODES,AGENT_STATUSES,AGENT_ADAPTER_TYPES,@@ -79,6 +80,7 @@ export {type CompanyStatus,type DeploymentMode,type DeploymentExposure,+ type BindMode,type AuthBaseUrlMode,type AgentStatus,type AgentAdapterType,@@ -149,6 +151,16 @@ export {type PluginBridgeErrorCode,} from "./constants.js";+export {+ ALL_INTERFACES_BIND_HOST,+ LOOPBACK_BIND_HOST,+ inferBindModeFromHost,+ isAllInterfacesHost,+ isLoopbackHost,+ resolveRuntimeBind,+ validateConfiguredBindMode,+} from "./network-bind.js";+export type {Company,FeedbackVote,diff --git a/packages/shared/src/network-bind.ts b/packages/shared/src/network-bind.tsnew file mode 100644index 0000000000..eeda9c5028--- /dev/null+++ b/packages/shared/src/network-bind.ts@@ -0,0 +1,105 @@+import type { BindMode, DeploymentExposure, DeploymentMode } from "./constants.js";++export const LOOPBACK_BIND_HOST = "127.0.0.1";+export const ALL_INTERFACES_BIND_HOST = "0.0.0.0";++function normalizeHost(host: string | null | undefined): string | undefined {+ const trimmed = host?.trim();+ return trimmed ? trimmed : undefined;+}++export function isLoopbackHost(host: string | null | undefined): boolean {+ const normalized = normalizeHost(host)?.toLowerCase();+ return normalized === "127.0.0.1" || normalized === "localhost" || normalized === "::1";+}++export function isAllInterfacesHost(host: string | null | undefined): boolean {+ const normalized = normalizeHost(host)?.toLowerCase();+ return normalized === "0.0.0.0" || normalized === "::";+}++export function inferBindModeFromHost(+ host: string | null | undefined,+ opts?: { tailnetBindHost?: string | null | undefined },+): BindMode {+ const normalized = normalizeHost(host);+ const tailnetBindHost = normalizeHost(opts?.tailnetBindHost);++ if (!normalized || isLoopbackHost(normalized)) return "loopback";+ if (isAllInterfacesHost(normalized)) return "lan";+ if (tailnetBindHost && normalized === tailnetBindHost) return "tailnet";+ return "custom";+}++export function validateConfiguredBindMode(input: {+ deploymentMode: DeploymentMode;+ deploymentExposure: DeploymentExposure;+ bind?: BindMode | null | undefined;+ host?: string | null | undefined;+ customBindHost?: string | null | undefined;+}): string[] {+ const bind = input.bind ?? inferBindModeFromHost(input.host);+ const customBindHost = normalizeHost(input.customBindHost);+ const errors: string[] = [];++ if (input.deploymentMode === "local_trusted" && bind !== "loopback") {+ errors.push("local_trusted requires server.bind=loopback");+ }++ if (bind === "custom" && !customBindHost) {+ const legacyHost = normalizeHost(input.host);+ if (!legacyHost || isLoopbackHost(legacyHost) || isAllInterfacesHost(legacyHost)) {+ errors.push("server.customBindHost is required when server.bind=custom");+ }+ }++ if (input.deploymentMode === "authenticated" && input.deploymentExposure === "public" && bind === "tailnet") {+ errors.push("server.bind=tailnet is only supported for authenticated/private deployments");+ }++ return errors;+}++export function resolveRuntimeBind(input: {+ bind?: BindMode | null | undefined;+ host?: string | null | undefined;+ customBindHost?: string | null | undefined;+ tailnetBindHost?: string | null | undefined;+}): {+ bind: BindMode;+ host: string;+ customBindHost?: string;+ errors: string[];+} {+ const bind = input.bind ?? inferBindModeFromHost(input.host, { tailnetBindHost: input.tailnetBindHost });+ const legacyHost = normalizeHost(input.host);+ const customBindHost =+ normalizeHost(input.customBindHost) ??+ (bind === "custom" && legacyHost && !isLoopbackHost(legacyHost) && !isAllInterfacesHost(legacyHost)+ ? legacyHost+ : undefined);++ switch (bind) {+ case "loopback":+ return { bind, host: LOOPBACK_BIND_HOST, customBindHost, errors: [] };+ case "lan":+ return { bind, host: ALL_INTERFACES_BIND_HOST, customBindHost, errors: [] };+ case "custom":+ return customBindHost+ ? { bind, host: customBindHost, customBindHost, errors: [] }+ : { bind, host: legacyHost ?? LOOPBACK_BIND_HOST, errors: ["server.customBindHost is required when server.bind=custom"] };+ case "tailnet": {+ const tailnetBindHost = normalizeHost(input.tailnetBindHost);+ return tailnetBindHost+ ? { bind, host: tailnetBindHost, customBindHost, errors: [] }+ : {+ bind,+ host: legacyHost ?? LOOPBACK_BIND_HOST,+ customBindHost,+ errors: [+ "server.bind=tailnet requires a detected Tailscale address or PAPERCLIP_TAILNET_BIND_HOST",+ ],+ };+ }+ }+}diff --git a/scripts/dev-runner.ts b/scripts/dev-runner.tsindex 756a6b921d..ba68f039f0 100644--- a/scripts/dev-runner.ts+++ b/scripts/dev-runner.ts@@ -4,6 +4,7 @@ import { existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } fimport path from "node:path";import { createInterface } from "node:readline/promises";import { stdin, stdout } from "node:process";+import { BIND_MODES, type BindMode } from "@paperclipai/shared";import { createCapturedOutputBuffer, parseJsonResponseWithLimit } from "./dev-runner-output.mjs";import { shouldTrackDevServerPath } from "./dev-runner-paths.mjs";import { createDevServiceIdentity, repoRoot } from "./dev-service-profile.ts";@@ -62,13 +63,36 @@ const tailscaleAuthFlagNames = new Set([]);let tailscaleAuth = false;+let bindMode: BindMode | null = null;+let bindHost: string | null = null;const forwardedArgs: string[] = [];-for (const arg of cliArgs) {+for (let index = 0; index < cliArgs.length; index += 1) {+ const arg = cliArgs[index];if (tailscaleAuthFlagNames.has(arg)) {tailscaleAuth = true;continue;}+ if (arg === "--bind") {+ const value = cliArgs[index + 1];+ if (!value || value.startsWith("--") || !BIND_MODES.includes(value as BindMode)) {+ console.error(`[paperclip] invalid --bind value. Use one of: ${BIND_MODES.join(", ")}`);+ process.exit(1);+ }+ bindMode = value as BindMode;+ index += 1;+ continue;+ }+ if (arg === "--bind-host") {+ const value = cliArgs[index + 1];+ if (!value || value.startsWith("--")) {+ console.error("[paperclip] --bind-host requires a value");+ process.exit(1);+ }+ bindHost = value;+ index += 1;+ continue;+ }forwardedArgs.push(arg);}@@ -78,6 +102,16 @@ if (process.env.npm_config_tailscale_auth === "true") {if (process.env.npm_config_authenticated_private === "true") {tailscaleAuth = true;}+if (!bindMode && process.env.npm_config_bind && BIND_MODES.includes(process.env.npm_config_bind as BindMode)) {+ bindMode = process.env.npm_config_bind as BindMode;+}+if (!bindHost && process.env.npm_config_bind_host) {+ bindHost = process.env.npm_config_bind_host;+}+if (bindMode === "custom" && !bindHost) {+ console.error("[paperclip] --bind custom requires --bind-host <host>");+ process.exit(1);+}const env: NodeJS.ProcessEnv = {...process.env,@@ -94,13 +128,36 @@ if (mode === "watch") {env.PAPERCLIP_MIGRATION_AUTO_APPLY ??= "true";}-if (tailscaleAuth) {- env.PAPERCLIP_DEPLOYMENT_MODE = "authenticated";- env.PAPERCLIP_DEPLOYMENT_EXPOSURE = "private";- env.PAPERCLIP_AUTH_BASE_URL_MODE = "auto";- env.HOST = "0.0.0.0";- console.log("[paperclip] dev mode: authenticated/private (tailscale-friendly) on 0.0.0.0");+if (tailscaleAuth || bindMode) {+ const effectiveBind = bindMode ?? "lan";+ if (tailscaleAuth) {+ console.log("[paperclip] note: --tailscale-auth/--authenticated-private are legacy aliases for --bind lan");+ }+ env.PAPERCLIP_BIND = effectiveBind;+ if (bindHost) {+ env.PAPERCLIP_BIND_HOST = bindHost;+ } else {+ delete env.PAPERCLIP_BIND_HOST;+ }+ if (effectiveBind === "loopback" && !tailscaleAuth) {+ delete env.PAPERCLIP_DEPLOYMENT_MODE;+ delete env.PAPERCLIP_DEPLOYMENT_EXPOSURE;+ delete env.PAPERCLIP_AUTH_BASE_URL_MODE;+ console.log("[paperclip] dev mode: local_trusted (bind=loopback)");+ } else {+ env.PAPERCLIP_DEPLOYMENT_MODE = "authenticated";+ env.PAPERCLIP_DEPLOYMENT_EXPOSURE = "private";+ env.PAPERCLIP_AUTH_BASE_URL_MODE = "auto";+ console.log(+ `[paperclip] dev mode: authenticated/private (bind=${effectiveBind}${bindHost ? `:${bindHost}` : ""})`,+ );+ }} else {+ delete env.PAPERCLIP_BIND;+ delete env.PAPERCLIP_BIND_HOST;+ delete env.PAPERCLIP_DEPLOYMENT_MODE;+ delete env.PAPERCLIP_DEPLOYMENT_EXPOSURE;+ delete env.PAPERCLIP_AUTH_BASE_URL_MODE;console.log("[paperclip] dev mode: local_trusted (default)");}@@ -108,7 +165,7 @@ const serverPort = Number.parseInt(env.PORT ?? process.env.PORT ?? "3100", 10) |const devService = createDevServiceIdentity({mode,forwardedArgs,- tailscaleAuth,+ networkProfile: tailscaleAuth ? `legacy:${bindMode ?? "lan"}` : (bindMode ?? "default"),port: serverPort,});diff --git a/scripts/dev-service-profile.ts b/scripts/dev-service-profile.tsindex 9c129b34a2..90efb322d5 100644--- a/scripts/dev-service-profile.ts+++ b/scripts/dev-service-profile.ts@@ -8,7 +8,7 @@ export const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)export function createDevServiceIdentity(input: {mode: "watch" | "dev";forwardedArgs: string[];- tailscaleAuth: boolean;+ networkProfile: string;port: number;}) {const envFingerprint = createHash("sha256")@@ -16,7 +16,7 @@ export function createDevServiceIdentity(input: {JSON.stringify({mode: input.mode,forwardedArgs: input.forwardedArgs,- tailscaleAuth: input.tailscaleAuth,+ networkProfile: input.networkProfile,port: input.port,}),)diff --git a/scripts/provision-worktree.sh b/scripts/provision-worktree.shindex 93e6a2d610..9fbd3ccc6e 100644--- a/scripts/provision-worktree.sh+++ b/scripts/provision-worktree.sh@@ -237,6 +237,8 @@ async function main() {server: {deploymentMode: sourceConfig?.server?.deploymentMode ?? "local_trusted",exposure: sourceConfig?.server?.exposure ?? "private",+ ...(sourceConfig?.server?.bind ? { bind: sourceConfig.server.bind } : {}),+ ...(sourceConfig?.server?.customBindHost ? { customBindHost: sourceConfig.server.customBindHost } : {}),host: sourceConfig?.server?.host ?? "127.0.0.1",port: serverPort,allowedHostnames: sourceConfig?.server?.allowedHostnames ?? [],diff --git a/server/src/__tests__/server-startup-feedback-export.test.ts b/server/src/__tests__/server-startup-feedback-export.test.tsindex 785656458e..056e812af3 100644--- a/server/src/__tests__/server-startup-feedback-export.test.ts+++ b/server/src/__tests__/server-startup-feedback-export.test.ts@@ -66,6 +66,8 @@ vi.mock("../config.js", () => ({loadConfig: vi.fn(() => ({deploymentMode: "authenticated",deploymentExposure: "private",+ bind: "loopback",+ customBindHost: undefined,host: "127.0.0.1",port: 3210,allowedHostnames: [],diff --git a/server/src/config.ts b/server/src/config.tsindex 5ae50400ef..9be5c21a56 100644--- a/server/src/config.ts+++ b/server/src/config.ts@@ -1,4 +1,5 @@import { readConfigFile } from "./config-file.js";+import { execFileSync } from "node:child_process";import { existsSync, realpathSync } from "node:fs";import { resolve } from "node:path";import { config as loadDotenv } from "dotenv";@@ -6,15 +7,20 @@ import { resolvePaperclipEnvPath } from "./paths.js";import { maybeRepairLegacyWorktreeConfigAndEnvFiles } from "./worktree-config.js";import {AUTH_BASE_URL_MODES,+ BIND_MODES,DEPLOYMENT_EXPOSURES,DEPLOYMENT_MODES,SECRET_PROVIDERS,STORAGE_PROVIDERS,+ type BindMode,type AuthBaseUrlMode,type DeploymentExposure,type DeploymentMode,type SecretProvider,type StorageProvider,+ inferBindModeFromHost,+ resolveRuntimeBind,+ validateConfiguredBindMode,} from "@paperclipai/shared";import {resolveDefaultBackupDir,@@ -44,6 +50,8 @@ type DatabaseMode = "embedded-postgres" | "postgres";export interface Config {deploymentMode: DeploymentMode;deploymentExposure: DeploymentExposure;+ bind: BindMode;+ customBindHost: string | undefined;host: string;port: number;allowedHostnames: string[];@@ -78,6 +86,24 @@ export interface Config {telemetryEnabled: boolean;}+function detectTailnetBindHost(): string | undefined {+ const explicit = process.env.PAPERCLIP_TAILNET_BIND_HOST?.trim();+ if (explicit) return explicit;++ try {+ const stdout = execFileSync("tailscale", ["ip", "-4"], {+ encoding: "utf8",+ stdio: ["ignore", "pipe", "ignore"],+ });+ return stdout+ .split(/\r?\n/)+ .map((line) => line.trim())+ .find(Boolean);+ } catch {+ return undefined;+ }+}+export function loadConfig(): Config {const fileConfig = readConfigFile();const fileDatabaseMode =@@ -148,6 +174,18 @@ export function loadConfig(): Config {deploymentMode === "local_trusted"? "private": (deploymentExposureFromEnv ?? fileConfig?.server.exposure ?? "private");+ const bindFromEnvRaw = process.env.PAPERCLIP_BIND;+ const bindFromEnv =+ bindFromEnvRaw && BIND_MODES.includes(bindFromEnvRaw as BindMode)+ ? (bindFromEnvRaw as BindMode)+ : null;+ const configuredHost = process.env.HOST ?? fileConfig?.server.host ?? "127.0.0.1";+ const tailnetBindHost = detectTailnetBindHost();+ const bind =+ bindFromEnv ??+ fileConfig?.server.bind ??+ inferBindModeFromHost(configuredHost, { tailnetBindHost });+ const customBindHost = process.env.PAPERCLIP_BIND_HOST ?? fileConfig?.server.customBindHost;const authBaseUrlModeFromEnvRaw = process.env.PAPERCLIP_AUTH_BASE_URL_MODE;const authBaseUrlModeFromEnv =authBaseUrlModeFromEnvRaw &&@@ -223,11 +261,32 @@ export function loadConfig(): Config {fileDatabaseBackup?.dir ??resolveDefaultBackupDir(),);+ const bindValidationErrors = validateConfiguredBindMode({+ deploymentMode,+ deploymentExposure,+ bind,+ host: configuredHost,+ customBindHost,+ });+ if (bindValidationErrors.length > 0) {+ throw new Error(bindValidationErrors[0]);+ }+ const resolvedBind = resolveRuntimeBind({+ bind,+ host: configuredHost,+ customBindHost,+ tailnetBindHost,+ });+ if (resolvedBind.errors.length > 0) {+ throw new Error(resolvedBind.errors[0]);+ }return {deploymentMode,deploymentExposure,- host: process.env.HOST ?? fileConfig?.server.host ?? "127.0.0.1",+ bind: resolvedBind.bind,+ customBindHost: resolvedBind.customBindHost,+ host: resolvedBind.host,port: Number(process.env.PORT) || fileConfig?.server.port || 3100,allowedHostnames,authBaseUrlMode,diff --git a/server/src/index.ts b/server/src/index.tsindex 7bf5cea77c..0e8db5a629 100644--- a/server/src/index.ts+++ b/server/src/index.ts@@ -701,9 +701,10 @@ export async function startServer(): Promise<StartedServer> {logger.warn({ err, url }, "Failed to open browser on startup");});}- printStartupBanner({- host: config.host,- deploymentMode: config.deploymentMode,+ printStartupBanner({+ bind: config.bind,+ host: config.host,+ deploymentMode: config.deploymentMode,deploymentExposure: config.deploymentExposure,authReady,requestedPort: config.port,diff --git a/server/src/routes/access.ts b/server/src/routes/access.tsindex a53bf0dcb2..e4893765fb 100644--- a/server/src/routes/access.ts+++ b/server/src/routes/access.ts@@ -928,7 +928,7 @@ function buildOnboardingDiscoveryDiagnostics(input: {code: "openclaw_onboarding_private_loopback_bind",level: "warn",message: "Paperclip is bound to loopback in authenticated/private mode.",- hint: "Run with a reachable bind host or use pnpm dev --tailscale-auth for private-network onboarding."+ hint: "Use a reachable private bind mode such as `pnpm dev --bind lan` or `pnpm dev --bind tailnet` for private-network onboarding."});}diff --git a/server/src/startup-banner.ts b/server/src/startup-banner.tsindex 1a52731b39..a3ae2ed1a3 100644--- a/server/src/startup-banner.ts+++ b/server/src/startup-banner.ts@@ -1,6 +1,6 @@import { existsSync, readFileSync } from "node:fs";import { resolvePaperclipConfigPath, resolvePaperclipEnvPath } from "./paths.js";-import type { DeploymentExposure, DeploymentMode } from "@paperclipai/shared";+import type { BindMode, DeploymentExposure, DeploymentMode } from "@paperclipai/shared";import { parse as parseEnvFileContents } from "dotenv";@@ -18,6 +18,7 @@ type EmbeddedPostgresInfo = {};type StartupBannerOptions = {+ bind: BindMode;host: string;deploymentMode: DeploymentMode;deploymentExposure: DeploymentExposure;@@ -148,6 +149,7 @@ export function printStartupBanner(opts: StartupBannerOptions): void {color(" ───────────────────────────────────────────────────────", "blue"),row("Mode", `${dbMode} | ${uiMode}`),row("Deploy", `${opts.deploymentMode} (${opts.deploymentExposure})`),+ row("Bind", `${opts.bind} ${color(`(${opts.host})`, "dim")}`),row("Auth", opts.authReady ? color("ready", "green") : color("not-ready", "yellow")),row("Server", portValue),row("API", `${apiUrl} ${color(`(health: ${apiUrl}/health)`, "dim")}`),