codebay 0.15.0 → 0.16.0

package/src/lib/log-capture.server.ts

@@ -7,8 +7,8 @@ import {
 	statSync,
 	writeFileSync
 } from 'node:fs';
-import { join } from 'node:path';
-import { LOGS_DIR } from './config.server.ts';
+import { dirname, join } from 'node:path';
+import { claudeMirrorDir, LOGS_DIR } from './config.server.ts';
 import { getInstance, type InstanceRow } from './db.server.ts';
 import { isRunning } from './docker.server.ts';
 import { execInContainer } from './exec.server.ts';
@@ -23,25 +23,30 @@ const END_MARKER = '__CODEBAY_END__';
 
 export interface ManifestEntry {
 	path: string;
+	/** Path relative to the container's Claude config dir, e.g. `projects/-workspaces-foo/x.jsonl`. */
+	relPath: string;
 	size: number;
 }
 
 interface FetchJob {
 	path: string;
+	relPath: string;
 	hostFileName: string;
 	/** 1-indexed byte to `tail -c +N` from; 1 re-pulls the whole file. */
 	startByte: number;
-	mode: 'append' | 'rollover';
 }
 
 /**
- * Lists the transcript + history files with their byte sizes. `find`/`wc -c` (not GNU `-printf`)
- * so it works on busybox containers too; the marker line lets the parser skip login-shell noise.
+ * Lists the transcript + history files with their byte sizes, led by the config dir itself so the
+ * parser can derive each file's layout-preserving relative path rather than guess at the encoding.
+ * `find`/`wc -c` (not GNU `-printf`) so it works on busybox containers too; the marker line lets
+ * the parser skip login-shell noise.
  */
