npm - coxpit - Versions diffs - 5.2.1 → 5.3.1 - Mend

coxpit 5.2.1 → 5.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md CHANGED Viewed

@@ -74,7 +74,8 @@ Your keys and login never touch coxpit's config or database.
 | env | default | what |
 |---|---|---|
-| `COXPIT_HOST` / `COXPIT_PORT` | `127.0.0.1` / `8210` | daemon bind |
+| `COXPIT_HOST` / `COXPIT_PORT` | `127.0.0.1` / `8210` | daemon bind. If the port is busy the daemon **auto-moves to the next free port** (see the startup log / lock file for the actual one) |
+| `COXPIT_PORT_STRICT` | — | `1` = fail instead of auto-moving when the port is busy (pin a fixed port behind a reverse proxy) |
 | `COXPIT_DB` | `~/.coxpit/coxpit.db` | SQLite (libSQL) file (a legacy `./coxpit.db` in the cwd is still honored) |
 | `COXPIT_AUTH_PASS` | — | access key (back-compat, key-only). If set on an **exposed** bind, the branded unlock page asks for this key — no username. Empty = use the stored key, or first-run setup |
 | `COXPIT_AUTH_DISABLED` | — | `1` forces auth **off** (delegate to a front gateway like Cloudflare Access / Tailscale) |
@@ -88,6 +89,8 @@ Your keys and login never touch coxpit's config or database.
 | `COXPIT_WEBHOOK_URL` | — | POSTs `{event:"run.settled",run:{...}}` when a run finishes — wire it to Telegram, Slack, anything |
 | `COXPIT_PUBLIC_URL` | — | if set, the webhook payload adds `url: <base>/?run=<id>` — tap it on your phone and the board opens that run |
+Most of these can also be changed from the in-app **Settings** view (gear, left rail) — port, bind host, access key, agent defaults and notification URLs — persisted to `~/.coxpit/settings.json`. Precedence is **explicit env > `settings.json` > default**, so anything pinned by an env var shows as locked in the UI. Port and host changes apply on the next daemon restart.
 Running on the open internet? Put it behind your own front door (Tailscale, Cloudflare Access, a reverse proxy with TLS) and keep the access key on — it exposes shells.
 ## Access key & remote access

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "coxpit",
-  "version": "5.2.1",
+  "version": "5.3.1",
   "description": "Self-hosted cockpit for running a fleet of AI coding agents across your own machines — parallel worktree runs, live board, compare & merge, web terminal, design capture.",
   "type": "module",
   "license": "MIT",

package/src/board.ts CHANGED Viewed

