Shardflux

A link to watch the workspace desktop live in a browser (view only unless interactive): give it to the person you work for. Returns {url, expires_at, port, interactive}. Anyone with the link can open it until expires_at, so treat it like a password. stop: true ends every view instead.

Write up to 64 KiB at the acknowledged byte offset (0 initially). close sends EOF. A repeated identical last frame cannot duplicate bytes; continue from a partial acknowledgement.

Start a tracked exec session and return at once; read it with exec_read and stop it with exec_cancel. stdin_open keeps a pipe open for workspace_exec_input. Processful workspaces only.

Serve a TCP port of the workspace at its own HTTPS URL (https://<port>-<handle>.<domain>), e.g. a dev server, a preview of the app you are building, or a webhook receiver. Returns {port, url, created_at, callback, newly_exposed}. The port is private: nothing reaches it without a credential, so to open it in a browser (or give a person access) call workspace_port_link. Start the server inside the workspace listening on 0.0.0.0:<port> (not only 127.0.0.1), e.g. with workspace_exec_start. A request to a suspended or idle workspace wakes it and is answered once it runs. Idempotent: an exposed port…

Fork a running or suspended workspace into a new key (an independent copy of its committed state). Returns the fork operation and the new workspace (with wait: once finished, and its timing). Not for file-first workspaces.

Stage a parked workspace ahead of an imminent VM tool call. Invoke explicitly when tool input starts; returns without waiting for restore. A suspended workspace must be resumed first.

Read idle policy and activity without waking or recording activity.

Prevent idle suspension for seconds; never shortens an existing keepalive.

List the workspaces of this API key’s project (key, state, template, active operation).

The exposed ports of the workspace: {ports: [{port, url, created_at, callback}]}, ordered by port. callback is set when the port has a callback URL for webhooks. Every port is private; workspace_port_link gives a link that opens one in a browser.

Open a persistent workspace by key: creates it from the template on first use, reconnects (or resumes) it afterwards, never resets it. Waits until it is ready unless wait is false; on timeout the start continues server side (operation_wait); a queued start has a deadline 15 minutes after it was created. The result’s timing says where the time went. mode "file_first" opens a file-first workspace (files only, ready at once; see mode).

A link that opens an exposed port in a browser: give it to the person you work for, or open it yourself. Returns {url, expires_at}. Opening it starts a browser session for the port until expires_at and lands on path. Anyone with the link can open the port until then, so treat it like a password. Expose the port first with workspace_expose_port.

Give a workspace more (or less) memory, CPU or disk without a restart, running or suspended, fixed or elastic: use it when a build, a test suite or a dataset needs more than the workspace has. Memory changes live and disks grow online; a suspended workspace gets its new size when it resumes, before its first call. CPU changes live within the vCPUs the workspace booted with; a larger CPU size applies at its next start. The new caps are stored, so every later start uses them. Returns per resource what applied and when (applies_at: now, resume or next_start), the stored caps and a one-line messag…

Switch computer use on or off for a workspace (inherit follows its template). While it is on, the computer tool drives the workspace desktop, which starts on the first computer call. Returns {enabled, workspace, template, available}; available false means its template version cannot run a desktop (switching on is then refused).

Set adaptive, never or fixed:<seconds> (60..604800); default restores the inherited policy.

Replace all labels; an empty object clears them. Labels are searchable metadata, not secrets.

Delete a persistent workspace after this many idle days (1..3650). null removes its own policy and follows the project default.

Current state of one workspace (ready, mode, observed/desired state, grants, pending reason; tree_revision for a file-first workspace) and its most recent operations.

Suspend a running workspace (full-state checkpoint; processes stop, files and state are kept, and the next tool call resumes it). Returns the suspend operation (with wait: once finished, and its timing). A finished suspend returns as soon as the workspace is sealed on its host (typically a few hundred ms); its durable field turns true when the copy lands in durable storage, typically within a second. Pass durable: true to return only then. With after_seconds the suspend is deferred instead: the workspace is suspended once it has been idle that long. Use it when you finish your work (the end of…

Keep files, installed package files and home while moving to the supported current layout/base. One cold start ends memory and running processes. at next_resume schedules it without stopping the VM; now upgrades immediately. The operation reports whether it is scheduled or applied.