insta 0.1.23 → 0.1.25

package/dist/commands/cron.js

@@ -16,7 +16,7 @@
 //      forward because it can (see buildRequest).
 import { randomUUID } from 'node:crypto';
 import { ApiClient, ApiError, requireProject } from '../api.js';
-import { die, handleApproval, info, printJson, refuse } from '../util.js';
+import { die, handleApproval, info, isWebUrl, printJson, refuse } from '../util.js';
 import { q, resolveSoleService } from './services.js';
 // ---- pure, unit-tested helpers (throw plain Errors; the CLI guard turns them into clean output) ----
 // The API's own bounds (openapi/schemas/cron.ts), enforced here so junk fails before any network or
@@ -245,7 +245,7 @@ export function assertTargetFlags(o, partial = false) {
         throw new Error('--path applies to --service (an external target carries its path in the --url)');
     if (!partial && !o.url && !o.service)
         throw new Error('name a target: --url <https://…> or --service <name> [--path /api/cron]');
-    if (o.url !== undefined && !/^https?:\/\//i.test(o.url))
+    if (o.url !== undefined && !isWebUrl(o.url))
         throw new Error(`--url must be an absolute http(s) URL, got: ${o.url}`);
     if (o.path !== undefined && !o.path.startsWith('/'))
         throw new Error(`--path must start with /, got: ${o.path}`);

package/dist/commands/deploy.js

@@ -6,7 +6,7 @@ import { info, die, printJson, handleApproval, renderNextActions, CliExit } from
 import { flyctlBuildAndPush, ensureFlyctl, defaultBuildRunner, stderrBuildRunner } from '../flyctl-build.js';
 import { packDirectory, windowsModeCaveat } from '../pack.js';
 import { deployArchive, uploadArchive } from '../deploy-archive.js';
-import { parsePort } from './services.js';
+import { isV6Endpoint, parseEndpoint, parsePort } from './services.js';
 // With --json, stdout must carry exactly one JSON document (the deploy result), so every progress
 // line moves to stderr.
 const note = (opts) => (opts.json ? (m) => void process.stderr.write(m + '\n') : info);
@@ -19,9 +19,25 @@ export function deployRequestBody(source, branch, opts) {
         group: opts.group,
         port: opts.port ? Number(opts.port) : undefined,
         websocket: opts.websocket ? true : undefined,
+        endpoint: opts.endpoint !== undefined ? parseEndpoint(opts.endpoint) : undefined,
         replaceSource: opts.replaceSource ? true : undefined,
     };
 }
+// Where the deploy answers: the HTTPS URL, or for a v6-lane service (tcp, udp, tcp+udp) its
+// address, one scheme per protocol (the platform reports no URL for one). The scheme comes from the
+// RESULT's `endpoint` (instacloud-platform#681 reports it beside endpointHost, including on a
+// redeploy that passed none -- the endpoint the service kept); --endpoint is only the fallback for
+// an older platform that names the host but not the endpoint. With neither, the address prints
+// without a scheme rather than guessing tcp for what may be a udp service. Pure, so it's unit-tested.
+export function deployedTarget(r, port, flag) {
+    if (r.endpointHost) {
+        const endpoint = isV6Endpoint(r.endpoint) ? r.endpoint : isV6Endpoint(flag) ? flag : undefined;
+        if (endpoint === undefined)
+            return `${r.endpointHost}:${port ?? '?'} (endpoint unchanged; \`insta service list\` shows its protocol)`;
+        return (endpoint === 'tcp+udp' ? ['tcp', 'udp'] : [endpoint]).map((pr) => `${pr}://${r.endpointHost}:${port ?? '?'}`).join(', ');
+    }
+    return r.url || '(no URL: a worker)';
+}
 // Ask the platform which lane serves this target, so the CLI stops knowing which provider backs
 // its service. A 404 means the platform predates the contract — and because this is a GET, it
 // 404s the same way for a human and an agent, which a POST would not.
@@ -143,6 +159,19 @@ export async function deploy(dir, opts) {
         die('pick one: a source <dir> OR --image <url>, not both');
     if (!dir && !opts.image)
         die('usage: insta deploy <dir> | --image <url>  [--branch <b>] [--group <g>] [--port <n>]');
+    // Normalized here, once, so both lanes get the same validated value: the archive lane's body
+    // (deployArchive) otherwise silently drops anything that isn't exactly one of the endpoints to
+    // undefined, which let a typo like --endpoint tpc build and deploy using the service's existing
+    // endpoint instead of failing locally. Checked before ApiClient.load()/requireProject(): those
+    // can resolve a project and persist an automatic link for an unlinked directory, so a typo must
+    // die before either runs, not after.
+    let endpoint;
+    try {
+        endpoint = opts.endpoint === undefined ? undefined : parseEndpoint(opts.endpoint);
+    }
+    catch (e) {
+        die(e.message);
+    }
     const api = await ApiClient.load();
     const p = await requireProject();
     const branch = opts.branch ?? p.branch;
@@ -162,7 +191,7 @@ export async function deploy(dir, opts) {
             log(`using port ${exposed} (Dockerfile EXPOSE) — override with --port`);
         }
     }
-    const effOpts = { ...opts, port: port?.toString() };
+    const effOpts = { ...opts, port: port?.toString(), endpoint };
     const source = dir ? await prepareSource(api, p.projectId, dir, branch, effOpts) : { image: opts.image };
     if (!source)
         return; // an approval is pending; the user approves and re-runs
@@ -171,8 +200,8 @@ export async function deploy(dir, opts) {
         // nextActions, which the operation read does not carry.
         const d = source.deployed;
         if (opts.json)
-            return printJson({ image: d.image, url: d.url, branch: d.branch, group: d.group, machineId: d.machineId });
-        info(`deployed ${d.image} -> ${d.url} (branch ${d.branch}, group ${d.group})`);
+            return printJson({ image: d.image, url: d.url, ...(d.endpointHost ? { endpointHost: d.endpointHost } : {}), ...(d.endpoint ? { endpoint: d.endpoint } : {}), branch: d.branch, group: d.group, machineId: d.machineId });
+        info(`deployed ${d.image} -> ${deployedTarget(d, effOpts.port, endpoint)} (branch ${d.branch}, group ${d.group})`);
         return;
     }
     const res = await api.rawRequest('POST', `/projects/${p.projectId}/deploy`, deployRequestBody(source, branch, effOpts))
@@ -182,7 +211,7 @@ export async function deploy(dir, opts) {
     const what = source.image;
     if (opts.json)
         return printJson({ image: source.image, ...res.body });
-    info(`deployed ${what} -> ${res.body.url} (branch ${res.body.branch}, group ${res.body.group})`);
+    info(`deployed ${what} -> ${deployedTarget(res.body, effOpts.port, endpoint)} (branch ${res.body.branch}, group ${res.body.group})`);
     renderNextActions(res.body.nextActions);
 }
 // The platform refuses an image deploy onto a repo-connected service and names the body field it

package/dist/commands/postgres.js

@@ -14,9 +14,9 @@ export function alwaysOnArgs(first, second) {
 export function alwaysOnLine(group, scaleToZero) {
     return `postgres ${group}: always-on ${scaleToZero === false ? 'on — instance stays warm' : scaleToZero === true ? 'off — scales to zero when idle' : 'unknown — the provider did not report it'}`;
 }
-// Show or set a postgres service's idle mode: scale-to-zero (the default: instance suspends when
-// idle, cold-starts on the next connection) or always-on (instance stays warm; idle RAM bills at
-// actual usage). Reads GET /database/instance, sets PATCH /database/settings {scaleToZero} —
+// Show or set a postgres service's idle mode: always-on (the default for databases since platform
+// #666: instance stays warm; idle RAM bills at actual usage) or scale-to-zero (instance suspends
+// when idle, cold-starts on the next connection). Reads GET /database/instance, sets PATCH /database/settings {scaleToZero} —
 // insta-db-backed postgres only.
 export async function dbAlwaysOn(first, second, opts) {
     const { mode, service } = alwaysOnArgs(first, second);
@@ -70,7 +70,7 @@ export function alwaysOnSetLine(service, branch, mode, scaleToZero) {
     const group = service ?? 'default';
     if (scaleToZero !== (mode === 'off'))
         return `postgres ${group}: always-on ${mode} requested — the database has not applied it yet; confirm with \`insta postgres always-on${service ? ` ${service}` : ''}${branch ? ` --branch ${branch}` : ''}\``;
-    return `postgres ${group}: always-on ${mode === 'on' ? 'ENABLED — instance stays warm (no cold starts; idle RAM bills at actual usage)' : 'disabled — scales to zero when idle (default; first connection after idle cold-starts)'}`;
+    return `postgres ${group}: always-on ${mode === 'on' ? 'ENABLED — instance stays warm (no cold starts; idle RAM bills at actual usage; the default for databases)' : 'disabled — scales to zero when idle (first connection after idle cold-starts)'}`;
 }
 // Validated pass-throughs for the provider's quantity strings. The insta-db resize API takes
 // k8s-style quantities (cpu: "2", "2500m"; memory: "4Gi", "2048Mi"), so unlike the compute path
@@ -160,9 +160,20 @@ export async function dbLimits(service, opts) {
         return;
     if (opts.json)
         return printJson(res.body);
-    const cpu = typeof res.body?.cpuMilli === 'number' ? `${res.body.cpuMilli / 1000} vCPU` : (opts.cpu ?? 'unchanged');
-    const mem = typeof res.body?.memoryMib === 'number' ? fmtMib(res.body.memoryMib) : (opts.memory ?? 'unchanged');
-    info(`postgres ${service ?? 'default'}: ceiling set to ${cpu} / ${mem}`);
+    info(limitsSetLine(service, opts.branch, { cpu: body.cpu, memory: body.memory }, res));
+}
+// insta-db queues the resize and answers 202 (the platform adds pending: true) with the row from
+// BEFORE the patch, so on pending the body's cpuMilli/memoryMib are the old ceiling: print what was
+// asked for and point at the read-back, the way alwaysOnSetLine does.
+export function limitsSetLine(service, branch, requested, res) {
+    const group = service ?? 'default';
+    if (res.status === 202 || res.body?.pending === true) {
+        const asked = [requested.cpu && `${requested.cpu} vCPU`, requested.memory].filter(Boolean).join(' / ');
+        return `postgres ${group}: ceiling ${asked} requested, not applied yet — confirm with \`insta postgres limits${service ? ` ${service}` : ''}${branch ? ` --branch ${branch}` : ''}\``;
+    }
+    const cpu = typeof res.body?.cpuMilli === 'number' ? `${res.body.cpuMilli / 1000} vCPU` : (requested.cpu ?? 'unchanged');
+    const mem = typeof res.body?.memoryMib === 'number' ? fmtMib(res.body.memoryMib) : (requested.memory ?? 'unchanged');
+    return `postgres ${group}: ceiling set to ${cpu} / ${mem}`;
 }
 // Bytes → human units, one decimal above KiB. Local because the metrics payload is the only
 // bytes-denominated read in this file (fmtMib serves the MiB-denominated resize path).
@@ -204,12 +215,8 @@ export function dbStatsLines(group, body) {
     ];
 }
 // Point-in-time stats snapshot for a postgres service: connections vs the server's ceiling, cache
-// hit rate, database size. Read-only. insta-db-backed: a suspended instance answers from the
-// provider's control plane (shown as "(suspended)" with structural zeros), never dialed. That is
-// every environment today — the Neon-backed contrast below is historical: Neon is no longer used
-// anywhere, and the code that handled it is retained, not live. Neon-backed: the platform read
-// over a direct SQL connection, so a one-shot call could wake a suspended endpoint — acceptable
-// for an explicit command, which is why nothing here polls.
+// hit rate, database size. Read-only. A suspended instance answers from the provider's control
+// plane (shown as "(suspended)" with structural zeros), never dialed.
 export async function dbStats(service, opts) {
     const api = await ApiClient.load();
     const p = await requireProject();

package/dist/commands/private-network.js

@@ -0,0 +1,101 @@
+// `insta compute public-access` and `insta <redis|mysql|mongodb> public-access`: show, close or
+// re-open a compute-plane service's public access (the platform's PUT .../services/:id/access).
+//
+// Every insta-compute service has a private address in its project branch: `<name>.insta.internal`
+// for compute, `<name>-<type>.insta.internal` for a managed database (the platform's private_host;
+// this file only prints what the platform reports, never composes one). Closing public access makes
+// the service private-only: its URL answers 403 (a database's public *_URL stops connecting) and
+// only services in the same branch reach it. Like `insta postgres public-access off`, closing asks
+// first, and a non-interactive caller (agent, CI, --json) must pass --yes.
+import { ApiClient, ApiError, requireProject } from '../api.js';
+import { handleApproval, info, printJson, refuse } from '../util.js';
+import { q, resolveSoleService } from './services.js';
+import { alwaysOnArgs, confirmOnTerminal } from './postgres.js';
+const isDb = (type) => type !== 'compute';
+const credential = (type) => `${type.toUpperCase()}_URL`;
+const privateCredential = (type) => `${type.toUpperCase()}_PRIVATE_URL`;
+/** `<host>:<port>` for the private address, or undefined when the platform reports none. */
+export function privateAddress(s) {
+    return s.private_host ? `${s.private_host}${s.port ? `:${s.port}` : ''}` : undefined;
+}
+// The show block. Pure, exported for tests.
+export function publicAccessLines(s) {
+    const pub = s.public;
+    const head = `${s.type} ${s.name}: public access ${pub === false ? 'off' : pub === true ? 'on' : 'unknown'}`;
+    const why = pub === false
+        ? (isDb(s.type) ? ` — ${credential(s.type)} does not connect; apps in this branch use ${privateCredential(s.type)}` : ' — its URL answers 403; only services in this branch reach it')
+        : pub === true ? (isDb(s.type) ? '' : ' — reachable from the internet at its URL') : '';
+    const lines = [head + why];
+    const addr = privateAddress(s);
+    if (addr) {
+        lines.push(`  private: ${addr}${s.type === 'compute' ? ' (TCP and UDP, from services in this branch)' : ` (from services in this branch; ${privateCredential(s.type)} holds the connection string)`}`);
+        if (s.private_fqdn)
+            lines.push(`  fqdn:    ${s.private_fqdn} (for tools that skip the search domain, e.g. nslookup, dig)`);
+    }
+    else {
+        lines.push('  private: none yet — the platform reports no private address for this service (not yet back-filled, a worker, or a region without the private network)');
+    }
+    return lines;
+}
+// Map a refusal to a CLI-shaped message. Pure, exported for tests.
+export function publicAccessErrorMessage(e, ctx) {
+    const code = e.body?.code;
+    const b = ctx.branch ? ` --branch ${ctx.branch}` : '';
+    if (code === 'private_network_disabled')
+        return `the private network is not yet available on this deployment — ${ctx.type} ${ctx.service} stays public`;
+    if (code === 'private_network_unavailable_in_region')
+        return `the region of ${ctx.type} ${ctx.service} has no private network yet — it stays public`;
+    if (code === 'no_private_name')
+        return `${ctx.type} ${ctx.service} has no private network name, so closing public access would leave it unreachable — rename it first: \`insta service rename ${ctx.type} ${ctx.service} <new-name>${b}\``;
+    if (code === 'private_name_taken')
+        return `${e.message} — rename one of the services: \`insta service rename ${ctx.type} ${ctx.service} <new-name>${b}\``;
+    return `${ctx.what} failed (${e.status}): ${e.message}`;
+}
+// What closing will break, said before asking. Pure, exported for tests.
+export function closeWarning(s) {
+    return isDb(s.type)
+        ? `closing public access: ${credential(s.type)} (the public address) stops connecting — external clients, CI and local development can no longer reach ${s.type} ${s.name}, and apps in this branch must use ${privateCredential(s.type)} (bind it and redeploy them)`
+        : `closing public access: ${s.type} ${s.name}'s URL will answer 403 and stop waking it — browsers, webhooks and every caller outside this branch lose it; services in this branch keep reaching it at its private address`;
+}
+export async function servicePublicAccess(type, first, second, opts, deps = {}) {
+    const { mode, service } = alwaysOnArgs(first, second);
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const branch = opts.branch ?? p.branch;
+    const { services } = await api.request('GET', `/projects/${p.projectId}/services${q(branch)}`);
+    const svc = resolveSoleService(services, type, service);
+    if (!mode) {
+        if (opts.json)
+            return printJson({ name: svc.name, type: svc.type, public: svc.public ?? null, private_host: svc.private_host ?? null, private_fqdn: svc.private_fqdn ?? null, port: svc.port ?? null });
+        for (const l of publicAccessLines(svc))
+            info(l);
+        return;
+    }
+    if (mode === 'off' && !opts.yes) {
+        const tty = deps.tty ?? (!!process.stdin.isTTY && !!process.stdout.isTTY);
+        if (opts.json || !tty)
+            refuse([closeWarning(svc), `${type} ${svc.name}: re-run with --yes to confirm`]);
+        info(closeWarning(svc));
+        const ok = await (deps.confirm ?? confirmOnTerminal)(`Close public access to ${type} ${svc.name}?`);
+        if (!ok)
+            return info(`${type} ${svc.name}: public access unchanged`);
+    }
+    let res;
+    try {
+        res = await api.rawRequest('PUT', `/projects/${p.projectId}/services/${svc.id}/access`, { public: mode === 'on' });
+    }
+    catch (e) {
+        if (e instanceof ApiError)
+            throw new Error(publicAccessErrorMessage(e, { type, service: svc.name, branch: opts.branch, what: mode === 'off' ? 'closing public access' : 'opening public access' }));
+        throw e;
+    }
+    if (handleApproval(res, opts.json))
+        return;
+    if (opts.json)
+        return printJson(res.body);
+    const notice = typeof res.body?.notice === 'string' && res.body.notice ? res.body.notice : undefined;
+    info(`${type} ${svc.name}: public access ${mode === 'off' ? 'CLOSED' : 'open'}`);
+    if (notice)
+        info(`  ${notice}`);
+}
+//# sourceMappingURL=private-network.js.map

package/dist/commands/secrets.js

@@ -190,6 +190,23 @@ export function applyServiceLines(services) {
         return `  = ${s.serviceId}${s.reason ? ` (${s.reason})` : ''}`;
     });
 }
+// POST one entry to /apply and settle what `secrets set` and `secrets unset` share: the approval
+// gate, the exit code, and the --json document. Returns null when the caller has nothing left to
+// print — the platform gated the write, or --json already carried the outcome.
+async function applyEntry(d, name, branch, entry, opts) {
+    const res = await d.api.rawRequest('POST', `/projects/${d.projectId}/apply`, { branch: branch ?? d.linkedBranch, entries: [entry] });
+    if (handleApproval(res, opts.json))
+        return null;
+    const entries = res.body.entries ?? [];
+    const services = res.body.services ?? [];
+    const verdict = applyVerdict(entries, services);
+    process.exitCode = applyExitCode(verdict);
+    if (opts.json) {
+        printJson({ ok: verdict === 'ok', verdict, name, branch: branch ?? null, service: opts.service ?? null, entries, services });
+        return null;
+    }
+    return { verdict, services };
+}
 // Set a user secret. Project-wide by default; --branch scopes it to one branch. --service binds
 // it to a branch service instead, which implies the current branch (binding requires one). Value
 // comes from the argument, or stdin when omitted (keeps secret values out of shell history).
@@ -205,15 +222,10 @@ export async function secretsSet(name, value, opts, deps) {
     const branch = opts.service ? (opts.branch ?? d.linkedBranch) : opts.branch;
     // The batch always deploys on ONE branch, so the top level falls back to the linked one even when the entry itself is project-wide.
     const entry = { kind: 'set', name, value: v, ...(branch ? { branch } : {}), ...(opts.service ? { service: opts.service } : {}) };
-    const res = await d.api.rawRequest('POST', `/projects/${d.projectId}/apply`, { branch: branch ?? d.linkedBranch, entries: [entry] });
-    if (handleApproval(res, opts.json))
+    const outcome = await applyEntry(d, name, branch, entry, opts);
+    if (!outcome)
         return;
-    const entries = res.body.entries ?? [];
-    const services = res.body.services ?? [];
-    const verdict = applyVerdict(entries, services);
-    process.exitCode = applyExitCode(verdict);
-    if (opts.json)
-        return printJson({ ok: verdict === 'ok', verdict, name, branch: branch ?? null, service: opts.service ?? null, entries, services });
+    const { verdict, services } = outcome;
     info(`set ${name}${opts.service ? ` → ${opts.service}` : ''} (${branch ? `branch ${branch}` : 'project-wide'})`);
     for (const line of applyServiceLines(services))
         info(line);
@@ -232,17 +244,12 @@ export async function secretsUnset(name, opts, deps) {
     // pair without one) — so --service defaults to the linked branch, exactly as `secrets set` does.
     const branch = opts.service ? (opts.branch ?? d.linkedBranch) : opts.branch;
     const entry = { kind: 'delete', name, ...(branch ? { branch } : {}), ...(opts.service ? { service: opts.service } : {}) };
-    const res = await d.api.rawRequest('POST', `/projects/${d.projectId}/apply`, { branch: branch ?? d.linkedBranch, entries: [entry] });
-    if (handleApproval(res, opts.json))
-        return;
-    const entries = res.body.entries ?? [];
-    const services = res.body.services ?? [];
-    const verdict = applyVerdict(entries, services);
-    process.exitCode = applyExitCode(verdict);
     // The EFFECTIVE branch, not the flag: with --service and no --branch the scope that was deleted
     // is the linked branch's, and the output has to say which scope it actually touched.
-    if (opts.json)
-        return printJson({ ok: verdict === 'ok', verdict, name, branch: branch ?? null, service: opts.service ?? null, entries, services });
+    const outcome = await applyEntry(d, name, branch, entry, opts);
+    if (!outcome)
+        return;
+    const { verdict, services } = outcome;
     const scope = opts.service ? `${opts.service}, branch ${branch}` : branch ? `branch ${branch}` : 'project-wide';
     info(`unset ${name} (${scope})`);
     for (const line of applyServiceLines(services))

package/dist/commands/services.js

@@ -105,6 +105,32 @@ export function resolveComputeServiceId(services, name) {
 function defaultDatabasePort(type) {
     return type === 'mysql' ? 3306 : type === 'mongodb' ? 27017 : 6379;
 }
+export const ENDPOINTS = ['http', 'tcp', 'udp', 'tcp+udp'];
+export function parseEndpoint(raw) {
+    const v = raw.trim().toLowerCase();
+    if (!ENDPOINTS.includes(v))
+        throw new Error(`--endpoint must be http, tcp, udp or tcp+udp, got: ${raw}`);
+    return v;
+}
+// tcp, udp and tcp+udp are the same v6 lane with a different protocol set: no HTTP domain, and the
+// address is endpoint_host on the service port.
+export const isV6Endpoint = (e) => e === 'tcp' || e === 'udp' || e === 'tcp+udp';
+// Where a tcp service is dialed. The host is set once a deploy has confirmed it; before that the
+// row only knows its port.
+export function tcpAddress(s) {
+    return s.endpoint_host ? `tcp://${s.endpoint_host}:${s.port}` : `tcp/${s.port ?? '?'} (address after the first deploy)`;
+}
+// Where a v6-lane service (tcp, udp or tcp+udp) is reached, one scheme per protocol it serves:
+// tcp://host:port, udp://host:port, or both for tcp+udp. tcp is exactly tcpAddress. Before a
+// deploy has confirmed the host, the row only knows the protocol and port.
+export function v6Address(s) {
+    if (s.endpoint === 'tcp')
+        return tcpAddress(s);
+    const protos = s.endpoint === 'tcp+udp' ? ['tcp', 'udp'] : ['udp'];
+    if (!s.endpoint_host)
+        return `${s.endpoint === 'tcp+udp' ? 'tcp+udp' : 'udp'}/${s.port ?? '?'} (address after the first deploy)`;
+    return protos.map((pr) => `${pr}://${s.endpoint_host}:${s.port}`).join(', ');
+}
 // Map service-add options to the platform POST body. Pure, so it's unit-tested without a network
 // mock (mirrors deployRequestBody in deploy.ts). Validation (which options are valid for which
 // type) stays in servicesAdd, ahead of any network/config access.
@@ -112,6 +138,7 @@ export function servicesAddRequestBody(type, name, branch, opts) {
     return {
         type, name, ...(branch ? { branch } : {}), public: !!opts.public,
         ...(opts.image ? { image: opts.image } : {}), ...(opts.port !== undefined ? { port: parsePort(opts.port, { allowZero: type === 'compute' }) } : {}),
+        ...(opts.endpoint !== undefined ? { endpoint: parseEndpoint(opts.endpoint) } : {}),
         ...(opts.region ? { region: opts.region } : {}),
         // Sent whenever the flag was given, false included: the birth default is platform config
         // (INSTA_COMPUTE_ALWAYS_ON_DEFAULT, scale-to-zero unless set), so an explicit --no-always-on
@@ -135,6 +162,11 @@ export async function servicesAdd(type, name, opts = {}) {
             throw new Error('--port is only valid for compute services');
         parsePort(opts.port, { allowZero: true });
     }
+    if (opts.endpoint !== undefined) {
+        if (type !== 'compute')
+            throw new Error('--endpoint is only valid for compute services');
+        parseEndpoint(opts.endpoint);
+    }
     // Presence, not truthiness: `--no-always-on` is an explicit false and is just as compute-only.
     if (opts.alwaysOn !== undefined && type !== 'compute')
         throw new Error(alwaysOnTypeError(type));
@@ -179,7 +211,8 @@ export function serviceAddedLine(type, name, branch, svc) {
     const vol = svc.volume_gib ? `  vol ${svc.volume_gib}Gi at ${svc.volume_mount_path ?? "/data"}` : '';
     // The major belongs next to the connect hint: it decides which psql/pg_dump to reach for.
     const pg = svc.type === 'postgres' ? pgBadge(svc.pg_version) : '';
-    return `added ${type} service ${name} on ${branch ?? 'default'} (${svc.id})${access}${svc.region ? `  ${svc.region}` : ''}${img}${vol}${pg}${svc.domain ? ` — ${svc.domain}` : ''}`;
+    const where = isV6Endpoint(svc.endpoint) ? ` — ${v6Address(svc)}` : svc.domain ? ` — ${svc.domain}` : '';
+    return `added ${type} service ${name} on ${branch ?? 'default'} (${svc.id})${access}${svc.region ? `  ${svc.region}` : ''}${img}${vol}${pg}${where}`;
 }
 // `  pg <major>` for a postgres row, or '' when the platform sent nothing usable. The field arrives
 // as untyped API JSON: only a positive integer renders, so a malformed or nonsense value (true,
@@ -197,7 +230,13 @@ export function serviceListLine(s) {
                 // Postgres major, so the reader picks matching pg_dump/psql BEFORE connecting (a newer client
                 // dumps statements an older server cannot restore). Older platforms send no pg_version.
                 : s.type === 'postgres' ? pgBadge(s.pg_version) : '';
-    return `${s.type}/${s.name}  [${s.status}]${extra}${s.domain ? `  ${s.domain}` : ''}  ${s.id}`;
+    // A tcp/udp/tcp+udp compute service has no HTTP domain; its address is the v6-lane one.
+    const where = s.type === 'compute' && isV6Endpoint(s.endpoint) ? `  ${v6Address(s)}` : s.domain ? `  ${s.domain}` : '';
+    // The private address the platform reports (never composed here), and a closed compute service
+    // says so beside the URL it no longer serves.
+    const closed = s.type === 'compute' && s.public === false ? '  public off' : '';
+    const priv = s.private_host ? `  private ${s.private_host}${s.port ? `:${s.port}` : ''}` : '';
+    return `${s.type}/${s.name}  [${s.status}]${extra}${where}${closed}${priv}  ${s.id}`;
 }
 export async function servicesList(opts) {
     const api = await ApiClient.load();

package/dist/commands/template.js

@@ -129,11 +129,17 @@ export function parseSetFlags(pairs) {
     for (const pair of pairs) {
         const m = /^([A-Z][A-Z0-9_]{0,63})=([\s\S]*)$/.exec(pair);
         if (!m)
-            throw new Error(`--set expects NAME=value (NAME matching ^[A-Z][A-Z0-9_]{0,63}$), got: ${pair}`);
+            throw new Error(`--set expects NAME=value (NAME matching ^[A-Z][A-Z0-9_]{0,63}$), got: ${redactSetPair(pair)}`);
         values[m[1]] = m[2];
     }
     return values;
 }
+// --set carries secrets and this error reaches stderr and CI logs, so only the name is ever shown.
+function redactSetPair(pair) {
+    const eq = pair.indexOf('=');
+    // Nothing of a pair with no `=`: it was never split, so the whole token may be the value itself.
+    return eq >= 0 ? `${pair.slice(0, eq)}=<value hidden>` : '<value hidden: no NAME= in front of it>';
+}
 export function missingVariablesMessage(missing) {
     return [
         'missing required template variables:',
@@ -236,8 +242,13 @@ export function deploymentUrls(dep) {
     return lines;
 }
 // One line per service with its terminal state — the anatomy of a partial/failed run.
+// `skipped` is the platform saying the user deleted that service and the run stepped over it. Its
+// `state` stays `pending`, which under the marks below would read as "not reached yet" — a run that
+// is still going — so it gets its own mark and names the reason instead.
 export function serviceStateLines(dep) {
     return (dep?.services ?? []).map((s) => {
+        if (s?.skipped)
+            return `  - ${s?.name ?? 'service'} [skipped: it no longer exists, so the run stepped over it]`;
         const mark = s?.state === 'healthy' ? '✓' : s?.state === 'failed' ? '✗' : '•';
         return `  ${mark} ${s?.name ?? 'service'}${s?.url ? ` — ${s.url}` : ''}${s?.state && s.state !== 'healthy' ? ` [${s.state}]` : ''}`;
     });
@@ -247,9 +258,13 @@ export function serviceStateLines(dep) {
 // deploy, or clean up), not just that something went wrong.
 export function partialMessage(dep) {
     const services = dep?.services ?? [];
-    const healthy = services.filter((s) => s?.state === 'healthy').length;
+    // A skipped service was never part of this run — the user had deleted it — so counting it in the
+    // denominator would report a run that did everything it could as having left something behind.
+    // It is still LISTED below, because "where did it go" is the question the count then raises.
+    const ran = services.filter((s) => !s?.skipped);
+    const healthy = ran.filter((s) => s?.state === 'healthy').length;
     return [
-        `template deployment finished partial: ${healthy}/${services.length} services healthy`,
+        `template deployment finished partial: ${healthy}/${ran.length} services healthy`,
         ...serviceStateLines(dep),
         ...(dep?.error ? [`  ${dep.error}`] : []),
         ...(dep?.logsTail ? ['--- log tail ---', String(dep.logsTail).trimEnd()] : []),
@@ -421,4 +436,209 @@ export async function templateDeploy(target, opts = {}, deps = {}) {
     info('next: `insta postgres url` prints the postgres DSN; bind service credentials into compute with `insta secrets bind`; `insta secrets` refreshes user-defined secrets in .env');
     renderNextActions(dep.nextActions);
 }
+/** The review, as lines. Current is the LIVE value: what the upgrade will overwrite. */
+export function upgradePlanLines(plan) {
+    if (plan.refusals.length) {
+        return ['This upgrade cannot run:', ...plan.refusals.map((r) => `  ${r}`)];
+    }
+    const lines = [`${plan.from_version} → ${plan.to_version}`];
+    for (const s of plan.services) {
+        const who = s.service_name ?? s.key;
+        if (s.gone) {
+            lines.push(`  ${who}  no longer exists, skipped`);
+            continue;
+        }
+        // Created, not reconciled: there is no live value to compare, so its rows follow below as they come.
+        if (s.added)
+            lines.push(`  ${who}  added by ${plan.to_version}, created by this upgrade`);
+        for (const f of s.fields) {
+            const drift = f.drifted ? '  (you changed this, the upgrade will overwrite it)' : '';
+            lines.push(`  ${who}  ${f.label}  ${f.live ?? '(none)'} → ${f.next}${drift}`);
+        }
+        for (const name of s.missing_variables) {
+            lines.push(`  ${who}  ${name} is required by ${plan.to_version} and has no value, pass --set ${name}=...`);
+        }
+    }
+    for (const key of plan.removed)
+        lines.push(`  ${key}  dropped by ${plan.to_version}, left running`);
+    return lines;
+}
+// The 409 codes a user will actually hit, in a sentence that says what to do next.
+const UPGRADE_409 = {
+    template_version_changed: 'The template was republished since the plan was shown. Nothing was changed. Run the command again to review the new version.',
+};
+const ROLLBACK_409 = {
+    template_version_not_recorded: 'The earlier version of this template is no longer recorded, so it cannot be restored. Nothing was changed.',
+};
+/**
+ * Codes whose platform sentence names the deployment or the version to act on. Replacing it with
+ * wording of our own would drop the one name that makes it actionable, so the platform's sentence
+ * is printed as given and only the next step is appended.
+ */
+const KEEP_PLATFORM_SENTENCE = {
+    // "this deployment was already replaced by <code>@<version> — act on that deployment instead".
+    // Reachable here only for a service a NEWER version dropped: it keeps pointing at the deployment
+    // the instance has moved off, which is the one this CLI resolves from the service name.
+    template_superseded: 'Nothing was changed. This command addresses a service, so name one that the newer deployment carries.',
+    // "<code>@<version> was republished with different content after this instance ran it …".
+    template_version_content_changed: 'Nothing was changed.',
+    // Two causes now, and the second one names the version: "this instance was already rolled back
+    // to <version> … upgrade it to move forward", beside the original "was not upgraded from
+    // anything". Our own wording could only say one of them, and said the wrong one for a rollback.
+    template_no_step_back: 'Nothing was changed.',
+};
+/** The sentence to raise for a coded 409, or undefined when this is not one we explain. */
+function coded409(e, advice) {
+    if (!(e instanceof ApiError) || e.status !== 409)
+        return undefined;
+    const code = typeof e.body?.code === 'string' ? e.body.code : '';
+    if (advice[code])
+        return new Error(advice[code]);
+    const next = KEEP_PLATFORM_SENTENCE[code];
+    return next ? new Error(`${e.message}. ${next}`) : undefined;
+}
+async function postWithAdvice(api, path, body, advice) {
+    try {
+        return await api.rawRequest('POST', path, body);
+    }
+    catch (e) {
+        throw coded409(e, advice) ?? e;
+    }
+}
+/**
+ * A service name is what a person has; a deployment uuid is not. The services list already carries
+ * the attribution, so the lookup lives here rather than in the user's head.
+ */
+async function deploymentOfService(api, projectId, branch, service, verb) {
+    const body = await api.request('GET', `/projects/${projectId}/services?branch=${encodeURIComponent(branch)}`);
+    const row = (body.services ?? []).find((s) => s.name === service);
+    if (!row)
+        throw new Error(`no service named ${service} on branch ${branch}`);
+    // Named by the caller: the same sentence under `rollback` would send the user to upgrade instead.
+    if (!row.template_deployment_id)
+        throw new Error(`${service} was not deployed from a template, so there is nothing to ${verb}`);
+    return { deploymentId: row.template_deployment_id };
+}
+export async function templateUpgrade(service, opts = {}, deps = {}) {
+    const given = parseSetFlags(opts.set ?? []); // a typo'd --set fails before any network access
+    const api = deps.api ?? (await ApiClient.load());
+    const p = deps.project ?? (await requireProject());
+    const branchName = opts.branch ?? p.branch;
+    const ask = deps.ask ?? promptVariable;
+    const target = await deploymentOfService(api, p.projectId, branchName, service, 'upgrade');
+    // The poll and preview routes are keyed by deployment id, not project: name the project so agent
+    // mode signs with the project-bound session, exactly as templateDeploy does.
+    // The preview is a GET and raises coded 409s of its own (template_superseded among them), so it
+    // gets the same reading as the POST rather than the raw "<sentence> (HTTP 409)" the guard prints.
+    let plan;
+    try {
+        ;
+        ({ plan } = await api.request('GET', `/template-deployments/${target.deploymentId}/upgrade`, undefined, { projectId: p.projectId }));
+    }
+    catch (e) {
+        throw coded409(e, UPGRADE_409) ?? e;
+    }
+    // --json alone is "tell me" (the plan, no upgrade); --json --yes is "do it and tell me".
+    const quiet = !!opts.json;
+    if (opts.json && (!opts.yes || plan.refusals.length)) {
+        printJson(plan);
+        if (plan.refusals.length)
+            process.exitCode = 1;
+        return;
+    }
+    if (!quiet)
+        for (const line of upgradePlanLines(plan))
+            info(line);
+    // A refusal is not a prompt to confirm past: there is nothing to confirm.
+    if (plan.refusals.length) {
+        process.exitCode = 1;
+        return;
+    }
+    // Only what the new version ADDS is ever asked for: the platform recovers every value the
+    // instance already holds, so re-prompting would invite the user to overwrite a live credential.
+    const missing = plan.services.flatMap((s) => s.missing_variables.map((name) => ({ name, required: true })));
+    const tty = !opts.yes && !!process.stdin.isTTY && !!process.stdout.isTTY;
+    const variables = missing.length ? await resolveVariables(missing, given, { tty, ask }) : given;
+    if (!opts.yes && tty) {
+        const go = await clack.confirm({ message: `Upgrade ${service} from ${plan.from_version} to ${plan.to_version}?` });
+        if (clack.isCancel(go))
+            throw new CliCancel();
+        if (!go)
+            return;
+    }
+    // The version and digest the user just read. A republish in between answers 409 rather than
+    // running something they never saw.
+    const res = await postWithAdvice(api, `/projects/${p.projectId}/template-deployments/${target.deploymentId}/upgrade`, {
+        variables, expectedVersion: plan.to_version, expectedDigest: plan.to_digest,
+    }, UPGRADE_409);
+    if (handleApproval(res, opts.json))
+        return;
+    const deploymentId = res.body.deploymentId ?? (res.body.deployment ?? res.body).id;
+    if (!quiet)
+        info(`upgrading ${service} to ${plan.to_version} (${deploymentId})`);
+    const dep = await watchDeployment((id) => api.request('GET', `/template-deployments/${id}`, undefined, { projectId: p.projectId }), deploymentId, quiet ? () => { } : info, deps.wait);
+    if (quiet)
+        return printJson(dep);
+    info(`${service} is on ${plan.to_version}`);
+    info(`next: \`insta template rollback ${service}\` returns it to ${plan.from_version}`);
+    renderNextActions(dep.nextActions);
+}
+export async function templateRollback(service, opts = {}, deps = {}) {
+    const given = parseSetFlags(opts.set ?? []); // a typo'd --set fails before any network access
+    const quiet = !!opts.json;
+    const out = quiet ? () => { } : info;
+    // Destructive, and its two warnings are load-bearing: a machine-readable run must say --yes out
+    // loud rather than roll back unseen through a pipe.
+    // Same rule as `template publish`: ask on a terminal, anywhere else (a pipe, --json) say --yes.
+    const tty = !opts.json && !opts.yes && !!process.stdin.isTTY && !!process.stdout.isTTY;
+    if (!opts.yes && !tty)
+        throw new Error('rollback needs --yes without a terminal to confirm on: it does not restore data the app migrated, so nothing was rolled back');
+    const api = deps.api ?? (await ApiClient.load());
+    const p = deps.project ?? (await requireProject());
+    const branchName = opts.branch ?? p.branch;
+    const ask = deps.ask ?? promptVariable;
+    const target = await deploymentOfService(api, p.projectId, branchName, service, 'roll back');
+    // Said BEFORE the confirmation, not after the fact: rollback prints no plan, so these lines are
+    // the whole disclosure, and what they warn of is not recoverable by running the command again.
+    out('Going back restores every setting that version declares: the image, the start command, the port, always-on, public access, the volume mount path and the recorded variables.');
+    out('A setting the older version does not declare keeps its current value.');
+    out('Public access on a storage bucket reaches that bucket on every branch that has a copy, not only this one.');
+    out('It does not restore data the app migrated under the newer version, and a volume only grows.');
+    if (tty) {
+        const go = await clack.confirm({ message: `Return ${service} to the version it was upgraded from?` });
+        if (clack.isCancel(go))
+            throw new CliCancel();
+        if (!go)
+            return;
+    }
+    // The platform recovers every value the services still hold, so a rollback normally sends
+    // nothing. What it cannot recover is a variable the NEWER version stopped declaring: the upgrade
+    // deleted that value and the older manifest still requires it. Rollback prints no plan, so the
+    // platform's 400 naming them is the only place those names exist — prompt from it and retry
+    // once, exactly as templateDeploy does with its own missing_variables.
+    const rollbackPath = `/projects/${p.projectId}/template-deployments/${target.deploymentId}/rollback`;
+    const variables = { ...given };
+    let res;
+    try {
+        res = await postWithAdvice(api, rollbackPath, { variables }, ROLLBACK_409);
+    }
+    catch (e) {
+        const missing = e instanceof ApiError ? missingVariablesFrom(e.body) : null;
+        if (!missing?.length)
+            throw e;
+        // No TTY (or --yes) fails here with the `--set NAME=value` list, the same rule the deploy and
+        // upgrade paths follow — nothing has been rolled back at this point.
+        Object.assign(variables, await resolveVariables(missing, {}, { tty, ask }));
+        res = await postWithAdvice(api, rollbackPath, { variables }, ROLLBACK_409);
+    }
+    if (handleApproval(res, opts.json))
+        return;
+    const deploymentId = res.body.deploymentId ?? (res.body.deployment ?? res.body).id;
+    out(`rolling ${service} back (${deploymentId})`);
+    const dep = await watchDeployment((id) => api.request('GET', `/template-deployments/${id}`, undefined, { projectId: p.projectId }), deploymentId, out, deps.wait);
+    if (quiet)
+        return printJson(dep);
+    info(`${service} is back on ${(dep.deployment ?? dep).template_version ?? 'its previous version'}`);
+    renderNextActions(dep.nextActions);
+}
 //# sourceMappingURL=template.js.map

package/dist/commands/upgrade.js

@@ -346,8 +346,6 @@ export async function autoupdate(mode) {
     const enabled = cfg.autoUpdate !== false && !process.env.INSTA_NO_AUTOUPDATE;
     info(`autoupdate: ${enabled ? 'on' : 'off'} (default on while the CLI is pre-1.0 — \`insta config autoupdate off\` to disable)`);
 }
-// Called once at CLI start-up. Never blocks: reads the cache synchronously, prints at most one
-// stderr line, and (when due) spawns detached children for the registry check / quiet upgrade.
 /** Commands that must never nudge about an update or spawn a background one.
  *
  *  `upgrade`/`autoupdate` are the update machinery itself. Every `__` command
@@ -368,6 +366,8 @@ export function skipsUpdateCheck(cmd, sub) {
         return true;
     return cmd === 'upgrade' || cmd === 'autoupdate' || !!cmd?.startsWith('__');
 }
+// Called once at CLI start-up. Never blocks: reads the cache synchronously, prints at most one
+// stderr line, and (when due) spawns detached children for the registry check / quiet upgrade.
 export function maybeUpdate(current, argv) {
     if (skipsUpdateCheck(argv[2], argv[3]))
         return;

package/dist/deploy-archive.js

@@ -1,5 +1,6 @@
 import { setTimeout as delay } from 'node:timers/promises';
 import { handleApproval } from './util.js';
+import { ENDPOINTS, isV6Endpoint } from './commands/services.js';
 export function archiveBuildSpec(hasDockerfile) {
     return hasDockerfile ? { type: 'dockerfile' } : { type: 'nixpacks' };
 }
@@ -72,6 +73,7 @@ export async function deployArchive(api, projectId, ref, branch, opts, now = Dat
         archive: ref,
         port: opts.port ? Number(opts.port) : undefined,
         websocket: typeof opts.websocket === 'boolean' ? opts.websocket : undefined,
+        endpoint: ENDPOINTS.includes(opts.endpoint ?? '') ? opts.endpoint : undefined,
         replaceSource: opts.replaceSource === true ? true : undefined,
     });
     // An approval is a 202 too, told apart by its status word; anything else here is our operation.
@@ -121,7 +123,12 @@ export async function deployArchive(api, projectId, ref, branch, opts, now = Dat
             if (state === 'live') {
                 const image = res.body?.imageRef;
                 const url = res.body?.url;
-                if (typeof image !== 'string' || !image || typeof url !== 'string' || (!url && opts.port !== '0')) {
+                // A tcp/udp/tcp+udp (v6-lane) service has no URL: its answer is the v6 host instead. A worker has neither.
+                const endpointHost = typeof res.body?.endpointHost === 'string' && res.body.endpointHost ? res.body.endpointHost : undefined;
+                // The endpoint the service is on (instacloud-platform#681), so the address gets its scheme;
+                // an older platform omits it, and a value this CLI does not know is treated as absent.
+                const endpoint = endpointHost && isV6Endpoint(res.body?.endpoint) ? res.body.endpoint : undefined;
+                if (typeof image !== 'string' || !image || typeof url !== 'string' || (!url && opts.port !== '0' && !endpointHost)) {
                     throw new Error('the deploy finished but the platform returned no image or URL for it — check `insta status`');
                 }
                 const optionalString = (field, v) => {
@@ -132,7 +139,7 @@ export async function deployArchive(api, projectId, ref, branch, opts, now = Dat
                     return v;
                 };
                 return {
-                    image, url,
+                    image, url, ...(endpointHost ? { endpointHost } : {}), ...(endpoint ? { endpoint } : {}),
                     branch: optionalString('branch', res.body.branch) ?? branch,
                     group: optionalString('group', res.body.group) ?? opts.group ?? '',
                     machineId: optionalString('machineId', res.body.machineId),

package/dist/index.js

@@ -28,6 +28,7 @@ import { buildLogs } from './commands/build-logs.js';
 import * as computeCmd from './commands/compute.js';
 import * as githubCmd from './commands/github.js';
 import * as pgCmd from './commands/postgres.js';
+import * as privateNet from './commands/private-network.js';
 import * as dbQueryCmd from './commands/db-query.js';
 import * as managedDb from './commands/managed-db.js';
 import * as storageCmd from './commands/storage.js';
@@ -155,6 +156,7 @@ svc.command('add [type] [name]').description('Provision a service on demand (com
     .option('--public', 'storage only: serve the bucket with anonymous public-read (default private)')
     .option('--image <url>', 'compute only: run this container image at creation')
     .option('--port <n>', 'compute only: port the image listens on (default 8080; 0 for a worker without a routed port)')
+    .option('--endpoint <http|tcp|udp|tcp+udp>', 'compute only: how the service is reached — http (default: HTTPS at its domain), or tcp / udp / tcp+udp (raw TCP, UDP or both on --port at its own public IPv6 address; IPv6 clients only, no platform TLS, no custom domain). tcp needs --port and refuses commonly scanned, web (80/443) and platform-reserved ports; udp refuses amplification-prone (DNS, NTP, SNMP, memcached, …) and platform-reserved ports; tcp+udp refuses both lists. A udp datagram wakes a suspended service and what the wake held is re-sent until the service first replies (an app may see it twice); a receive-only udp service (never replies) needs --always-on to stay awake')
     .option('--always-on', 'compute only: create as always-on — never scales to zero (all plans; billing is actual usage either way). A worker (--port 0) is always-on regardless')
     .option('--no-always-on', 'compute only: create as scale-to-zero — idle machines suspend and wake on the next request (the default for new compute services; refused with --port 0, a worker cannot scale to zero)')
     .option('--mount-path <path>', 'compute only: container mount path for a new volume (requires --volume; default /data)')
@@ -364,7 +366,7 @@ function addObservability(group, component, noun) {
 // optional makes commander unable to hold that boundary itself).
 const { argv: computeArgv, command: execCommand, windowsFallback: execWindowsFallback, } = computeCmd.splitExecArgs(process.argv);
 // ---- compute ----
-const compute = program.command('compute').description('Compute services: lifecycle (start/stop/suspend/restart/status), scale, limits, volume, always-on, exec, ssh, GitHub source, logs, metrics');
+const compute = program.command('compute').description('Compute services: lifecycle (start/stop/suspend/restart/status), scale, limits, volume, public access, always-on, exec, ssh, GitHub source, logs, metrics');
 compute.command('start [service]').description('Bring a compute service online (persistent — re-enables auto-wake)')
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => computeCmd.computeStart(service, o)));
 compute.command('stop [service]').description('Take a compute service offline; traffic will NOT wake it until `start`')
@@ -383,6 +385,10 @@ compute.command('scale [count] [service]').description('Set a compute service sa
 compute.command('limits [service]').description("Show or set a compute service's resource ceiling (any plan within the free cap; raising above it needs a paid plan). --memory is the dial; cpu derives from it unless --cpu is given. Billing is actual usage — the ceiling caps what the app may burn, it is not a price")
     .option('--memory <size>', 'memory ceiling, e.g. 512mb or 1gb').option('--cpu <n>', 'vCPU ceiling override (provider sizes: 1, 2, 4, 6, 8)')
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => computeCmd.computeLimits(service, o)));
+compute.command('public-access [mode] [service]').description("Show, close or re-open a compute service's public access (mode: on|off; no mode = print it and the service's private address). Every compute service is reachable by the other services in its project branch at <name>.insta.internal:<port> (TCP and UDP); off = private-only: its URL answers 403 and no longer wakes it, so only services in the same branch reach it. Immediate, no redeploy. Asks first; --yes when there is no terminal or with --json. insta-compute only (gated: service.setAccess)")
+    .option('-y, --yes', 'close without asking (required when there is no terminal, or with --json)')
+    .option('--json').option('--branch <branch>', 'branch (default: current)')
+    .action(guard((mode, service, o) => privateNet.servicePublicAccess('compute', mode, service, o)));
 compute.command('always-on <mode> [service]').description('Set a compute service always-on (mode: on|off). on = machines never scale to zero; off = scale-to-zero (the default for new compute services; refused on a worker, port 0). All plans; billing is actual usage either way')
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((mode, service, o) => computeCmd.computeAlwaysOn(mode, service, o)));
 compute.command('ssh [service]')
@@ -449,7 +455,7 @@ pg.command('volume [service]').description("Show or grow a postgres service's pr
     .option('--size <gi>', 'new size in whole Gi, e.g. 10 (must be ≥ the current size)')
     .option('--json').option('--branch <branch>', 'branch (default: current)')
     .action(guard((service, o) => pgCmd.dbVolume(service, o)));
-pg.command('always-on [mode] [service]').description('Show or set a postgres service always-on (mode: on|off; no mode = print the current setting). on = instance stays warm, no cold starts; off = default scale-to-zero (idle instance suspends; first connection cold-starts). insta-db-backed services only')
+pg.command('always-on [mode] [service]').description('Show or set a postgres service always-on (mode: on|off; no mode = print the current setting). on = instance stays warm, no cold starts (the default for databases); off = scale-to-zero (idle instance suspends; first connection cold-starts). insta-db-backed services only')
     .option('--json').option('--branch <branch>', 'branch (default: current)')
     .action(guard((mode, service, o) => pgCmd.dbAlwaysOn(mode, service, o)));
 pg.command('private-access [mode] [service]').description('Show or set private network access (mode: on|off; no mode = print public and private access). on = mint DATABASE_PRIVATE_URL beside DATABASE_URL (unchanged) — it resolves only inside InstaCloud compute, not from a laptop or CI; bind it into a compute with `insta secrets bind … --source-name DATABASE_PRIVATE_URL`. off = retract it (refused while public access is closed). insta-db-backed only (gated: service.setAccess)')
@@ -462,7 +468,7 @@ pg.command('public-access [mode] [service]').description("Show, close or re-open
 addObservability(pg, 'db', 'postgres');
 // ---- redis / mysql / mongodb (managed databases) ----
 for (const type of ['redis', 'mysql', 'mongodb']) {
-    const g = program.command(type).description(`Managed ${type} services: query, status, resource ceiling, volume, always-on, logs, metrics`);
+    const g = program.command(type).description(`Managed ${type} services: query, status, resource ceiling, volume, public access, always-on, logs, metrics`);
     const query = g.command('query <service> [args...]').description(type === 'redis'
         ? 'Run a redis command against the service via the console exec API — a pre-tokenized argv, e.g. `GET mykey`'
         : `Run one quoted ${type} statement against the service via the console exec API`)
@@ -481,6 +487,10 @@ for (const type of ['redis', 'mysql', 'mongodb']) {
         .option('--size <gi>', 'new size in whole Gi, e.g. 10 (must be ≥ the current size)')
         .option('--json').option('--branch <branch>', 'branch (default: current)')
         .action(guard((service, o) => computeCmd.serviceVolume(type, service, o)));
+    g.command('public-access [mode] [service]').description(`Show, close or re-open a ${type} service's public access (mode: on|off; no mode = print it and the private address). On insta-compute every ${type} is reachable from services in its project branch at <name>-${type}.insta.internal (${type.toUpperCase()}_PRIVATE_URL); off = ${type.toUpperCase()}_URL stops connecting and only apps in the branch reach it, through ${type.toUpperCase()}_PRIVATE_URL. Asks first; --yes when there is no terminal or with --json (gated: service.setAccess)`)
+        .option('-y, --yes', 'close without asking (required when there is no terminal, or with --json)')
+        .option('--json').option('--branch <branch>', 'branch (default: current)')
+        .action(guard((mode, service, o) => privateNet.servicePublicAccess(type, mode, service, o)));
     g.command('always-on <mode> [service]').description(`Set a ${type} service always-on (mode: on|off). on = machines never scale to zero; off = scale-to-zero. Billing is actual usage either way`)
         .option('--json').option('--branch <branch>', 'branch (default: current)')
         .action(guard((mode, service, o) => computeCmd.serviceAlwaysOn(type, mode, service, o)));
@@ -525,6 +535,7 @@ buildCmd.command('logs <build-id>').description('Read source-build output for a
 program.command('deploy [dir]').description('Deploy a source directory (built remotely; on insta-compute a Dockerfile is optional and nixpacks detects the runtime) or a prebuilt --image to a branch compute group')
     .option('--image <url>', 'prebuilt container image to deploy (instead of a source dir)').option('--branch <b>').option('--group <g>').option('--port <p>', 'port the app listens on (0 for a worker without a routed port)')
     .option('--websocket', 'run a WebSocket app (larger guest + connection-based concurrency)')
+    .option('--endpoint <http|tcp|udp|tcp+udp>', 'switch how the service is reached from this deploy on: tcp / udp / tcp+udp (raw TCP, UDP or both on --port at its own public IPv6 address; IPv6 clients only) or http (back to its HTTPS domain). Omitted: keep the current endpoint')
     .option('--replace-source', 'the service deploys from a connected GitHub repo: switch it to this image and remove the repo connection (admin); without it such a deploy is refused')
     .option('--json', 'print the deploy result as JSON (build progress goes to stderr)')
     .action(guard((dir, o) => deploy(dir, o)));
@@ -547,6 +558,18 @@ tpl.command('deploy <code-or-dir-or-url>').description('Deploy a template onto a
     .option('-y, --yes', 'non-interactive: missing required variables fail with a --set list instead of prompting')
     .option('--json')
     .action(guard((target, o) => template.templateDeploy(target, o)));
+tpl.command('upgrade <service>').description('Move a service deployed from a template to the version the registry serves now. Shows what will change and asks before it runs. A service that already exists is reused, and every setting the new version declares is applied: image, start command, port, always-on, public access, the volume and its mount path, and the variables, each of them listed in the plan first. A service the new version ADDS is created by the upgrade: the plan names it as added and then lists every setting it will be created with, each written `(none) -> <new value>` because there is no live service to compare against, followed by the variables it requires. A service the new version no longer declares is left running, named in the plan as dropped. A volume the new version adds is attached at your plan\'s size and mounted where the manifest says; an existing one is never resized. For a storage bucket, a public-access change reaches that bucket on every branch that has a copy. Refused with a 409 when the template was republished since the plan, or when this instance has already moved off this deployment')
+    .option('--branch <b>', 'branch the service is on (default: current)')
+    .option('--set <NAME=value>', 'set a template variable the new version requires (repeatable)', (v, prev) => [...prev, v], [])
+    .option('-y, --yes', 'do not ask for confirmation')
+    .option('--json', 'machine-readable output: alone it prints the plan and does not upgrade; with --yes it upgrades and prints the finished deployment')
+    .action(guard((service, o) => template.templateUpgrade(service, o)));
+tpl.command('rollback <service>').description('Return a service to the template version it was upgraded from, one step. Restores every setting that version declares: image, start command, port, always-on, public access, the volume mount path and the recorded variables, while a setting it does not declare keeps its current value. For a storage bucket, a public-access change reaches that bucket on every branch that has a copy. It does not restore data the app migrated, and a volume only grows. Refused with a 409 when the service was never upgraded, when that version\'s manifest is no longer recorded, or when that version was republished with different content after this instance ran it')
+    .option('--branch <b>', 'branch the service is on (default: current)')
+    .option('--set <NAME=value>', "set a template variable the older version requires that the instance no longer holds — an upgrade to a version that stopped declaring it deleted the value (repeatable)", (v, prev) => [...prev, v], [])
+    .option('-y, --yes', 'do not ask for confirmation')
+    .option('--json', 'print the finished deployment as JSON and suppress progress lines; requires --yes')
+    .action(guard((service, o) => template.templateRollback(service, o)));
 // Authoring: the org's community templates, the same drafts the console editor changes.
 tpl.command('create').description("Create a community template draft from the linked project (or --project), or an empty one with --blank. Prints its code, status and the console editor link")
     .option('--project <id>', 'project to generate the draft from (default: the linked project)')

package/dist/template-manifest.js

@@ -139,7 +139,6 @@ export function validateManifest(m) {
         if (authored.spec !== undefined) {
             problems.push(`${where}: compute size is the platform's to choose — remove spec`);
         }
-        // Validate runtime fields: command and mountPath
         if (svc.command !== undefined && (typeof svc.command !== 'string' || !svc.command.trim())) {
             problems.push(`${where}.command must be a non-empty string`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "insta",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "type": "module",
   "description": "InstaCloud CLI — a thin client of the platform control-plane API.",
   "keywords": [