Project Runtime

The project runtime lets FastClaw scaffold a web project from a template, run its dev server in a long-lived sandbox, and return a preview URL while the agent continues editing files.

Two Layers

Layer	Owns	Lifecycle
Project	Source tree and chat grouping	Created by the user, persistent
Project Runtime	Running dev-server container and preview URL	Booted on demand, evictable

The runtime is keyed by (user_id, agent_id, project_id). Deleting runtime records removes previews but does not delete project files or chat history.

In the Docker backend, the runtime container and the agent's per-turn sandbox bind-mount the same host project directory. When the agent edits files, the dev server sees the edits and HMR updates the preview.

Runtime API

Method	Path	Purpose
`GET`	`/api/agents/{id}/projects/{pid}/runtime`	Current runtime state
`POST`	`/api/agents/{id}/projects/{pid}/runtime/up`	Provision and boot
`POST`	`/api/agents/{id}/projects/{pid}/runtime/sleep`	Stop container, keep files
`POST`	`/api/agents/{id}/projects/{pid}/runtime/wake`	Reboot sleeping runtime
`DELETE`	`/api/agents/{id}/projects/{pid}/runtime`	Tear down runtime, keep files
`GET`	`/api/agents/{id}/projects/{pid}/preview`	Preview URL and status
`GET`	`/api/agents/{id}/projects/{pid}/runtime/logs`	Dev-server logs

Template Env

FASTCLAW_PREVIEW_BASE
FASTCLAW_SHIPANY_TEMPLATE_DIR
FASTCLAW_SHIPANY_SCAFFOLD
FASTCLAW_SHIPANY_DEV
FASTCLAW_VITE_REACT_SCAFFOLD
FASTCLAW_VITE_REACT_DEV

FASTCLAW_PREVIEW_BASE may use {project} as a placeholder, for example:

https://{project}.preview.example.com

Agent Tools

When the runtime is wired, agents can use:

start_app_preview
app_preview_logs

These tools are only available on agents that have a runtime manager registered.

Two Layers

Live Preview Model

Runtime API

Template Env

Agent Tools

On this page