-function manifestScript(): string {
+export function manifestScript(): string {
 	return (
 		`h=$(eval echo ~$(id -un)); cfg="\${CLAUDE_CONFIG_DIR:-$h/.claude}"; ` +
 		`printf '%s\\n' '${MANIFEST_MARKER}'; ` +
+		`printf '%s\\n' "$cfg"; ` +
 		`{ find "$cfg" -maxdepth 1 -type f -name 'history.jsonl' 2>/dev/null; ` +
 		`find "$cfg/projects" -type f -name '*.jsonl' 2>/dev/null; } | ` +
 		`while IFS= read -r f; do printf '%s\\t%s\\n' "$f" "$(wc -c < "$f" | tr -d ' ')"; done; true`
@@ -74,13 +79,21 @@ function fetchScript(): string {
 export function parseManifest(stdout: string): ManifestEntry[] {
 	const at = stdout.indexOf(MANIFEST_MARKER);
 	if (at === -1) return [];
+	const [, cfgLine, ...lines] = stdout.slice(at + MANIFEST_MARKER.length).split('\n');
+	// Trailing slashes would leave the relative path leading with one, breaking the host join.
+	const cfg = (cfgLine ?? '').trim().replace(/\/+$/, '');
+	if (!cfg) return [];
 	const out: ManifestEntry[] = [];
-	for (const line of stdout.slice(at + MANIFEST_MARKER.length).split('\n')) {
+	for (const line of lines) {
 		const tab = line.indexOf('\t');
 		if (tab === -1) continue;
 		const path = line.slice(0, tab);
 		const size = Number(line.slice(tab + 1).trim());
-		if (path && Number.isFinite(size)) out.push({ path, size });
+		if (!path || !Number.isFinite(size) || !path.startsWith(`${cfg}/`)) continue;
+		const relPath = path.slice(cfg.length + 1);
+		// `find` can't emit `..` today, but this gets joined onto a host dir, so don't rely on that.
+		if (relPath.split('/').includes('..')) continue;
+		out.push({ path, relPath, size });
 	}
 	return out;
 }
@@ -94,19 +107,22 @@ export function hostFileNameFor(instanceId: string, containerPath: string): stri
 	return `history-${instanceId}.jsonl`;
 }
 
-/** Diffs container sizes against the host mirrors: append new bytes, or re-pull a file that shrank. */
+/**
+ * Diffs container sizes against the host mirrors: append new bytes, or re-pull a file that shrank.
+ * Sized against the layout-preserving mirror, not the flat archive, because that one tracks the
+ * container 1:1 — it's what gets mounted back in, so it must stay a byte-exact copy.
+ */
 export function planFetch(
 	instanceId: string,
 	manifest: ManifestEntry[],
-	hostSize: (hostFileName: string) => number
+	hostSize: (relPath: string) => number
 ): FetchJob[] {
 	const jobs: FetchJob[] = [];
-	for (const { path, size } of manifest) {
+	for (const { path, relPath, size } of manifest) {
 		const hostFileName = hostFileNameFor(instanceId, path);
-		const existing = hostSize(hostFileName);
+		const existing = hostSize(relPath);
 		if (size === existing) continue;
-		if (size < existing) jobs.push({ path, hostFileName, startByte: 1, mode: 'rollover' });
-		else jobs.push({ path, hostFileName, startByte: existing + 1, mode: 'append' });
+		jobs.push({ path, relPath, hostFileName, startByte: size < existing ? 1 : existing + 1 });
 	}
 	return jobs;
 }
@@ -178,6 +194,7 @@ function updateIndex(logsDir: string, row: InstanceRow): void {
 interface CaptureDeps {
 	exec?: typeof execInContainer;
 	logsDir?: string;
+	mirrorDir?: string;
 }
 
 /**
@@ -188,6 +205,7 @@ export async function runCapturePass(row: InstanceRow, deps: CaptureDeps = {}):
 	if (!row.container_id) return false;
 	const exec = deps.exec ?? execInContainer;
 	const logsDir = deps.logsDir ?? LOGS_DIR;
+	const mirrorDir = deps.mirrorDir ?? claudeMirrorDir(row.id);
 	const target = { containerId: row.container_id, remoteUser: row.remote_user };
 
 	const manifestRes = await exec(target, { script: manifestScript(), capture: true });
@@ -195,7 +213,7 @@ export async function runCapturePass(row: InstanceRow, deps: CaptureDeps = {}):
 	const manifest = parseManifest(manifestRes.stdout);
 
 	mkdirSync(logsDir, { recursive: true });
-	const jobs = planFetch(row.id, manifest, (name) => sizeOnDisk(join(logsDir, name)));
+	const jobs = planFetch(row.id, manifest, (rel) => sizeOnDisk(join(mirrorDir, rel)));
 
 	if (jobs.length) {
 		const args = ['fetch'];
@@ -207,9 +225,19 @@ export async function runCapturePass(row: InstanceRow, deps: CaptureDeps = {}):
 				const job = byPath.get(block.path);
 				if (!job) continue;
 				const bytes = Buffer.from(block.base64, 'base64');
-				const dest = join(logsDir, job.hostFileName);
-				if (job.mode === 'rollover') rollOver(dest);
-				appendFileSync(dest, bytes);
+				const archive = join(logsDir, job.hostFileName);
+				const mirror = join(mirrorDir, job.relPath);
+				mkdirSync(dirname(mirror), { recursive: true });
+				// The archive keeps every generation; the mirror only ever holds what the container
+				// holds, since it gets mounted back in and a stale byte would resurface as history.
+				// Any whole-file pull rolls, since a pre-mirror instance's archive would otherwise double.
+				if (job.startByte === 1) {
+					rollOver(archive);
+					writeFileSync(mirror, bytes);
+				} else {
+					appendFileSync(mirror, bytes);
+				}
+				appendFileSync(archive, bytes);
 			}
 		}
 	}

package/src/lib/osc52.ts

@@ -0,0 +1,18 @@
+/**
+ * OSC 52 is how a program inside the container asks the *outer* terminal to put text on the host
+ * clipboard — what tmux's `set-clipboard on` emits on copy. xterm.js ships no handler for it, so
+ * every such write was silently dropped and copy out of an instance was impossible.
+ */
+export function decodeOsc52(data: string): string | null {
+	const sep = data.indexOf(';');
+	if (sep === -1) return null;
+	const payload = data.slice(sep + 1).replace(/\s+/g, '');
+	// `?` is a read request; answering it would hand the host clipboard to the container.
+	if (payload === '' || payload === '?') return null;
+	try {
+		const bytes = Uint8Array.from(atob(payload), (c) => c.charCodeAt(0));
+		return new TextDecoder().decode(bytes);
+	} catch {
+		return null;
+	}
+}

package/src/lib/upload.ts

@@ -0,0 +1,32 @@
+import { apiFetch } from '../api.ts';
+
+export interface UploadedFile {
+	name: string;
+	hostPath: string;
+	containerPath: string;
+	bytes: number;
+}
+
+/** Unknown MIME subtype → `.bin`, so a pasted image never round-trips with no extension at all. */
+function extFor(mimeType: string): string {
+	const subtype = mimeType.split('/')[1];
+	return subtype && /^[a-z0-9.+-]+$/i.test(subtype) ? subtype : 'bin';
+}
+
+/** Files from a drop or a paste; pasted images arrive nameless, so they get a timestamped one. */
+export function filesFrom(dt: DataTransfer | null): File[] {
+	if (!dt) return [];
+	return [...dt.files].map((f) =>
+		f.name ? f : new File([f], `pasted-${Date.now()}.${extFor(f.type)}`, { type: f.type })
+	);
+}
+
+export async function uploadFile(id: string, file: File): Promise<UploadedFile> {
+	const q = new URLSearchParams({ name: file.name });
+	const { file: saved } = await apiFetch<{ file: UploadedFile }>(
+		`/api/instances/${id}/upload?${q}`,
+		{ method: 'POST', headers: { 'Content-Type': 'application/octet-stream' }, body: file },
+		'Upload failed'
+	);
+	return saved;
+}

package/src/lib/uploads.server.ts

@@ -0,0 +1,164 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { open, unlink, type FileHandle } from 'node:fs/promises';
+import { basename, join, posix, resolve, sep } from 'node:path';
+import { Mochi, apiError, json, type MochiRouteValue } from 'mochi-framework';
+import { getInstance, getOption, type InstanceRow } from './db.server.ts';
+
+export const UPLOAD_ENABLED_KEY = 'workspace_upload_enabled';
+
+/** Off until someone opts in — a write path into every workspace is not something to ship armed. */
+export function uploadEnabled(): boolean {
+	return getOption(UPLOAD_ENABLED_KEY) === '1';
+}
+
+/** The drop folder inside every workspace; git-excluded (MANAGER_GIT_EXCLUDES + its own .gitignore). */
+export const INBOX_DIR = 'codebay-inbox';
+
+/** App-level ceiling, independent of Bun's `maxRequestBodySize` — kept in one place so they can't drift. */
+export const UPLOAD_MAX_BYTES = 256 * 1024 * 1024;
+
+/**
+ * A bare filename only. `basename()` alone isn't enough to stop `../x` or `a/b` — a path with
+ * separators would silently resolve to a different (real) name than what it looks like it means,
+ * so any input `basename()` had to change is rejected outright rather than normalized.
+ */
+function hasControlChar(name: string): boolean {
+	for (let i = 0; i < name.length; i++) {
+		if (name.charCodeAt(i) < 0x20) return true;
+	}
+	return false;
+}
+
+export function safeUploadName(raw: string): string {
+	const trimmed = raw.trim();
+	const candidate = basename(trimmed);
+	if (!candidate || candidate === '.' || candidate === '..' || candidate.length > 200) {
+		throw new Error('invalid file name');
+	}
+	if (candidate !== trimmed || /[\\/]/.test(candidate) || hasControlChar(candidate)) {
+		throw new Error('invalid file name');
+	}
+	return candidate;
+}
+
+/** `name`, then `name-1.ext`, `name-2.ext`… — the candidates `openUnique` tries in order. */
+function* candidateNames(name: string): Generator<string> {
+	yield name;
+	const dot = name.lastIndexOf('.');
+	const stem = dot > 0 ? name.slice(0, dot) : name;
+	const ext = dot > 0 ? name.slice(dot) : '';
+	for (let n = 1; ; n++) yield `${stem}-${n}${ext}`;
+}
+
+/**
+ * Claims the first free candidate with an exclusive create, so nothing already in the inbox is ever
+ * overwritten. `wx` (O_CREAT|O_EXCL) also refuses to follow a symlink — even a dangling one, which
+ * an `existsSync` probe would report as free and a plain write would follow outside the workspace.
+ */
+export async function openUnique(
+	dir: string,
+	name: string
+): Promise<{ name: string; path: string; file: FileHandle }> {
+	for (const candidate of candidateNames(name)) {
+		const path = join(dir, candidate);
+		try {
+			return { name: candidate, path, file: await open(path, 'wx') };
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err;
+		}
+	}
+	throw new Error('unreachable');
+}
+
+const INBOX_GITIGNORE = '*\n';
+// Earlier builds seeded this, whose negation left the folder itself showing in `git status`.
+const LEGACY_INBOX_GITIGNORE = '*\n!.gitignore\n';
+
+/** Self-excluding, so the inbox needs no entry in `MANAGER_GIT_EXCLUDES`-derived `.git/info/exclude`. */
+function seedInboxGitignore(inbox: string): void {
+	const path = join(inbox, '.gitignore');
+	const st = lstatSync(path, { throwIfNoEntry: false });
+	if (!st) {
+		try {
+			writeFileSync(path, INBOX_GITIGNORE, { flag: 'wx' });
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err;
+		}
+	} else if (st.isFile() && readFileSync(path, 'utf8') === LEGACY_INBOX_GITIGNORE) {
+		writeFileSync(path, INBOX_GITIGNORE);
+	}
+}
+
+export interface SavedUpload {
+	name: string;
+	hostPath: string;
+	containerPath: string;
+	bytes: number;
+}
+
+/** Writes straight to the host bind mount — no `execInContainer`, no base64, no 128 KiB carrier cap. */
+export async function saveUpload(
+	row: InstanceRow,
+	rawName: string,
+	body: ReadableStream<Uint8Array> | Blob
+): Promise<SavedUpload> {
+	if (!existsSync(row.workspace_path)) throw new Error('Workspace folder is not on disk yet');
+	if (!row.remote_workspace_folder) throw new Error('Instance has not booted yet');
+	const inbox = join(row.workspace_path, INBOX_DIR);
+	// A symlinked inbox could redirect the write outside the workspace, so refuse anything but a real
+	// dir — `lstat`, not `existsSync`, which reports a dangling link as absent.
+	const st = lstatSync(inbox, { throwIfNoEntry: false });
+	if (st && !st.isDirectory()) throw new Error(`${INBOX_DIR} is not a directory`);
+	mkdirSync(inbox, { recursive: true });
+	seedInboxGitignore(inbox);
+	const safe = safeUploadName(rawName);
+	if (!resolve(inbox, safe).startsWith(inbox + sep)) throw new Error('invalid file name'); // belt and braces
+	const { name, path: dest, file } = await openUnique(inbox, safe);
+	// Streamed to disk chunk by chunk, so the body never has to fit in memory.
+	let written = 0;
+	try {
+		const stream = body instanceof Blob ? body.stream() : body;
+		for await (const chunk of stream) {
+			for (let off = 0; off < chunk.byteLength;) {
+				off += (await file.write(chunk, off)).bytesWritten;
+			}
+			written += chunk.byteLength;
+		}
+	} catch (err) {
+		// An aborted or over-cap body would otherwise leave a truncated file that looks complete.
+		await file.close();
+		await unlink(dest);
+		throw err;
+	}
+	await file.close();
+	return {
+		name,
+		hostPath: dest,
+		bytes: written,
+		// posix.join, never `join` — the container path is POSIX even when the host is Windows.
+		containerPath: posix.join(row.remote_workspace_folder, INBOX_DIR, name)
+	};
+}
+
+/**
+ * Raw body + `?name=` rather than multipart: nothing to parse, and the bytes stream straight to
+ * disk. Spread into the route table like `proxyRoutes`/`mcpRoutes`, and kept off `routes.ts`'s own
+ * `mutationRoute` helper (which always answers 200) because this needs 404 and 413.
+ */
+export const uploadRoutes: Record<string, MochiRouteValue> = {
+	'/api/instances/:id/upload': Mochi.api(async ({ method, params, url, request }) => {
+		if (method !== 'POST') return apiError(405, 'Method Not Allowed');
+		if (!uploadEnabled()) return apiError(404, 'Not Found');
+		const row = getInstance(params.id!);
+		if (!row) return apiError(404, 'Instance not found');
+		const len = Number(request.headers.get('content-length') ?? '0');
+		if (len > UPLOAD_MAX_BYTES) return apiError(413, `File exceeds ${UPLOAD_MAX_BYTES} bytes`);
+		if (!request.body) return apiError(400, 'Empty body');
+		try {
+			const saved = await saveUpload(row, url.searchParams.get('name') ?? '', request.body);
+			return json({ file: saved }, { status: 201 });
+		} catch (err) {
+			return apiError(400, (err as Error).message);
+		}
+	})
+};

package/src/mcp/server.server.ts

@@ -12,7 +12,10 @@ The normal flow is: create_sandbox (from a Git URL or a local folder) → poll g
 status is "running" → run_agent with a prompt → poll get_run until it is done → get_diff to see what
 changed → git_push / create_pr to land it.
 
-Sandboxes are persistent and cost real resources, so delete_sandbox when you are finished with one.
+Sandboxes are persistent and cost real resources: stop_sandbox one you will come back to (its
+workspace and run history stay; start_sandbox brings it back) and delete_sandbox one you are finished
+with. rebuild_sandbox recreates the container from the devcontainer config, keeping the workspace —
+it is what applies add_port_forward / remove_port_forward.
 A sandbox runs one agent at a time. Runs are asynchronous: run_agent returns a handle immediately and
 the work continues in the background, so never assume a run has finished without checking get_run.`;
 

package/src/mcp/tools.server.ts

@@ -2,13 +2,27 @@ import * as v from 'valibot';
 import type { McpServer } from 'tmcp';
 import { tool } from 'tmcp/utils';
 import {
+	addForwardedPort,
 	createInstance,
 	deleteInstance,
 	listInstances,
+	rebuildInstance,
+	removeForwardedPort,
+	renameInstance,
 	sanitizeInstance,
+	startInstance,
+	stopInstance,
 	subscribeLogs
 } from '../lib/instances.server.ts';
-import { getInstance, getRun, listRuns, type AgentRunRow } from '../lib/db.server.ts';
+import {
+	getInstance,
+	getRun,
+	listForwards,
+	listRuns,
+	openRunFor,
+	type AgentRunRow,
+	type InstanceRow
+} from '../lib/db.server.ts';
 import {
 	PROMPT_MAX_BYTES,
 	pollRunNow,
@@ -36,21 +50,34 @@ const MAX_WAIT_SECONDS = 60;
 
 const sandboxId = v.pipe(v.string(), v.minLength(1), v.description('The sandbox id.'));
 
+const containerPort = v.pipe(
+	v.number(),
+	v.integer(),
+	v.minValue(1),
+	v.maxValue(65535),
+	v.description('The port inside the container.')
+);
+
 function requireInstance(id: string) {
 	const row = getInstance(id);
 	if (!row) throw new Error(`No sandbox with id ${id}`);
 	return row;
 }
 
+/** A boot owns its row until the last injection lands, so nothing else may move it before then. */
+function requireSettled(id: string) {
+	const row = requireInstance(id);
+	if (row.status === 'creating') {
+		throw new Error('the sandbox is still building — poll get_sandbox until status is "running"');
+	}
+	return row;
+}
+
 /** Every tool that touches the container needs one that is actually up. */
 function requireRunning(id: string) {
-	const row = requireInstance(id);
+	const row = requireSettled(id);
 	if (!row.container_id || row.status !== 'running') {
-		throw new Error(
-			row.status === 'creating'
-				? 'the sandbox is still building — poll get_sandbox until status is "running"'
-				: `the sandbox is ${row.status}, not running`
-		);
+		throw new Error(`the sandbox is ${row.status}, not running`);
 	}
 	return row;
 }
@@ -58,8 +85,20 @@ function requireRunning(id: string) {
 /** The IDE link is what makes a sandbox inspectable by a human, so every sandbox payload carries it. */
 const ideUrl = (id: string) => `${PUBLIC_ORIGIN}${proxyPathFor(id)}`;
 
-function sandboxPayload(row: ReturnType<typeof requireInstance>) {
-	return { ...sanitizeInstance(row), ide_url: ideUrl(row.id) };
+const healthFor = (id: string) => currentHealthSnapshots().find((s) => s.id === id)?.health ?? null;
+
+/** Forwards ride along because add/remove_port_forward hand back the sandbox as their receipt. */
+function sandboxPayload(row: InstanceRow) {
+	const open = new Set(healthFor(row.id)?.openPorts ?? []);
+	return {
+		...sanitizeInstance(row),
+		ide_url: ideUrl(row.id),
+		forwarded_ports: listForwards(row.id).map((f) => ({
+			container_port: f.container_port,
+			host_port: f.host_port,
+			open: open.has(f.container_port)
+		}))
+	};
 }
 
 /** The prompt is left out: the caller wrote it, and it can be as large as the carrier allows. */
@@ -68,6 +107,11 @@ function runPayload(run: AgentRunRow) {
 	return { run_id: id, sandbox_id: instance_id, ...detail };
 }
 
+/** The run a stop/rebuild settled, re-read after the fact so the caller sees it as cancelled. */
+function cancelledRun(open: AgentRunRow | null) {
+	return open ? runPayload(getRun(open.id)!) : null;
+}
+
 /**
  * A failed call reaches the model as readable content rather than a JSON-RPC protocol error: the
  * caller is an agent, and "that sandbox is still building" is information it can act on.
@@ -103,7 +147,10 @@ const runOptions = {
 		v.pipe(
 			v.string(),
 			v.description(
-				'A JSON Schema (as a string). When set, the run’s structured_output matches it.'
+				'A JSON Schema (as a string). When set, the run’s structured_output matches it. If no ' +
+					'payload ever validates the run fails with error "structured_output_failed", and its ' +
+					'result holds Claude’s plain-text answer with rejected_structured_output the last ' +
+					'payload the schema refused.'
 			)
 		)
 	),
@@ -224,11 +271,10 @@ export function registerTools(server: McpServer<v.GenericSchema>): void {
 		},
 		async (input) => {
 			const row = requireInstance(input.sandbox_id);
-			const health = currentHealthSnapshots().find((s) => s.id === row.id)?.health ?? null;
 			const runs = listRuns(row.id, 5);
 			return {
 				sandbox: sandboxPayload(row),
-				health,
+				health: healthFor(row.id),
 				runs: runs.map(runPayload)
 			};
 		}
@@ -249,6 +295,126 @@ export function registerTools(server: McpServer<v.GenericSchema>): void {
 		}
 	);
 
+	define(
+		{
+			name: 'stop_sandbox',
+			description:
+				'Stop a sandbox’s container without destroying it: the workspace, its files and its run ' +
+				'history are kept, and start_sandbox brings it back. Any active run is cancelled first, ' +
+				'the same way the dashboard’s Stop does, and comes back as cancelled_run so the ' +
+				'cancellation is never silent. Synchronous: the returned sandbox already has its new ' +
+				'status ("stopped", or "error" with the reason if Docker refused).',
+			schema: v.object({ sandbox_id: sandboxId })
+		},
+		async (input) => {
+			const row = requireSettled(input.sandbox_id);
+			if (!row.container_id) throw new Error('the sandbox has no container to stop');
+			const open = openRunFor(row.id);
+			const sandbox = sandboxPayload(await stopInstance(row.id));
+			return { sandbox, cancelled_run: cancelledRun(open) };
+		}
+	);
+
+	define(
+		{
+			name: 'start_sandbox',
+			description:
+				'Start a stopped sandbox’s container again. Synchronous, unlike create_sandbox: it ' +
+				'returns once Docker has started the container, with status already "running" (or ' +
+				'"error", with the reason in `error`), so there is nothing to poll for the status itself. ' +
+				'The editor surface inside takes a few more seconds to come up; get_sandbox’s ' +
+				'health.codeServerAccessible reports when it has. run_agent, exec_command and the file ' +
+				'tools work as soon as status is "running".',
+			schema: v.object({ sandbox_id: sandboxId })
+		},
+		async (input) => {
+			const row = requireSettled(input.sandbox_id);
+			if (!row.container_id) throw new Error('the sandbox has no container to start');
+			return { sandbox: sandboxPayload(await startInstance(row.id)) };
+		}
+	);
+
+	define(
+		{
+			name: 'rebuild_sandbox',
+			description:
+				'Recreate a sandbox’s container from its devcontainer config while keeping the workspace ' +
+				'copy, so files edited inside survive. This is what applies add_port_forward / ' +
+				'remove_port_forward and re-runs the Codebay injections (credentials, hooks). Any active ' +
+				'run is cancelled and comes back as cancelled_run. Returns immediately with status ' +
+				'"creating" while the build runs in the background; poll get_sandbox until status is ' +
+				'"running" (or "error" — get_logs kind "boot" says why).',
+			schema: v.object({
+				sandbox_id: sandboxId,
+				no_cache: v.optional(
+					v.pipe(v.boolean(), v.description('Rebuild the image without Docker’s build cache.'))
+				)
+			})
+		},
+		(input) => {
+			const row = requireSettled(input.sandbox_id);
+			const open = openRunFor(row.id);
+			const sandbox = sandboxPayload(rebuildInstance(row.id, { noCache: input.no_cache }));
+			return {
+				sandbox,
+				cancelled_run: cancelledRun(open),
+				note: 'The sandbox is rebuilding. Poll get_sandbox until status is "running".'
+			};
+		}
+	);
+
+	define(
+		{
+			name: 'rename_sandbox',
+			description:
+				'Rename a sandbox. Names are unique, so a clash gets a " #2"-style suffix; the returned ' +
+				'sandbox carries the name actually applied.',
+			schema: v.object({ sandbox_id: sandboxId, name: v.pipe(v.string(), v.minLength(1)) })
+		},
+		(input) => {
+			requireInstance(input.sandbox_id);
+			return { sandbox: sandboxPayload(renameInstance(input.sandbox_id, input.name)) };
+		}
+	);
+
+	define(
+		{
+			name: 'add_port_forward',
+			description:
+				'Publish a port inside the sandbox (e.g. a dev server an agent started) on a host port of ' +
+				'the Codebay host, so a human can open it; Codebay picks the host port. Only persisted ' +
+				'here: the mapping goes live on the next rebuild_sandbox, and forwarded_ports[].open on ' +
+				'get_sandbox shows once the mapping is published (after a rebuild).',
+			schema: v.object({ sandbox_id: sandboxId, port: containerPort })
+		},
+		async (input) => {
+			requireInstance(input.sandbox_id);
+			const sandbox = sandboxPayload(await addForwardedPort(input.sandbox_id, input.port));
+			return {
+				sandbox,
+				forward: sandbox.forwarded_ports.find((f) => f.container_port === input.port) ?? null,
+				note: 'Forwards are applied by rebuild_sandbox; the port is not published until then.'
+			};
+		}
+	);
+
+	define(
+		{
+			name: 'remove_port_forward',
+			description:
+				'Drop a forwarded port. Like add_port_forward this only updates the persisted set; the ' +
+				'mapping is actually unpublished by the next rebuild_sandbox.',
+			schema: v.object({ sandbox_id: sandboxId, port: containerPort })
+		},
+		(input) => {
+			requireInstance(input.sandbox_id);
+			return {
+				sandbox: sandboxPayload(removeForwardedPort(input.sandbox_id, input.port)),
+				note: 'Forwards are applied by rebuild_sandbox; the port stays published until then.'
+			};
+		}
+	);
+
 	define(
 		{
 			name: 'run_agent',

package/src/pages/Instance.svelte

@@ -3,7 +3,11 @@
 	import '@fontsource-variable/jetbrains-mono';
 	import InstanceView from '../components/InstanceView.svelte';
 
-	let { id, injectionChecks }: { id: string; injectionChecks: number } = $props();
+	let {
+		id,
+		injectionChecks,
+		uploadEnabled
+	}: { id: string; injectionChecks: number; uploadEnabled: boolean } = $props();
 </script>
 
-<InstanceView {id} {injectionChecks} mochi:hydrate />
+<InstanceView {id} {injectionChecks} {uploadEnabled} mochi:hydrate />

package/src/pages/Settings.svelte

@@ -19,6 +19,7 @@
 		defaultImage,
 		builtinImage,
 		disableBuildCache,
+		workspaceUploadEnabled,
 		copyIgnorePatterns,
 		builtinCopyIgnore,
 		claudeConfigDir,
@@ -65,6 +66,7 @@
 		defaultImage: string;
 		builtinImage: string;
 		disableBuildCache: boolean;
+		workspaceUploadEnabled: boolean;
 		copyIgnorePatterns: string;
 		builtinCopyIgnore: string;
 		claudeConfigDir: string;
@@ -114,6 +116,7 @@
 	{defaultImage}
 	{builtinImage}
 	{disableBuildCache}
+	{workspaceUploadEnabled}
 	{copyIgnorePatterns}
 	{builtinCopyIgnore}
 	{claudeConfigDir}