@@ -337,7 +337,29 @@ export const BOARD_HTML = /* html */ `<!doctype html>
   .gov-order{color:var(--muted);border-top:1px solid var(--line);padding-top:6px;margin-top:2px}
   .gov-order b{color:var(--brand)}
   /* v5.1 Documents (문서함) — grouped by run, list only, no cards */
-  #docbox .db-sub{color:var(--muted);font-size:13px;margin:0 0 14px}
+  #docbox .db-sub,#setbox .db-sub{color:var(--muted);font-size:13px;margin:0 0 14px}
+  #setbox .db-sub code{font-family:var(--mono);color:var(--brand);font-size:12px}
+  .set-list{max-width:620px;min-width:0;display:flex;flex-direction:column;gap:14px}
+  .set-sec{border:1px solid var(--line);border-radius:10px;background:var(--surface);padding:14px 16px;min-width:0}
+  .set-h{font-family:var(--mono);font-size:11px;text-transform:uppercase;letter-spacing:.12em;color:var(--faint);margin:0 0 12px}
+  .set-row{display:flex;align-items:center;gap:12px;margin-bottom:10px}
+  .set-lbl{flex:0 0 150px;font-size:13px;color:var(--muted)}
+  .set-row input:not([type=checkbox]),.set-row select{flex:1;box-sizing:border-box;max-width:100%;background:#0e1118;border:1px solid var(--line);border-radius:7px;
+    color:var(--ink);font-family:var(--mono);font-size:13px;padding:8px 10px;outline:none;min-width:0}
+  .set-row input:focus,.set-row select:focus{border-color:var(--brand)}
+  .set-row input:disabled,.set-row select:disabled,.set-check input:disabled{opacity:.4;cursor:not-allowed;background:#0b0d12}
+  .set-check input:disabled ~ span{opacity:.5}
+  .set-check{align-items:flex-start;gap:10px}
+  .set-check input[type=checkbox]{flex:0 0 auto;width:15px;height:15px;margin:2px 0 0;accent-color:var(--brand)}
+  .set-check span{flex:1;min-width:0;font-size:12.5px;color:var(--muted);line-height:1.5}
+  .set-note{font-size:11.5px;color:var(--faint);margin-top:6px}
+  .set-lock{display:block;font-family:var(--mono);font-size:10px;color:var(--s-preparing);margin-top:2px;text-transform:none;letter-spacing:0}
+  .set-state{font-size:12.5px;color:var(--ink);margin-bottom:10px}
+  .set-actions{display:flex;gap:8px;margin-top:4px}
+  .set-kv{display:flex;justify-content:space-between;gap:12px;font-family:var(--mono);font-size:12px;padding:3px 0;color:var(--muted)}
+  .set-kv b{color:var(--ink);font-weight:500;word-break:break-all;text-align:right}
+  .set-save{display:flex;align-items:center;gap:12px;margin-top:2px}
+  .set-saved{font-family:var(--mono);font-size:12px;color:var(--done)}
   .db-tools{display:flex;gap:8px;align-items:center;margin-bottom:14px;flex-wrap:wrap}
   .db-tools select,.db-tools input{background:var(--surface);border:1px solid var(--line);border-radius:7px;
     color:var(--muted);font-family:var(--mono);font-size:12px;padding:6px 10px}
@@ -835,6 +857,11 @@ export const BOARD_HTML = /* html */ `<!doctype html>
     /* 온보딩 패널이 좁은 화면을 넘치지 않게 */
     .empty{padding:24px 0}
     .setup{max-width:100%;width:100%;margin:8px 0}
+    /* Settings — 좁은 화면에선 라벨 위/인풋 아래로 스택(가로 넘침 방지) */
+    .set-row:not(.set-check){flex-direction:column;align-items:stretch;gap:6px}
+    .set-row:not(.set-check) .set-lbl{flex:auto}
+    .set-kv{flex-direction:column;gap:2px}
+    .set-kv b{text-align:left}
     .chk .v{min-width:0}
     .cmp{flex-direction:column;overflow-y:auto;overflow-x:hidden}
     .cmp-col{min-width:0;border-right:none;border-bottom:1px solid var(--line);flex:0 0 auto;max-height:72vh}
@@ -886,6 +913,9 @@ ${ICON_SPRITE}
       <button type="button" class="navi" data-view="archive">
         <svg class="ic"><use href="#i-archive"/></svg><span>Archive</span><span class="nsp"></span><span class="n" id="navArchiveN"></span>
       </button>
+      <button type="button" class="navi" data-view="settings">
+        <svg class="ic"><use href="#i-settings"/></svg><span>Settings</span>
+      </button>
     </nav>
     <div class="railsp"></div>
@@ -1027,6 +1057,10 @@ ${ICON_SPRITE}
       </div>
       <div class="db-list" id="dbList"></div>
     </div>
+    <div id="setbox" hidden>
+      <p class="db-sub">이 데몬의 설정 — 데이터 폴더의 <code>settings.json</code> 에 저장. env 로 고정된 값은 잠깁니다.</p>
+      <div class="set-list" id="setList"></div>
+    </div>
   </main>
 </div>
@@ -1639,13 +1673,17 @@ function setView(v){
   });
   const archive = v==='archive';
   const docs = v==='documents';
+  const settings = v==='settings';
+  const alt = archive||docs||settings;
   $('archive').hidden = !archive;
   $('docbox').hidden = !docs;
-  $('grid').style.display = (archive||docs) ? 'none' : '';
-  $('empty').style.display = (archive||docs) ? 'none' : ($('grid').innerHTML ? 'none' : 'flex');
-  document.querySelector('.toolbar').style.display = (archive||docs) ? 'none' : 'flex';
+  $('setbox').hidden = !settings;
+  $('grid').style.display = alt ? 'none' : '';
+  $('empty').style.display = alt ? 'none' : ($('grid').innerHTML ? 'none' : 'flex');
+  document.querySelector('.toolbar').style.display = alt ? 'none' : 'flex';
   if (archive){ paintArchRepos(); $('archRepo').value = selectedRepo!=null ? String(selectedRepo) : ''; archFetch(true); reclaimRefresh(); }
   else if (docs){ renderDocbox(); }
