9. Wire up Cog playground and documentation

architecture/06-cli.md

@@ -6,15 +6,16 @@ The Cog CLI is a Go binary that provides commands for the full model lifecycle:
 
 ## Commands Overview
 
-| Command     | Job To Be Done                        |
-| ----------- | ------------------------------------- |
-| `cog init`  | Bootstrap a new model project         |
-| `cog build` | Create a container image              |
-| `cog run`   | Run a prediction in a container       |
-| `cog exec`  | Run arbitrary commands in a container |
-| `cog serve` | Start HTTP server in a container      |
-| `cog push`  | Deploy to Replicate                   |
-| `cog login` | Authenticate with Replicate           |
+| Command          | Job To Be Done                        |
+| ---------------- | ------------------------------------- |
+| `cog init`       | Bootstrap a new model project         |
+| `cog build`      | Create a container image              |
+| `cog run`        | Run a prediction in a container       |
+| `cog exec`       | Run arbitrary commands in a container |
+| `cog serve`      | Start HTTP server in a container      |
+| `cog playground` | Open a local UI for a model API       |
+| `cog push`       | Deploy to Replicate                   |
+| `cog login`      | Authenticate with Replicate           |
 
 ## Development Commands
 
@@ -98,6 +99,21 @@ Builds the image (if needed) and starts a container running the [Container Runti
 
 **Code**: `pkg/cli/serve.go`
 
+### cog playground
+
+**Job**: Explore and call a running Cog HTTP API from a browser.
+
+```bash
+cog serve -p 8393
+cog playground --target http://localhost:8393
+```
+
+The command serves an embedded React application and reverse-proxies its requests to the selected model API. Each browser tab is an independent workspace: every request carries that tab's target, and the proxy keeps no shared current-target state, so tabs can use the same or different models concurrently. The UI and proxy accept only loopback connections, even when `--host 0.0.0.0` is used so a container can deliver webhooks. The proxy snapshots upstream response headers into encoded metadata so the request inspector can show model values without including or merging playground security and transport headers. Webhook URLs contain an opaque per-prediction token, which also isolates concurrent tab subscriptions, and payloads are relayed to the browser over server-sent events.
+
+The proxy is intentionally user-directed: this is a local development tool for APIs selected by the user, not a remotely hosted gateway. CLI and release builds compile `playground/` into ignored assets under `pkg/cli/playground/`, then embed them in the Go binary. Ordinary Go tests use a build-time stub, so a clean Go checkout does not require Node; binaries built without the asset tag reject the playground command with build instructions.
+
+**Code**: `pkg/cli/` owns the server and embedded assets; `playground/` owns the frontend source.
+
 ## Build Commands
 
 ### cog build
@@ -219,6 +235,7 @@ pkg/cli/
 ├── predict.go      # prediction execution and legacy cog predict
 ├── exec.go         # cog exec
 ├── serve.go        # cog serve
+├── playground.go   # cog playground and local proxy
 ├── push.go         # cog push
 ├── login.go        # cog login
 └── init.go         # cog init

docs/cli.md

@@ -175,6 +175,49 @@ cog login [flags]
       --token-stdin   Pass login token on stdin instead of opening a browser. You can find your Replicate login token at https://replicate.com/auth/token
 ```
 
+## `cog playground`
+
+Open a browser playground for talking to a running model.
+
+Starts a local web server that serves a schema-driven UI (a Postman-like tool
+for Cog models). Point it at any running Cog HTTP API -- for example one started
+with 'cog serve' -- and the playground reflects that model's inputs and outputs
+from its OpenAPI schema in real time.
+
+Requests are reverse-proxied through this server, so the target API does not
+need to set CORS headers. The server also hosts a webhook sink so async
+predictions can be observed in the browser.
+
+Async/webhook testing against a containerized model requires the webhook URL to
+be reachable from inside the container. On Docker Desktop the default
+'host.docker.internal' works once the server listens on a reachable interface
+(e.g. --host 0.0.0.0).
+
+```
+cog playground [flags]
+```
+
+**Examples**
+
+```
+  # Start a model API in one terminal
+  cog serve -p 8393
+
+  # Open the playground pointing at it
+  cog playground --target http://localhost:8393
+```
+
+**Options**
+
+```
+  -h, --help                  help for playground
+      --host string           Address to bind (use 0.0.0.0 to receive webhooks from containers) (default "127.0.0.1")
+      --no-open               Do not open the browser automatically
+  -p, --port int              Port to listen on (0 picks a free port)
+      --target string         Default target model API URL (default "http://localhost:8393")
+      --webhook-host string   Hostname the model uses to reach this server for webhooks (default "host.docker.internal")
+```
+
 ## `cog push`
 
 Build a Docker image from cog.yaml and push it to a container registry.

pkg/cli/root.go

@@ -60,6 +60,7 @@ https://github.com/replicate/cog`,
 		newPushCommand(),
 		newExecCommand(),
 		newServeCommand(),
+		newPlaygroundCommand(),
 		newTrainCommand(),
 		newWeightsCommand(),
 	)