insta 0.0.62 → 0.0.64

package/README.md

@@ -121,10 +121,15 @@ only. Provider-minted service credentials (`DATABASE_URL`, `BUCKET_NAME`,
 
 ### Destructive actions can require approval
 
-Reading secrets, deploying, deleting a project or branch, and changing services are
-governed by a per-project policy. Where the policy says `approve`, the command stops and
-prints an approval id for an admin to grant with `insta approvals approve <id>`. Run
-`insta policy get` for the live policy.
+Agent requests are governed by the project's `agent-policy`; human requests use normal RBAC.
+Where the agent policy says `approve`, the command stops and prints an approval id for a human
+admin to grant with `insta approvals approve <id>`. The agent then retries the unchanged request.
+Run `insta --agent agent-policy get --json` for stored overrides, `defaultRules`, `effectiveRules`,
+`bootstrapRules` and `ruleNotes`. Rules distinguish no affected branches (`project`), unprotected
+branches and protected branches. They describe policy, not authorization: RBAC, session checks,
+actual affected resources and compound actions still apply. An empty override object does not
+mean rules are unavailable. Text output also lists effective rules. The old `policy` command and approval
+`--always` option have been removed.
 
 ### Agents get the same surface
 
@@ -213,7 +218,7 @@ build never reaches a production installer.
 | `insta metrics` · `logs` · `events` | Service metrics; runtime logs (`--deploy` for deploy events); audit timeline |
 | `insta usage` · `billing` | Usage by billing dimension; `billing upgrade` · `billing portal` |
 | `insta approvals` | `list` · `approve` · `deny` |
-| `insta policy` | `get` · `set <action> <decision>` |
+| `insta agent-policy` | `get` · `set <mode>` · `protect-branch` · `unprotect-branch` · `rule set <action> <decision>` · `revoke-sessions` |
 | `insta observe` | `install` · `uninstall` · `report` · `sync` — local credential audit |
 | `insta feedback` | Report an InstaCloud-side hurdle (bug / feature-request / friction) to the team — never for the app you are building; works logged-out |
 | `insta upgrade` · `autoupdate` | Update the CLI; show or set auto-update |

package/dist/agent.js

@@ -0,0 +1,86 @@
+import { createHash, generateKeyPairSync, randomUUID, sign } from 'node:crypto';
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { findProjectRoot, readProject } from './config.js';
+import { alreadyTracked, ensureGitignore } from './gitignore.js';
+let mode = null;
+export function detectAgent(explicit, env = process.env) {
+    const client = env.CODEX_THREAD_ID || env.CODEX_CI === '1' ? 'codex'
+        : env.CLAUDECODE === '1' ? 'claude-code'
+            : env.CURSOR_AGENT === '1' ? 'cursor' : 'unknown';
+    return explicit || client !== 'unknown' ? { source: explicit ? 'cli-explicit' : 'cli-detected', client } : null;
+}
+export function configureAgent(value) { mode = value; }
+export function agentMode() { return mode; }
+const hash = (v) => createHash('sha256').update(v).digest('hex');
+export function canonicalTarget(path) {
+    const url = new URL(path, 'https://platform.invalid');
+    return url.pathname + url.search;
+}
+const guidance = 'agent session missing, expired, or for another project/environment — run `insta setup agent`';
+export async function issueAgentSession(api, projectId) {
+    const pair = generateKeyPairSync('ed25519');
+    const client = mode?.client ?? detectAgent(false)?.client ?? 'unknown';
+    const out = await api.request('POST', '/agent/sessions', {
+        projectId, client, publicKey: pair.publicKey.export({ type: 'spki', format: 'pem' }).toString(),
+    });
+    return { ...out, client, apiUrl: api.apiUrl.replace(/\/+$/, ''), privateKey: pair.privateKey.export({ type: 'pkcs8', format: 'pem' }).toString() };
+}
+export async function saveAgentSession(session, cwd = process.cwd()) {
+    const root = await findProjectRoot(cwd) ?? cwd;
+    const rel = '.insta/agent-session.json';
+    if (alreadyTracked(root, [rel]).length)
+        throw new Error('agent-session.json is tracked by Git; untrack it before running insta setup agent');
+    ensureGitignore(root, [rel], '# Local agent credentials');
+    const dir = join(root, '.insta');
+    await mkdir(dir, { recursive: true });
+    const temp = join(dir, `.agent-session-${randomUUID()}.tmp`);
+    // Ignore crash leftovers too; temporary files contain the same private material.
+    ensureGitignore(root, ['.insta/.agent-session-*.tmp']);
+    await writeFile(temp, JSON.stringify(session, null, 2), { mode: 0o600 });
+    await rename(temp, join(root, rel));
+    await chmod(join(root, rel), 0o600);
+}
+export async function setupProjectAgentSession(api, projectId) {
+    const id = projectId ?? (await readProject())?.projectId;
+    if (!id)
+        return false;
+    await saveAgentSession(await issueAgentSession(api, id));
+    return true;
+}
+export async function loadAgentSession(apiUrl, projectId, cwd = process.cwd()) {
+    try {
+        const root = await findProjectRoot(cwd) ?? cwd;
+        const session = JSON.parse(await readFile(join(root, '.insta/agent-session.json'), 'utf8'));
+        if (session.projectId !== projectId || session.apiUrl !== apiUrl.replace(/\/+$/, '') || !session.token || !session.privateKey
+            || !Number.isFinite(Date.parse(session.expiresAt)) || Date.parse(session.expiresAt) <= Date.now())
+            throw new Error();
+        return session;
+    }
+    catch {
+        throw new Error(guidance);
+    }
+}
+export async function agentHeaders(api, method, path, rawBody) {
+    if (!mode)
+        return {};
+    if (canonicalTarget(path) === '/agent/sessions' && method === 'POST')
+        return {
+            'Insta-Actor-Type': 'agent', 'Insta-Agent-Source': mode.source, 'Insta-Agent-Client': mode.client,
+        };
+    const target = canonicalTarget(path);
+    const match = target.match(/^\/projects\/([^/?]+)/);
+    // Account reads/project creation have no project policy yet. Mint a short-lived bootstrap
+    // assertion in memory. It cannot access project routes; never downgrade to a human request.
+    const session = match ? await loadAgentSession(api.apiUrl, decodeURIComponent(match[1])) : await issueAgentSession(api);
+    const timestamp = String(Math.floor(Date.now() / 1000));
+    const nonce = randomUUID();
+    const proof = [method.toUpperCase(), target, hash(rawBody), session.agentSessionId, timestamp, nonce, mode.source, session.client].join('\n');
+    return {
+        'Insta-Actor-Type': 'agent', 'Insta-Agent-Session': session.agentSessionId,
+        'Insta-Agent-Session-Token': session.token, 'Insta-Agent-Source': mode.source,
+        'Insta-Agent-Client': session.client, 'Insta-Agent-Timestamp': timestamp,
+        'Insta-Agent-Nonce': nonce, 'Insta-Agent-Signature': sign(null, Buffer.from(proof), session.privateKey).toString('base64url'),
+    };
+}
+//# sourceMappingURL=agent.js.map

package/dist/api.js

@@ -4,6 +4,7 @@ import { readGlobal, writeGlobal, readProject, writeProject } from './config.js'
 import { autoResolveProject, promptChoice } from './resolve-project.js';
 import { die } from './util.js';
 import { USER_AGENT } from './version.js';
+import { agentHeaders, agentMode } from './agent.js';
 export class ApiError extends Error {
     status;
     body;
@@ -16,6 +17,13 @@ export class ApiError extends Error {
         this.name = 'ApiError';
     }
 }
+export class AgentApprovalRequired extends Error {
+    body;
+    constructor(body) {
+        super(body.message ?? `approval required: ${body.approvalId}`);
+        this.body = body;
+    }
+}
 // Store a durable insta_ key as the credential: set it as the bearer and drop any refresh token (an insta_ key never rotates; a stale one would leak to /auth/refresh on a 401).
 export function storeApiKeyCredential(cfg, token, user) {
     cfg.accessToken = token;
@@ -53,6 +61,8 @@ export class ApiClient {
     // Returns parsed body for status < 400 (incl. 202); throws ApiError otherwise.
     async request(method, path, body, opts = {}) {
         const res = await this.raw(method, path, body, opts.auth ?? true);
+        if (agentMode() && res.status === 202 && res.body?.status === 'approval_required')
+            throw new AgentApprovalRequired(res.body);
         if (res.status >= 400)
             throw new ApiError(res.status, res.body?.error ?? `HTTP ${res.status}`, res.body);
         return res.body;
@@ -76,6 +86,8 @@ export class ApiClient {
         const headers = { 'Content-Type': 'application/json', 'Insta-Hints': '1', 'User-Agent': USER_AGENT };
         if (auth && this.cfg.accessToken)
             headers.Authorization = `Bearer ${this.cfg.accessToken}`;
+        if (auth)
+            Object.assign(headers, await agentHeaders(this, method, path, body === undefined ? '' : JSON.stringify(body)));
         const res = await this.fetchImpl(this.apiUrl + path, {
             method,
             headers,
@@ -113,6 +125,8 @@ export async function requireProject() {
     const p = await readProject();
     if (p)
         return p;
+    if (agentMode())
+        die('agent mode requires a linked project — run `insta setup agent --project <id>`');
     // One command, just works: unlinked ≠ error. Resolve the project (auto when there's one,
     // one-keystroke picker when several) and persist the choice so this happens once per dir.
     const api = await ApiClient.load();

package/dist/commands/agent-policy.js

@@ -0,0 +1,72 @@
+import { ApiClient, requireProject } from '../api.js';
+import { handleApproval, info, printJson } from '../util.js';
+async function current() {
+    const api = await ApiClient.load();
+    const project = await requireProject();
+    const path = `/projects/${project.projectId}/agent-policy`;
+    const out = await api.request('GET', path);
+    return { api, project, path, policy: out.policy, out };
+}
+export function displayPolicy(out, opts, output = { info, printJson }) {
+    const { info, printJson } = output;
+    const { policy, agentSessionEpoch } = out;
+    if (opts.json)
+        return printJson(out);
+    info(`agent policy: ${policy.mode}\nprotected branches: ${policy.protectedBranchIds.join(', ') || '(none)'}\nsession epoch: ${agentSessionEpoch}`);
+    if (out.effectiveRules) {
+        for (const [scope, rules] of Object.entries(out.effectiveRules)) {
+            info(`\n${scope}:`);
+            for (const [action, decision] of Object.entries(rules))
+                info(`  ${action}: ${decision}`);
+        }
+        info(`\nbootstrap: project.create = ${out.bootstrapRules?.['project.create'] ?? '(not reported)'}`);
+        for (const note of out.ruleNotes ?? [])
+            info(note);
+    }
+    else
+        info('This Platform does not expose resolved rules; upgrade Platform to inspect defaults.');
+}
+export async function get(opts) {
+    const { out } = await current();
+    // Forward the public response, never the internal API client (which holds credentials).
+    displayPolicy(out, opts);
+}
+async function update(change, opts) {
+    const state = await current();
+    await change(state.policy, state);
+    const result = await state.api.rawRequest('PUT', state.path, state.policy);
+    if (handleApproval(result, opts.json))
+        return;
+    if (opts.json)
+        return printJson(result.body);
+    info(`agent policy updated: ${result.body.policy.mode}`);
+}
+export async function set(mode, opts) {
+    const normalized = mode.replace(/-/g, '_');
+    if (!['full_access', 'read_only', 'branch_developer'].includes(normalized))
+        throw new Error('mode must be full-access, read-only, or branch-developer');
+    return update(policy => { policy.mode = normalized; }, opts);
+}
+export async function protect(branch, enabled, opts) {
+    return update(async (policy, { api, project }) => {
+        const { branches } = await api.request('GET', `/projects/${project.projectId}/branches`);
+        const found = branches.find((b) => b.id === branch || b.name === branch);
+        if (!found)
+            throw new Error('branch not found');
+        policy.protectedBranchIds = enabled ? [...new Set([...policy.protectedBranchIds, found.id])] : policy.protectedBranchIds.filter((id) => id !== found.id);
+    }, opts);
+}
+export async function rule(action, decision, opts) {
+    if (!['allow', 'deny', 'approve'].includes(decision))
+        throw new Error('decision must be allow, deny, or approve');
+    return update(policy => { policy.branchDeveloperRules[action] = decision; }, opts);
+}
+export async function revoke(opts) {
+    const api = await ApiClient.load();
+    const project = await requireProject();
+    const out = await api.request('POST', `/projects/${project.projectId}/agent-sessions/revoke`);
+    if (opts.json)
+        return printJson(out);
+    info(`all project agent sessions revoked (epoch ${out.agentSessionEpoch})`);
+}
+//# sourceMappingURL=agent-policy.js.map

package/dist/commands/build.js

@@ -169,7 +169,7 @@ export async function buildReport(dirArg, opts, deps) {
             // NOT "save the generated Dockerfile here": it is not standalone (it COPYs the
             // .nixpacks/nixpkgs-<hash>.nix support files nixpacks writes beside it, which this
             // directory does not have). The detected commands above are the reusable part.
-            nextAction: `to deploy this directory, write a Dockerfile at ${userDockerfilePath} — the detected install/start commands above are the starting point; or connect the repo on GitHub to use the nixpacks lane`,
+            nextAction: `to deploy this directory, write a Dockerfile at ${userDockerfilePath} — the detected install/start commands above are the starting point; or connect the GitHub repo to the service (\`insta compute connect-repo <owner/repo>\`) to use the nixpacks lane`,
         }
         : {
             id: 'dockerfile',
@@ -226,7 +226,7 @@ export function renderReport(r, explain) {
     lines.push(`plan for ${r.dir}:`);
     // The builder line is the first thing read (and the thing an agent scrapes), so it carries the
     // lane caveat too — "builder: nixpacks" on its own reads as a promise `insta deploy <dir>` breaks.
-    const lane = r.plan.builder === 'nixpacks' ? ' — GitHub lane only; `insta deploy <dir>` needs a Dockerfile' : '';
+    const lane = r.plan.builder === 'nixpacks' ? ' — GitHub lane only (`insta compute connect-repo`); `insta deploy <dir>` needs a Dockerfile' : '';
     lines.push(`  builder: ${r.plan.builder ?? 'none'}${r.plan.providers.length ? ` (providers: ${r.plan.providers.join(', ')})` : ''}${lane}`);
     if (r.plan.installCommand)
         lines.push(`  install: ${r.plan.installCommand}`);

package/dist/commands/compute.js

@@ -429,6 +429,8 @@ function operandIndices(argv, from, to = argv.length) {
 function execCommandIndex(argv) {
     for (let cursor = 2; cursor < argv.length; cursor++) {
         const token = argv[cursor];
+        if (token === '--agent')
+            continue;
         if (token.startsWith('-'))
             return -1; // a global flag, or `--`: either way not our command path
         return token === 'compute' && argv[cursor + 1] === 'exec' ? cursor : -1;

package/dist/commands/deploy.js

@@ -15,6 +15,7 @@ export function deployRequestBody(image, branch, opts) {
         group: opts.group,
         port: opts.port ? Number(opts.port) : undefined,
         websocket: opts.websocket ? true : undefined,
+        replaceSource: opts.replaceSource ? true : undefined,
     };
 }
 // A port mismatch is the #1 deploy mistake: the app boots "successfully" but the proxy routes to
@@ -45,7 +46,7 @@ export function noDockerfileMessage(absDir) {
         'Options:',
         `  - add a Dockerfile to ${absDir} (\`insta build ${absDir}\` prints the install/start commands nixpacks detected, as a starting point)`,
         '  - deploy a prebuilt image instead: `insta deploy --image <url>`',
-        "  - connect the app's GitHub repo in the console — that lane builds Dockerfile-less repos with nixpacks server-side",
+        '  - connect the GitHub repo to the service (`insta compute connect-repo <owner/repo>`) — that lane builds Dockerfile-less repos with nixpacks server-side',
     ].join('\n');
 }
 // Deploy either a prebuilt image (`--image`) or a source directory (positional `<dir>`, built

package/dist/commands/github.js

@@ -0,0 +1,122 @@
+import { ApiClient, requireProject } from '../api.js';
+import { info, printJson } from '../util.js';
+import { resolveSoleService, parsePort, q } from './services.js';
+export function parseRepoRef(raw) {
+    const s = raw.trim().replace(/^https?:\/\//i, '').replace(/^(www\.)?github\.com\//i, '').replace(/\/+$/, '').replace(/\.git$/i, '');
+    const m = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/.exec(s);
+    if (!m)
+        throw new Error(`not a GitHub repository reference: ${raw} (use owner/repo or https://github.com/owner/repo)`);
+    return { owner: m[1], repo: m[2] };
+}
+// "", ".", "/", "./" all mean the repo root, which the platform spells null.
+function normalizeRootDir(raw) {
+    if (raw === undefined)
+        return null;
+    const s = raw.trim().replace(/^\.\//, '').replace(/^\/+/, '').replace(/\/+$/, '');
+    return s === '' || s === '.' ? null : s;
+}
+export function pickCandidate(candidates, rootDir) {
+    if (candidates.length === 0)
+        throw new Error('no deployable service detected in this repository (no Dockerfile and nothing nixpacks recognises)');
+    if (rootDir !== undefined) {
+        const want = normalizeRootDir(rootDir);
+        const hit = candidates.find((c) => c.rootDir === want);
+        if (!hit)
+            throw new Error(`no deployable directory at ${want ?? '(repo root)'} — detected: ${candidates.map((c) => c.rootDir ?? '(repo root)').join(', ')}`);
+        return hit;
+    }
+    if (candidates.length === 1)
+        return candidates[0];
+    throw new Error([
+        `this repository has ${candidates.length} deployable directories; pass --root-dir to choose which one deploys into the service:`,
+        ...candidates.map((c) => `  ${(c.rootDir ?? '(repo root)').padEnd(24)} ${c.builder}${c.startCommand ? `  start: ${c.startCommand}` : ''}`),
+    ].join('\n'));
+}
+// Build/start come from detection only: the platform's nixpacks lane fails a build whose commands differ from it.
+// autoDeploy rides along only when switched off: a public repo 400s on autoDeploy: true.
+export function sourceBody(src, c, o) {
+    const repo = src.source === 'app'
+        ? { installationId: src.installationId, repoId: src.repoId, owner: src.owner, repo: src.repo }
+        : { public: true, owner: src.owner, repo: src.repo };
+    return {
+        ...repo,
+        rootDir: c.rootDir,
+        buildCommand: c.buildCommand,
+        startCommand: c.startCommand,
+        port: o.port !== undefined ? parsePort(o.port) : c.port,
+        ...(o.repoBranch ? { branch: o.repoBranch } : {}),
+        ...(o.autoDeploy === false ? { autoDeploy: false } : {}),
+    };
+}
+export function repoLine(serviceName, s) {
+    if (s.type !== 'github')
+        return `compute ${serviceName}: no repository connected${s.image ? ` (runs image ${s.image})` : ''} — connect one with \`insta compute connect-repo <owner/repo> ${serviceName}\``;
+    const how = s.public
+        ? 'public repo, deploys are manual (pushes do not redeploy)'
+        : s.auto_deploy ? `every push to ${s.branch} redeploys it` : 'auto-deploy off (pushes do not redeploy)';
+    const where = s.root_dir ? ` (${s.root_dir}/)` : '';
+    return `compute ${serviceName}: deploys from ${s.owner}/${s.repo}@${s.branch}${where} — ${how}`;
+}
+export async function findInstalledRepo(api, orgId, ref) {
+    if (!orgId)
+        throw new Error('this directory is linked without an org — set INSTA_ORG_ID alongside INSTA_PROJECT_ID, or link it with `insta project link`');
+    const { installations = [] } = await api.request('GET', `/github/installations?orgId=${encodeURIComponent(orgId)}`);
+    if (installations.length === 0) {
+        throw new Error('no GitHub App installation for this org — connect GitHub in the console first (Add Service → GitHub Repo → Connect GitHub), or pass --public for a public repository');
+    }
+    for (const inst of installations) {
+        const { repos = [] } = await api.request('GET', `/github/installations/${encodeURIComponent(inst.installation_id)}/repos?orgId=${encodeURIComponent(orgId)}`);
+        const hit = repos.find((r) => r.owner.toLowerCase() === ref.owner.toLowerCase() && r.repo.toLowerCase() === ref.repo.toLowerCase());
+        if (hit)
+            return { installationId: Number(inst.installation_id), repoId: hit.id };
+    }
+    const accounts = installations.map((i) => i.account_login ?? i.installation_id).join(', ');
+    throw new Error(`${ref.owner}/${ref.repo} is not visible to the org's GitHub App installation (installed on: ${accounts}) — grant the App access to it in the console (Configure GitHub app), or pass --public for a public repository`);
+}
+async function targetService(api, projectId, branch, serviceName) {
+    const { services } = await api.request('GET', `/projects/${projectId}/services${q(branch)}`);
+    return resolveSoleService(services, 'compute', serviceName);
+}
+export async function computeRepo(serviceName, opts) {
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const branch = opts.branch ?? p.branch;
+    const svc = await targetService(api, p.projectId, branch, serviceName);
+    // insta-oss keys compute ids per group, not per branch, so the read carries the branch (the cloud ignores it).
+    const { source } = await api.request('GET', `/projects/${p.projectId}/services/${svc.id}/source${q(branch)}`);
+    if (opts.json)
+        return printJson({ service: { id: svc.id, name: svc.name }, source });
+    info(repoLine(svc.name, source));
+}
+export async function computeConnectRepo(rawRef, serviceName, opts) {
+    const ref = parseRepoRef(rawRef);
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const svc = await targetService(api, p.projectId, opts.branch ?? p.branch, serviceName);
+    const src = opts.public
+        ? { source: 'public', ...ref }
+        : { source: 'app', ...(await findInstalledRepo(api, p.orgId, ref)), ...ref };
+    // Detection must scan the branch that will be built: the build refuses commands that differ from what it detects there.
+    const detected = await api.request('POST', `/projects/${p.projectId}/github/detect`, { ...src, ...(opts.repoBranch ? { ref: opts.repoBranch } : {}) });
+    const candidate = pickCandidate(detected.services, opts.rootDir);
+    const res = await api.request('PUT', `/projects/${p.projectId}/services/${svc.id}/source`, sourceBody(src, candidate, opts));
+    if (opts.json)
+        return printJson({ ...res, service: { id: svc.id, name: svc.name } });
+    const branch = res.source.branch;
+    const where = candidate.rootDir ? `${candidate.rootDir}/, ${candidate.builder}` : candidate.builder;
+    const now = res.build.queued ? `building ${branch} now` : `${branch} is already live at this commit`;
+    const how = src.source === 'public' ? 'deploys are manual from here: pushes will not redeploy (public repo)'
+        : opts.autoDeploy === false ? 'auto-deploy is off: redeploy with `insta compute connect-repo` again or from the console'
+            : `every push to ${branch} redeploys it`;
+    info(`connected ${ref.owner}/${ref.repo} → compute ${svc.name} (${where}): ${now} — ${how}`);
+}
+export async function computeDisconnectRepo(serviceName, opts) {
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const svc = await targetService(api, p.projectId, opts.branch ?? p.branch, serviceName);
+    const res = await api.request('DELETE', `/projects/${p.projectId}/services/${svc.id}/source`);
+    if (opts.json)
+        return printJson({ ...res, service: { id: svc.id, name: svc.name } });
+    info(`disconnected the repository from compute ${svc.name} — it keeps running its current image; pushes no longer deploy it`);
+}
+//# sourceMappingURL=github.js.map

package/dist/commands/govern.js

@@ -28,10 +28,10 @@ export async function approvalsList(opts) {
 export async function approvalsApprove(id, opts) {
     const api = await ApiClient.load();
     const p = await requireProject();
-    const out = await api.request('POST', `/projects/${p.projectId}/approvals/${id}/approve`, { always: !!opts.always });
+    const out = await api.request('POST', `/projects/${p.projectId}/approvals/${id}/approve`, {});
     if (opts.json)
         return printJson(out);
-    info(`approved ${out.approval.action} (${id})${opts.always ? ' — policy set to allow' : ''}`);
+    info(`approved ${out.approval.action} (${id})`);
 }
 export async function approvalsDeny(id, opts = {}) {
     const api = await ApiClient.load();
@@ -41,21 +41,4 @@ export async function approvalsDeny(id, opts = {}) {
         return printJson(out);
     info(`denied ${out.approval.action} (${id})`);
 }
-export async function policyGet(opts) {
-    const api = await ApiClient.load();
-    const p = await requireProject();
-    const { policy } = await api.request('GET', `/projects/${p.projectId}/policy`);
-    if (opts.json)
-        return printJson(policy);
-    for (const [action, decision] of Object.entries(policy))
-        info(`${action}: ${decision}`);
-}
-export async function policySet(action, decision, opts = {}) {
-    const api = await ApiClient.load();
-    const p = await requireProject();
-    const out = await api.request('PUT', `/projects/${p.projectId}/policy/${action}`, { decision });
-    if (opts.json)
-        return printJson({ action, decision, ...(out ?? {}) });
-    info(`policy ${action} = ${decision}`);
-}
 //# sourceMappingURL=govern.js.map

package/dist/commands/project.js

@@ -1,4 +1,5 @@
 import { homedir } from 'node:os';
+import { agentMode, setupProjectAgentSession } from '../agent.js';
 import { ApiClient, requireProject } from '../api.js';
 import { writeProject } from '../config.js';
 import { info, die, printJson, handleApproval, renderNextActions } from '../util.js';
@@ -76,6 +77,8 @@ export async function projectCreate(name, opts) {
     const orgId = await resolveOrg(api, opts.org);
     const out = await api.request('POST', `/orgs/${orgId}/projects`, { name: resolved });
     await writeProject({ projectId: out.project.id, orgId, branch: out.defaultBranch.name });
+    if (agentMode())
+        await setupProjectAgentSession(api, out.project.id);
     if (opts.json) {
         printJson({ ...out, linked: { projectId: out.project.id, orgId, branch: out.defaultBranch.name } });
     }
@@ -101,6 +104,8 @@ export async function projectList(opts) {
 }
 export async function projectLink(id, opts = {}) {
     const api = await ApiClient.load();
+    if (agentMode())
+        await setupProjectAgentSession(api, id);
     const { project } = await api.request('GET', `/projects/${id}`);
     await writeProject({ projectId: project.id, orgId: project.org_id, branch: 'main' });
     if (opts.json)

package/dist/commands/regions.js

@@ -1,8 +1,8 @@
 import { ApiClient } from '../api.js';
 import { info, printJson } from '../util.js';
 // insta regions — list the regions a postgres/compute service can be created in.
-export async function regionsList(opts = {}) {
-    const api = await ApiClient.load();
+export async function regionsList(opts = {}, deps) {
+    const api = deps?.api ?? await ApiClient.load();
     const { regions } = await api.request('GET', '/regions');
     if (opts.json)
         return printJson(regions);

package/dist/commands/setup.js

@@ -11,6 +11,7 @@ import { join } from 'node:path';
 import os from 'node:os';
 import { createInterface } from 'node:readline';
 import { ApiClient } from '../api.js';
+import { setupProjectAgentSession } from '../agent.js';
 import { readPersistedGlobal, resolveEnv } from '../config.js';
 import { DEFAULT_ENV, ENVS, ENV_NAMES, envForApiUrl, envFromEnvVar, isEnvName, mcpServerName } from '../env.js';
 import { info, openUrl } from '../util.js';
@@ -362,7 +363,7 @@ export async function setupAgent(opts, run = defaultRunner, mint, installConfigs
     login: () => loginDevice({}, openUrl),
     stdinTty: canPromptViaTty(),
     stdoutTty: !!process.stdout.isTTY,
-}, link = projectLink, create = (n) => projectCreate(n, {})) {
+}, link = projectLink, create = (n) => projectCreate(n, {}), enroll = async () => setupProjectAgentSession(await ApiClient.load())) {
     if (!opts.yes && !process.stdout.isTTY) {
         info('non-interactive shell — assuming -y');
     }
@@ -457,6 +458,13 @@ export async function setupAgent(opts, run = defaultRunner, mint, installConfigs
             }
         }
     }
+    if (loggedIn) {
+        if (await enroll())
+            info('✓ Project agent session ready (expires in 24 hours; refresh with insta setup agent)');
+    }
+    else {
+        info('  project agent session not created — run `insta login`, then `insta setup agent`');
+    }
     // THE summary line. The restart note exists because config-file agents only read their MCP
     // config at startup; the skill files need no restart.
     const mcpOk = claude === 'new' || claude === 'existing' || others.length > 0;

package/dist/config.js

@@ -2,6 +2,7 @@
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { ensureGitignore } from './gitignore.js';
 import { DEFAULT_ENV, ENVS, envForApiUrl, envFromEnvVar, normalizeUrl } from './env.js';
 const GLOBAL_DIR = join(homedir(), '.insta');
 const GLOBAL_FILE = join(GLOBAL_DIR, 'config.json');
@@ -125,6 +126,7 @@ export async function readProject(cwd = process.cwd()) {
 export async function writeProject(c, cwd = process.cwd()) {
     const target = (await findProjectRoot(cwd)) ?? cwd;
     await mkdir(join(target, PROJECT_DIR), { recursive: true });
+    ensureGitignore(target, ['.insta/agent-session.json'], '# Local agent credentials');
     await writeFile(join(target, PROJECT_DIR, PROJECT_FILE), JSON.stringify(c, null, 2));
 }
 //# sourceMappingURL=config.js.map

package/dist/index.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
-import { ApiError } from './api.js';
+import { configureAgent, detectAgent } from './agent.js';
+import * as agentPolicy from './commands/agent-policy.js';
+import { ApiError, AgentApprovalRequired } from './api.js';
 import { CliCancel, CliExit, fail, relayedExitCode } from './util.js';
 import { trackCommand } from './telemetry.js';
 import { cliVersion } from './version.js';
@@ -20,6 +22,7 @@ import * as secretsCmd from './commands/secrets.js';
 import { deploy } from './commands/deploy.js';
 import { build } from './commands/build.js';
 import * as computeCmd from './commands/compute.js';
+import * as githubCmd from './commands/github.js';
 import * as dbCmd from './commands/db.js';
 import * as dbQueryCmd from './commands/db-query.js';
 import * as storageCmd from './commands/storage.js';
@@ -32,6 +35,14 @@ import { billing, billingUpgrade, billingPortal } from './commands/billing.js';
 import * as selfUpdate from './commands/upgrade.js';
 import * as feedbackCmd from './commands/feedback.js';
 function onError(e) {
+    if (e instanceof AgentApprovalRequired) {
+        if (process.argv.includes('--json'))
+            process.stdout.write(JSON.stringify(e.body) + '\n');
+        else
+            process.stderr.write(e.message + '\n');
+        process.exitCode = 2;
+        return;
+    }
     if (e instanceof CliExit || e instanceof CliCancel)
         return;
     if (e instanceof ApiError)
@@ -64,6 +75,8 @@ const program = new Command();
 // against the subcommand's own (identically-named) option instead.
 program.enablePositionalOptions();
 program.name('insta').description('InstaCloud CLI — manage projects, branches, secrets, deploys').version(cliVersion());
+program.option('--agent', 'run as an agent with a verified project session and project agent policy');
+program.hook('preAction', () => configureAgent(detectAgent(!!program.opts().agent)));
 // ---- auth ----
 program.command('login').description('Log in — bare: sign in from your browser (any account type); or --email <email> + password, --oauth <github|google>, --device (headless), --api-key <insta_…> (headless, durable token)')
     .option('--email <email>', 'account email (email + password login)')
@@ -197,6 +210,7 @@ program.command('build [dir]').description('Verify a source directory would buil
 program.command('deploy [dir]').description('Deploy a source directory (built remotely on Fly) 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>')
     .option('--websocket', 'run a WebSocket app (larger guest + connection-based concurrency)')
+    .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)));
 // `insta compute exec` needs the command verbatim after a literal `--`; split it out of argv here,
@@ -232,6 +246,18 @@ const execCmd = compute.command('exec [service]').description("Run a one-shot co
 // new option cannot reach the CLI surface while the split still reads it as part of the command.
 for (const [flags, description] of computeCmd.EXEC_OPTIONS)
     execCmd.option(flags, description);
+compute.command('repo [service]').description('Show what a compute service deploys from: the image it runs, or the GitHub repository — owner/repo, the branch it builds, root directory, and whether pushes redeploy it')
+    .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => githubCmd.computeRepo(service, o)));
+compute.command('connect-repo <owner/repo> [service]').description("Connect a GitHub repository to an EXISTING compute service: the repo is built (its Dockerfile, or nixpacks when there is none) and deployed into that service, and every later push to the tracked repository branch redeploys it. The repo must be reachable through the org's GitHub App installation — connect GitHub in the console first (Add Service → GitHub Repo) — or be public. Build and start commands come from detection and cannot be set. Connecting again replaces the service's current source")
+    .option('--public', 'the repo is public and no GitHub App installation is needed (deploys are manual; pushes cannot redeploy)')
+    .option('--root-dir <dir>', 'the directory of the repo to build (a monorepo with several deployable directories lists them and exits 1 without it)')
+    .option('--repo-branch <name>', "the repository branch to build (default: the repo's default branch)")
+    .option('--no-auto-deploy', 'do not rebuild on pushes; redeploy by connecting again or from the console')
+    .option('--port <n>', 'port the app listens on (default: detected)')
+    .option('--branch <branch>', 'branch (default: current) — the environment the service is on')
+    .option('--json').action(guard((ref, service, o) => githubCmd.computeConnectRepo(ref, service, o)));
+compute.command('disconnect-repo [service]').description('Disconnect the GitHub repository from a compute service. The service keeps running its current image; pushes no longer deploy it, and its build history stays')
+    .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => githubCmd.computeDisconnectRepo(service, o)));
 compute.command('volume [service]').description("Show, attach, grow, or delete a compute service's persistent /data volume. No flag: print size, mount path, and the plan cap (any plan). --size on a volumeless service ATTACHES one (any plan at the default 10Gi, the free cap; larger is paid and plan-capped; the disk mounts at /data on the next deploy); on a volume-bearing one it grows (paid plans; grow-only — a provisioned disk cannot shrink). --delete DESTROYS the disk and ALL its data immediately (no detach, no undo; billing stops now, and suspend fast-wake + scale-out return). Billing is actual data stored — the size is a cap, not a price")
     .option('--size <gi>', 'new size in whole Gi, e.g. 10 (must be ≥ the current size)')
     .option('--delete', 'destroy the volume and ALL its data (irreversible; download anything you need first)')
@@ -324,7 +350,7 @@ program.command('events').description('Show the audit + agent-event timeline').o
 // ---- approvals ----
 const ap = program.command('approvals').description('Governance approvals (HITL)');
 ap.command('list').option('--status <s>', 'pending|granted|denied|consumed').option('--json').action(guard((o) => govern.approvalsList(o)));
-ap.command('approve <id>').option('--always', 'also set the policy to allow').option('--json').action(guard((id, o) => govern.approvalsApprove(id, o)));
+ap.command('approve <id>').option('--json').action(guard((id, o) => govern.approvalsApprove(id, o)));
 ap.command('deny <id>').option('--json').action(guard((id, o) => govern.approvalsDeny(id, o)));
 // ---- observe (local credential audit) ----
 const ob = program.command('observe').description('Local credential-audit hook');
@@ -333,9 +359,16 @@ ob.command('uninstall').action(guard(() => observe.observeUninstall()));
 ob.command('report').description('Render the local credential audit').option('--json').action(guard((o) => observe.observeReport(o)));
 ob.command('sync').description('Upload findings into the project timeline').action(guard(() => observe.observeSync()));
 // ---- policy ----
-const pol = program.command('policy').description('Governance policy');
-pol.command('get').option('--json').action(guard((o) => govern.policyGet(o)));
-pol.command('set <action> <decision>').description('action: secrets.read|secrets.write|deploy|project.delete|branch.delete|service.add|service.remove|service.scale|service.upgrade|service.setAccess|storage.read|storage.write|storage.delete; decision: allow|deny|approve').option('--json').action(guard((a, d, o) => govern.policySet(a, d, o)));
+const agentPol = program.command('agent-policy').description('Project agent access policy');
+agentPol.command('get').option('--json').action(guard((o) => agentPolicy.get(o)));
+agentPol.command('set <mode>').description('full-access | read-only | branch-developer')
+    .option('--json').action(guard((mode, o) => agentPolicy.set(mode, o)));
+agentPol.command('protect-branch <branch>').option('--json').action(guard((branch, o) => agentPolicy.protect(branch, true, o)));
+agentPol.command('unprotect-branch <branch>').option('--json').action(guard((branch, o) => agentPolicy.protect(branch, false, o)));
+agentPol.command('rule').command('set <action> <decision>').description('Set an unprotected-branch rule: allow | deny | approve')
+    .option('--json').action(guard((action, decision, o) => agentPolicy.rule(action, decision, o)));
+agentPol.command('revoke-sessions').description('Revoke ALL CLI agent sessions for this project')
+    .option('--json').action(guard((o) => agentPolicy.revoke(o)));
 // ---- feedback (agent + human hurdle reports → the InstaCloud team) ----
 program.command('feedback')
     .description('Report an InstaCloud-side hurdle (bug / missing feature / friction) to the InstaCloud team — about the insta toolkit itself, NEVER about the app you are building. Works logged-out and unlinked.')

package/dist/resolve-service.js

@@ -7,8 +7,7 @@
 import * as clack from '@clack/prompts';
 import { SERVICE_TYPES, assertServiceName, parsePort } from './commands/services.js';
 import { CliCancel } from './util.js';
-// Same order, labels and default names as the dashboard's Add Service menu. Github Repo is left
-// out: the platform has no repo path yet, so a CLI entry could only say "coming soon".
+// The CLI connects repos to existing services only; "GitHub Repo" is not a service kind here.
 export const SERVICE_KINDS = [
     { id: 'image', label: 'Docker Image', type: 'compute', hint: 'run an existing container image', needsImage: true },
     { id: 'postgres', label: 'Postgres', type: 'postgres', hint: 'relational DB, usable as soon as it is added', defaultName: 'main-db' },

package/dist/telemetry.js

@@ -39,7 +39,7 @@ const SAFE_ARGS = {
     'compute always-on': { 0: ON_OFF }, 'db always-on': { 0: ON_OFF }, metrics: { 0: TARGET }, logs: { 0: TARGET },
     'template info': { 0: SLUG }, 'billing upgrade': { 0: oneOf(['pro', 'team']) },
     'approvals approve': { 0: ID }, 'approvals deny': { 0: ID },
-    'policy set': { 0: POLICY_ACTION, 1: oneOf(['allow', 'deny', 'approve']) }, autoupdate: { 0: ON_OFF },
+    'agent-policy rule set': { 0: POLICY_ACTION, 1: oneOf(['allow', 'deny', 'approve']) }, autoupdate: { 0: ON_OFF },
 };
 const SAFE_OPTIONS = {
     org: ID, project: ID, region: REGION, env: ENV, oauth: oneOf(['github', 'google']),

package/package.json

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