+  else if (settings){ renderSettings(); }
   else render();
 }
 document.querySelectorAll('#viewNav .navi').forEach(b=>b.addEventListener('click', ()=>setView(b.dataset.view)));
@@ -1712,6 +1750,109 @@ $('dbList').addEventListener('click', (e)=>{
 $('dbRepo').addEventListener('change', paintDocbox);
 $('dbType').addEventListener('change', paintDocbox);
 $('dbQ').addEventListener('input', paintDocbox);
+// ── Settings 뷰 ──────────────────────────────
+let setData = null;
+async function renderSettings(){
+  const box = $('setList');
+  box.innerHTML = '<div class="db-load">loading…</div>';
+  try { setData = await (await fetch('/api/settings')).json(); }
+  catch(e){ box.innerHTML = '<div class="db-load">failed to load settings</div>'; return; }
+  const s = setData, ef = s.effective, L = s.envLocked, au = s.auth;
+  const lockNote = (on, envVar)=> on ? '<span class="set-lock">set by '+esc(envVar)+'</span>' : '';
+  const dis = (on)=> on ? ' disabled' : '';
+  const keyState = au.mode==='env' ? 'Managed by env (COXPIT_AUTH_PASS)'
+    : L.authDisabled ? 'Disabled by env (COXPIT_AUTH_DISABLED)'
+    : au.hasKey ? 'Access key is set' + (au.exposed?'':' (loopback trusted — asked only when exposed)')
+    : au.exposed ? 'No key yet — this daemon is exposed, set one' : 'No key — loopback trusted, no sign-in needed';
+  box.innerHTML =
+    '<div class="set-sec"><div class="set-h">Daemon</div>'
+      + '<label class="set-row"><span class="set-lbl">Port '+lockNote(L.port,'COXPIT_PORT')+'</span>'
+        + '<input id="setPort" type="number" min="1" max="65535" value="'+esc(String(ef.port))+'"'+dis(L.port)+'></label>'
+      + '<label class="set-row set-check"><input id="setStrict" type="checkbox"'+(ef.portStrict?' checked':'')+dis(L.port)+'>'
+        + '<span>Fail if the port is busy (instead of auto-moving to the next free port)</span></label>'
+      + '<label class="set-row"><span class="set-lbl">Bind host '+lockNote(L.host,'COXPIT_HOST')+'</span>'
+        + '<input id="setHost" value="'+escA(ef.host)+'" placeholder="127.0.0.1"'+dis(L.host)+'></label>'
+      + '<div class="set-note">Port and host apply on the next daemon restart.</div>'
+    + '</div>'
+    + '<div class="set-sec"><div class="set-h">Access key</div>'
+      + '<div class="set-state">'+esc(keyState)+'</div>'
+      + (au.canManage
+          ? '<label class="set-row"><span class="set-lbl">'+(au.hasKey?'Change key':'Set key')+'</span>'
+              + '<input id="setKey" type="password" placeholder="at least 6 characters" autocomplete="new-password"></label>'
+            + '<div class="set-actions"><button type="button" class="btn sm" id="setKeySave">'+(au.hasKey?'Update key':'Set key')+'</button>'
+              + (au.hasKey?'<button type="button" class="btn-ghost sm" id="setKeyClear">Remove key</button>':'')+'</div>'
+          : '<div class="set-note">Unset COXPIT_AUTH_PASS / COXPIT_AUTH_DISABLED to manage the key here.</div>')
+    + '</div>'
+    + '<div class="set-sec"><div class="set-h">Agent defaults</div>'
+      + '<label class="set-row"><span class="set-lbl">Provider</span>'
+        + '<select id="setProv"><option value="claude-code"'+(ef.agent.provider==='claude-code'?' selected':'')+'>Claude</option>'
+        + '<option value="codex"'+(ef.agent.provider==='codex'?' selected':'')+'>Codex</option></select></label>'
+      + '<label class="set-row"><span class="set-lbl">Model</span>'
+        + '<input id="setModel" value="'+escA(ef.agent.model||'')+'" placeholder="CLI default"></label>'
+      + '<label class="set-row"><span class="set-lbl">Default run count</span>'
+        + '<input id="setCount" type="number" min="1" max="12" value="'+esc(String(ef.agent.count))+'"></label>'
+      + '<label class="set-row set-check"><input id="setReal" type="checkbox"'+(ef.agent.real?' checked':'')+dis(L.real)+'>'
+        + '<span>Default to Real agent (spends credits) instead of Dry run '+lockNote(L.real,'COXPIT_AGENT_REAL')+'</span></label>'
+    + '</div>'
+    + '<div class="set-sec"><div class="set-h">Notifications</div>'
+      + '<label class="set-row"><span class="set-lbl">Webhook URL '+lockNote(L.webhookUrl,'COXPIT_WEBHOOK_URL')+'</span>'
+        + '<input id="setWebhook" value="'+escA(ef.webhookUrl||'')+'" placeholder="https://… (POSTed when a run settles)"'+dis(L.webhookUrl)+'></label>'
+      + '<label class="set-row"><span class="set-lbl">Public URL '+lockNote(L.publicUrl,'COXPIT_PUBLIC_URL')+'</span>'
+        + '<input id="setPublic" value="'+escA(ef.publicUrl||'')+'" placeholder="https://… (deep-link base in notifications)"'+dis(L.publicUrl)+'></label>'
+    + '</div>'
+    + '<div class="set-sec"><div class="set-h">About</div>'
+      + '<div class="set-kv"><span>version</span><b>'+esc(s.version)+'</b></div>'
+      + '<div class="set-kv"><span>data folder</span><b>'+esc(s.dataDir)+'</b></div>'
+    + '</div>'
+    + '<div class="set-save"><button type="button" class="btn" id="setSave">Save settings</button>'
+      + '<span class="set-saved" id="setSaved"></span></div>';
+  wireSettings();
+}
+function wireSettings(){
+  const save = $('setSave'); if (!save) return;
+  save.addEventListener('click', async ()=>{
+    const L = setData.envLocked;
+    const body = { agent:{} };
+    if (!L.port){ body.port = Number($('setPort').value); body.portStrict = $('setStrict').checked; }
+    if (!L.host) body.host = $('setHost').value.trim();
+    if (!L.webhookUrl) body.webhookUrl = $('setWebhook').value.trim();
+    if (!L.publicUrl) body.publicUrl = $('setPublic').value.trim();
+    body.agent.provider = $('setProv').value;
+    body.agent.model = $('setModel').value.trim();
+    body.agent.count = Number($('setCount').value);
+    if (!L.real) body.agent.real = $('setReal').checked;
+    try {
+      const r = await fetch('/api/settings', { method:'PATCH', headers:{'content-type':'application/json'}, body: JSON.stringify(body) });
+      const j = await r.json();
+      if (!r.ok){ toast(j.error||'save failed','error'); return; }
+      $('setSaved').textContent = j.restartRequired ? 'saved — restart the daemon to apply port/host' : 'saved';
+      setTimeout(()=>{ const el=$('setSaved'); if(el) el.textContent=''; }, 5000);
+      toast('settings saved'+(j.restartRequired?' — restart to apply port/host':''), 'ok');
+    } catch(e){ toast('save failed','error'); }
+  });
+  const ks = $('setKeySave');
+  if (ks) ks.addEventListener('click', async ()=>{
+    const key = $('setKey').value;
+    if ((key||'').length < 6){ toast('key must be at least 6 characters','error'); return; }
+    try {
+      const r = await fetch('/api/settings/key', { method:'POST', headers:{'content-type':'application/json'}, body: JSON.stringify({ key }) });
+      const j = await r.json();
+      if (!r.ok){ toast(j.error||'failed','error'); return; }
+      toast('access key set','ok'); renderSettings();
+    } catch(e){ toast('failed','error'); }
+  });
+  const kc = $('setKeyClear');
+  if (kc) kc.addEventListener('click', async ()=>{
+    if (!(await confirmUI('Remove the access key?', { sub:'On a loopback bind this means no sign-in. On an exposed bind the daemon returns to first-run setup.', okLabel:'Remove key' }))) return;
+    try {
+      const r = await fetch('/api/settings/key', { method:'DELETE' });
+      const j = await r.json();
+      if (!r.ok){ toast(j.error||'failed','error'); return; }
+      toast('access key removed','ok'); renderSettings();
+    } catch(e){ toast('failed','error'); }
+  });
+}
 // 뷰 nav 카운트 — Active=스코프 run 수, Goals=스코프 그룹 수, Archive=닫힌 태스크 수(hydrate)
 function paintNavCounts(){
   const scoped = [...runs.values()].filter(runInScope);

package/src/config.ts CHANGED Viewed

@@ -41,6 +41,24 @@ function defaultDbPath(): string {
 }
 const dbPath = process.env.COXPIT_DB || defaultDbPath();
+const settingsPath = path.join(path.dirname(path.resolve(dbPath)), 'settings.json');
+// 영속 설정(settings.json)을 인라인으로 읽는다(순환 import 회피 — settings.ts 는 config 를 import).
+// 병합 우선순위: 명시 env > settings.json > 기본값.
+interface StoredSettings {
+  port?: number; portStrict?: boolean; host?: string; webhookUrl?: string; publicUrl?: string;
+  agent?: { provider?: string; model?: string; count?: number; real?: boolean };
+}
+const stored: StoredSettings = (() => {
+  try {
+    const raw = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    return raw && typeof raw === 'object' ? raw : {};
+  } catch { return {}; }
+})();
+const env = process.env;
+const num = (v: unknown): number | undefined => {
+  const n = Number(v); return Number.isFinite(n) ? n : undefined;
+};
 // 버전 SSOT = package.json (하드코딩 문자열 이중화 방지)
 const pkgVersion: string = (() => {
@@ -56,24 +74,42 @@ export const config = {
   version: pkgVersion,
   // UTF-8 보장된 로케일 — PTY/원격 셸에 명시 전달용
   lang: process.env.LANG!,
-  host: process.env.COXPIT_HOST ?? '127.0.0.1',
-  port: Number(process.env.COXPIT_PORT ?? 8210),
+  host: env.COXPIT_HOST ?? stored.host ?? '127.0.0.1',
+  // 선호 포트(env > settings > 8210). 점유 시 index.ts 가 자동 이동(portStrict 면 실패).
+  port: num(env.COXPIT_PORT) ?? stored.port ?? 8210,
+  // 포트 점유 시 자동 이동 대신 실패(리버스 프록시 등 고정 포트가 필수인 경우).
+  portStrict: env.COXPIT_PORT_STRICT === '1' || (env.COXPIT_PORT_STRICT == null && stored.portStrict === true),
   dbPath,
+  settingsPath,
   // 단일 데몬 락 파일 — DB 와 같은 폴더(그 DB 를 지키는 락이므로)
   lockPath: path.join(path.dirname(path.resolve(dbPath)), 'daemon.lock.json'),
   // 원격 머신 SSH 개인키 경로(선택). 없으면 ssh 기본 키/에이전트 사용.
   sshKey: process.env.COXPIT_SSH_KEY ?? '',
   // run 정착 시 POST 할 웹훅(선택) — 텔레그램 브릿지 등 사용자 연결용.
-  webhookUrl: process.env.COXPIT_WEBHOOK_URL ?? '',
+  webhookUrl: env.COXPIT_WEBHOOK_URL ?? stored.webhookUrl ?? '',
   // 웹훅 payload 의 딥링크 base(선택) — 설정 시 url: <base>/?run=<id> 포함 (폰에서 탭 → 그 run)
-  publicUrl: (process.env.COXPIT_PUBLIC_URL ?? '').replace(/\/+$/, ''),
+  publicUrl: (env.COXPIT_PUBLIC_URL ?? stored.publicUrl ?? '').replace(/\/+$/, ''),
   agent: {
     // 기본 드라이런(모의 에이전트). 실제 CLI 실행은 켤 때만(크레딧 소모).
-    real: process.env.COXPIT_AGENT_REAL === '1',
+    real: env.COXPIT_AGENT_REAL != null ? env.COXPIT_AGENT_REAL === '1' : (stored.agent?.real ?? false),
     bin: process.env.COXPIT_AGENT_BIN ?? 'claude',
     // 격리 worktree에서 헤드리스 실행 권한: acceptEdits(파일편집 자동허용) 기본.
     // 완전 자율은 bypassPermissions.
     perm: process.env.COXPIT_AGENT_PERM ?? 'acceptEdits',
+    // 보드 기본값(런처 초기 상태) — settings 로만, run 발사 시 클라이언트가 실제 값 전달.
+    provider: stored.agent?.provider ?? 'claude-code',
+    model: stored.agent?.model ?? '',
+    count: stored.agent?.count ?? 1,
+  },
+  // 어떤 값이 env 로 고정됐는가 — Settings UI 가 잠금 표시(파일로 못 바꿈).
+  envLocked: {
+    port: env.COXPIT_PORT != null,
+    host: env.COXPIT_HOST != null,
+    webhookUrl: env.COXPIT_WEBHOOK_URL != null,
+    publicUrl: env.COXPIT_PUBLIC_URL != null,
+    real: env.COXPIT_AGENT_REAL != null,
+    authDisabled: env.COXPIT_AUTH_DISABLED === '1',
+    authPass: env.COXPIT_AUTH_PASS != null && env.COXPIT_AUTH_PASS !== '',
   },
   // 에이전트 셀프 오케스트레이션 — real+로컬 run 에 COXPIT_API/COXPIT_TOKEN env 와
   // 능력 고지를 준다(에이전트가 /api/agent/subtasks 로 서브런 발사). '0' 으로 끔.

package/src/index.ts CHANGED Viewed

@@ -2,9 +2,10 @@ import { config } from './config';
 import { authMode, ensureSetupToken, isExposedBind } from './authkey';
 import { db, ensureSchema } from './db';
 import { machines } from './db/schema';
-import { acquireDaemonLock } from './lock';
+import { acquireDaemonLock, updateLockPort } from './lock';
 import { reconcileOrphanRuns } from './orchestrator';
 import { buildServer } from './server';
+import type { AddressInfo } from 'node:net';
 // Windows 네이티브는 에이전트 실행 계층(sh·tmux·git worktree over sh)이 성립하지 않는다.
 // 보드/원격 머신 관제는 되지만 로컬 run 은 불가 — WSL 데몬을 안내한다.
@@ -31,15 +32,35 @@ const orphans = await reconcileOrphanRuns();
 if (orphans > 0) console.log(`[coxpit] settled ${orphans} orphaned run(s) from a previous daemon instance`);
 const app = await buildServer();
-try {
-  await app.listen({ host: config.host, port: config.port });
-} catch (e) {
-  if ((e as NodeJS.ErrnoException)?.code === 'EADDRINUSE') {
-    console.error(`[coxpit] port ${config.port} is already in use — is another daemon (or app) running? Set COXPIT_PORT to change.`);
-    process.exit(1);
+// 포트 바인드 — 선호 포트가 점유면 자동으로 다음 빈 포트로 이동(고정 포트가 필수면
+// COXPIT_PORT_STRICT=1 로 실패 처리). 어떤 고정 포트에도 의존하지 않아 "포트 점유로 죽는" 케이스 소멸.
+async function listenAuto(): Promise<number> {
+  const pref = config.port;
+  const tryBind = async (p: number) => { await app.listen({ host: config.host, port: p }); };
+  try {
+    await tryBind(pref);
+    return pref;
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException)?.code !== 'EADDRINUSE') throw e;
+    if (config.portStrict) {
+      console.error(`[coxpit] port ${pref} is already in use and COXPIT_PORT_STRICT=1 — refusing to move. Free the port or unset strict.`);
+      process.exit(1);
+    }
+  }
+  // pref+1..+20 스캔 → 그래도 없으면 OS 배정(:0).
+  for (let p = pref + 1; p <= pref + 20; p++) {
+    try { await tryBind(p); console.warn(`[coxpit] port ${pref} was busy — moved to ${p}.`); return p; }
+    catch (e) { if ((e as NodeJS.ErrnoException)?.code !== 'EADDRINUSE') throw e; }
   }
-  throw e;
+  await app.listen({ host: config.host, port: 0 });
+  const p = (app.server.address() as AddressInfo).port;
+  console.warn(`[coxpit] ports ${pref}..${pref + 20} were busy — moved to OS-assigned ${p}.`);
+  return p;
 }
+const boundPort = await listenAuto();
+updateLockPort(boundPort);   // 락에 실제 포트 반영 — 데스크톱/외부가 이걸 읽어 붙는다.
+console.log(`[coxpit] listening on http://${config.host === '0.0.0.0' ? '127.0.0.1' : config.host}:${boundPort}/`);
 // 접근키 인증 상태 안내. 첫 실행(키 미설정)이면 브랜디드 셋업 페이지 + 1회용 셋업 토큰을 찍는다.
 // (토큰 = Jupyter 스타일: 로그 접근자 = 머신 소유자. 터널/타넷/로컬 어디서 붙어도 이 토큰으로 셋업 가능.)
@@ -55,7 +76,7 @@ try {
     const token = ensureSetupToken();
     console.log(
       '[coxpit] no access key configured yet — open the board to set one (first-run setup).\n' +
-      `[coxpit] one-time setup token (needed unless you visit http://127.0.0.1:${config.port} directly): ${token}`,
+      `[coxpit] one-time setup token (needed unless you visit http://127.0.0.1:${boundPort} directly): ${token}`,
     );
   } else if (m.mode === 'env') {
     console.log('[coxpit] access-key auth ON (COXPIT_AUTH_PASS) — the branded unlock page asks for that key.');

package/src/lock.ts CHANGED Viewed

@@ -39,6 +39,16 @@ function pidAlive(pid: number): boolean {
   try { process.kill(pid, 0); return true; } catch { return false; }
 }
+/** 실제 바인드 포트를 락에 반영(자동 포트 이동 후 — 데스크톱/외부가 실제 포트를 읽게). */
+export function updateLockPort(port: number): void {
+  try {
+    const cur = readLock(config.lockPath);
+    if (cur?.pid === process.pid && cur.port !== port) {
+      fs.writeFileSync(config.lockPath, JSON.stringify({ ...cur, port } satisfies LockInfo));
+    }
+  } catch { /* best effort */ }
+}
 /**
  * 락 획득. 이미 살아있는 데몬이 같은 DB 를 잡고 있으면 안내 후 종료.
  * 죽은 프로세스가 남긴 stale 락은 치우고 진행한다.

package/src/server.ts CHANGED Viewed

@@ -10,10 +10,11 @@ import { eq, inArray, and, like, desc } from 'drizzle-orm';
 import { authGate } from './auth';
 import { loginPageHTML } from './login';
 import {
-  authMode, authIsOpen, verifyKey, storeKey, signSession, SESSION_COOKIE,
+  authMode, authIsOpen, verifyKey, storeKey, clearStored, isExposedBind, signSession, SESSION_COOKIE,
   clientKey, rateCheck, rateFail, rateReset, setupAllowed,
 } from './authkey';
 import { config } from './config';
+import { readSettings, writeSettings } from './settings';
 import { db } from './db';
 import { machines, repos, tasks, agentRuns, agentEvents, designCaptures, shareLinks, taskGroups } from './db/schema';
 import { BOOKMARKLET_JS } from './design';
@@ -351,6 +352,72 @@ export async function buildServer(): Promise<FastifyInstance> {
   // v5.1 Documents (문서함) — every output the workspace produced, grouped by run (DB-only).
   app.get('/api/documents', async () => await listDocuments());
+  // ── Settings (settings.json 레이어) ──────────────────────────────
+  // 현재 유효값 + env 잠금 + 인증 상태. 시크릿(키)은 절대 안 내보낸다(hasKey 만).
+  app.get('/api/settings', async () => {
+    const s = readSettings();
+    const m = authMode();
+    return {
+      effective: {
+        port: config.port, portStrict: config.portStrict, host: config.host,
+        webhookUrl: config.webhookUrl, publicUrl: config.publicUrl,
+        agent: { provider: config.agent.provider, model: config.agent.model, count: config.agent.count, real: config.agent.real },
+      },
+      stored: s,
+      envLocked: config.envLocked,
+      auth: { mode: m.mode, exposed: isExposedBind(), hasKey: m.mode === 'stored' || m.mode === 'env', canManage: m.mode !== 'env' && !config.envLocked.authDisabled },
+      dataDir: pdirname(config.dbPath),
+      version: config.version,
+    };
+  });
+  // 부분 저장. env 로 고정된 필드는 무시(파일이 env 를 못 이김). 포트·호스트는 재시작 반영.
+  app.patch('/api/settings', async (req, reply) => {
+    const b = (req.body ?? {}) as {
+      port?: unknown; portStrict?: unknown; host?: unknown; webhookUrl?: unknown; publicUrl?: unknown;
+      agent?: { provider?: unknown; model?: unknown; count?: unknown; real?: unknown };
+    };
+    const patch: Record<string, unknown> = {};
+    const L = config.envLocked;
+    if (!L.port && b.port !== undefined) {
+      const p = Number(b.port);
+      if (!Number.isInteger(p) || p < 1 || p > 65535) return reply.code(400).send({ error: 'port must be 1–65535' });
+      patch.port = p;
+    }
+    if (!L.port && b.portStrict !== undefined) patch.portStrict = !!b.portStrict;
+    if (!L.host && b.host !== undefined) patch.host = String(b.host);
+    if (!L.webhookUrl && b.webhookUrl !== undefined) patch.webhookUrl = String(b.webhookUrl);
+    if (!L.publicUrl && b.publicUrl !== undefined) patch.publicUrl = String(b.publicUrl);
+    if (b.agent) {
+      const a: Record<string, unknown> = {};
+      if (b.agent.provider === 'claude-code' || b.agent.provider === 'codex') a.provider = b.agent.provider;
+      if (b.agent.model !== undefined) a.model = String(b.agent.model);
+      if (b.agent.count !== undefined) { const c = Number(b.agent.count); if (Number.isInteger(c) && c >= 1 && c <= 12) a.count = c; }
+      if (!L.real && b.agent.real !== undefined) a.real = !!b.agent.real;
+      if (Object.keys(a).length) patch.agent = a;
+    }
+    const next = writeSettings(patch);
+    const portChanged = 'port' in patch || 'portStrict' in patch || 'host' in patch;
+    return { ok: true, stored: next, restartRequired: portChanged };
+  });
+  // 접근 키 셀프서비스 — 설정/변경. env 모드(COXPIT_AUTH_PASS)면 파일로 못 바꿈(409).
+  app.post('/api/settings/key', async (req, reply) => {
+    if (authMode().mode === 'env' || config.envLocked.authDisabled) return reply.code(409).send({ error: 'auth is controlled by env — unset COXPIT_AUTH_PASS/COXPIT_AUTH_DISABLED to manage the key here' });
+    const b = (req.body ?? {}) as { key?: unknown };
+    const key = typeof b.key === 'string' ? b.key : '';
+    if (key.length < 6) return reply.code(400).send({ error: 'key must be at least 6 characters' });
+    storeKey(key);
+    return { ok: true };
+  });
+  // 접근 키 해제 — loopback 이면 무인증, 노출이면 첫 방문 셋업 상태로 되돌아감.
+  app.delete('/api/settings/key', async (_req, reply) => {
+    if (authMode().mode === 'env' || config.envLocked.authDisabled) return reply.code(409).send({ error: 'auth is controlled by env' });
+    clearStored();
+    return { ok: true };
+  });
   // 아카이브 — 닫힌 태스크 목록(최신순, 페이지네이션·필터). 카드가 아니라 한 줄 행.
   app.get('/api/archive', async (req) => {
     const q = (req.query ?? {}) as { offset?: string; limit?: string; q?: string; repo?: string; status?: string };

package/src/settings.ts ADDED Viewed

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import { config } from './config';
+// 영속 설정 — 데이터 폴더(~/.coxpit)의 settings.json. 웹 Settings 페이지가 읽고/쓴다.
+// 우선순위(config.ts 에서 병합): 명시 env > settings.json > 기본값. env 를 준 값은 파일이 못 이긴다.
+// 시크릿(접근 키)은 여기 넣지 않는다 — authkey.ts(auth.json, 해시)가 소유.
+export interface Settings {
+  port?: number;
+  portStrict?: boolean;
+  host?: string;
+  webhookUrl?: string;
+  publicUrl?: string;
+  agent?: {
+    provider?: 'claude-code' | 'codex';
+    model?: string;
+    count?: number;
+    real?: boolean;
+  };
+}
+export function readSettings(): Settings {
+  try {
+    const raw = JSON.parse(fs.readFileSync(config.settingsPath, 'utf8'));
+    return raw && typeof raw === 'object' ? (raw as Settings) : {};
+  } catch {
+    return {};
+  }
+}
+/** 부분 병합 저장. env 로 고정된 값은 UI 에서 잠기므로 여기선 순수 저장만. */
+export function writeSettings(patch: Settings): Settings {
+  const cur = readSettings();
+  const next: Settings = { ...cur, ...patch };
+  if (patch.agent) next.agent = { ...(cur.agent ?? {}), ...patch.agent };
+  fs.writeFileSync(config.settingsPath, JSON.stringify(next, null, 2) + '\n');
+  return next;
+}