@replayio/app-building 1.1.0 → 1.3.0

package/README.md

@@ -33,11 +33,12 @@ const config: ContainerConfig = {
   flyApp: envVars.FLY_APP_NAME,
 };
 
-// Start a remote container
+// Start a remote container (detached — will exit after processing all work)
+config.detached = true;
 const repo: RepoOptions = { repoUrl: "https://github.com/...", cloneBranch: "main", pushBranch: "main" };
 const state = await startRemoteContainer(config, repo);
 
-// Send a prompt and wait for completion
+// Send a prompt — the container will process it and exit when done
 const httpOpts = httpOptsFor(state);
 const { id } = await httpPost(`${state.baseUrl}/message`, { prompt: "Build the app" }, httpOpts);
 
@@ -57,7 +58,7 @@ await stopRemoteContainer(config, state);
 
 | Export | Description |
 |---|---|
-| `ContainerConfig` | Interface bundling all external state: optional `projectRoot` (only needed for local Docker operations), `envVars`, `registry`, optional `flyToken`/`flyApp`/`imageRef`/`webhookUrl`. See [Webhooks](#webhooks) below. |
+| `ContainerConfig` | Interface bundling all external state: optional `projectRoot` (only needed for local Docker operations), `envVars`, `registry`, optional `flyToken`/`flyApp`/`imageRef`/`webhookUrl`/`detached`. See [Webhooks](#webhooks) and [Container lifecycle](#container-lifecycle) below. |
 | `RepoOptions` | Per-invocation git settings: `repoUrl`, `cloneBranch`, `pushBranch`. |
 | `ContainerRegistry` | Interface for container registry storage. Methods: `log`, `markStopped`, `clearStopped`, `getRecent`, `find`, `findAlive`. |
 | `FileContainerRegistry` | Built-in file-backed implementation of `ContainerRegistry`, backed by a `.jsonl` file. |
@@ -123,9 +124,41 @@ await stopRemoteContainer(config, state);
 |---|---|
 | `getImageRef()` | Returns `CONTAINER_IMAGE_REF` env var, or `ghcr.io/replayio/app-building:latest` by default. Used by `startRemoteContainer`. |
 
+## Container HTTP API
+
+Each container runs an HTTP server that accepts the following requests:
+
+| Method | Path | Description |
+|---|---|---|
+| `POST /message` | `{ prompt: string }` | Queue a message for processing. Returns `{ id }`. |
+| `GET /message/:id` | | Poll message status. Returns `{ id, status, result, error }`. |
+| `POST /detach` | | Signal the container to exit once all queued messages and tasks are done. |
+| `POST /stop` | | Force-stop the container immediately. Interrupts any running work, commits remaining changes, then exits. |
+| `POST /interrupt` | | Kill the currently running Claude process without stopping the container. |
+| `GET /status` | | Container state, queue depth, iteration count, cost, revision, etc. |
+| `GET /events?offset=N` | | Stream of Claude events (JSON lines) since offset. |
+| `GET /logs?offset=N` | | Stream of log lines since offset. |
+
+### Container lifecycle
+
+A container stays running and accepts messages until it receives a **detach** or **stop** signal:
+
+- **Detached at startup** (`config.detached = true`): Set `detached` on `ContainerConfig` to start
+  the container in detached mode. The container processes its initial message and any queued tasks,
+  then exits cleanly. This is the preferred way to run fire-and-forget jobs — no race between
+  container startup and a subsequent `POST /detach`.
+- **Detach** (`POST /detach`): Signal a running container to exit once all in-flight and queued
+  work is done. In the CLI, interactive mode (`npm run agent -- -i`) sends `/detach` automatically
+  when the user disconnects (Ctrl+C/D).
+- **Stop** (`POST /stop`): The container exits immediately, interrupting any running Claude
+  process. It commits any remaining work before shutting down. This is the forced shutdown path.
+
+Without either signal, the container waits indefinitely for new messages — this is intentional
+so that interactive users can send follow-up messages at any time.
+
 ## Webhooks
 
-Set `webhookUrl` on `ContainerConfig` to receive real-time notifications of container activity. The container POSTs fire-and-forget JSON to that URL on key events (no retries, failures are silently ignored).
+Set `webhookUrl` on `ContainerConfig` to receive real-time notifications of container activity. The container POSTs JSON to that URL on key events (no retries; failures are logged to stderr). If `WEBHOOK_SECRET` is set in the environment, the container sends it as a `Bearer` token in the `Authorization` header.
 
 ### Payload format
 

package/dist/container.d.ts

@@ -15,6 +15,8 @@ export interface ContainerConfig {
     flyApp?: string;
     imageRef?: string;
     webhookUrl?: string;
+    /** Start the container in detached mode. It will exit after processing all messages and tasks. */
+    detached?: boolean;
 }
 export interface RepoOptions {
     repoUrl: string;

package/dist/container.js

@@ -100,6 +100,8 @@ export async function startContainer(config, repo) {
     };
     if (config.webhookUrl)
         extra.WEBHOOK_URL = config.webhookUrl;
+    if (config.detached)
+        extra.DETACHED = "1";
     const containerEnv = buildContainerEnv(repo, config.envVars, extra);
     // Build docker run args
     const args = ["run", "-d", "--rm", "--name", containerName];
@@ -174,10 +176,9 @@ export async function startRemoteContainer(config, repo) {
     };
     if (config.webhookUrl)
         remoteExtra.WEBHOOK_URL = config.webhookUrl;
+    if (config.detached)
+        remoteExtra.DETACHED = "1";
     const containerEnv = buildContainerEnv(repo, config.envVars, remoteExtra);
-    // Remove Fly-specific vars from container env (not needed inside)
-    delete containerEnv.FLY_API_TOKEN;
-    delete containerEnv.FLY_APP_NAME;
     // Log existing machines (but don't destroy — multiple containers may run concurrently)
     const existing = await listMachines(config.flyApp, config.flyToken);
     if (existing.length > 0) {

package/dist/fly.js

@@ -63,11 +63,12 @@ export async function createMachine(app, token, image, env, name) {
             config: {
                 image,
                 env,
+                auto_destroy: true,
                 restart: { policy: "no" },
                 guest: {
-                    cpu_kind: "shared",
-                    cpus: 4,
-                    memory_mb: 4096,
+                    cpu_kind: "performance",
+                    cpus: 16,
+                    memory_mb: 32768,
                 },
                 services: [
                     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@replayio/app-building",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Library for managing agentic app-building containers",
   "type": "module",
   "exports": {