### Notion Channel Setup

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/ecosystem/channels/notion.md

Example of setting up the Notion channel, including client initialization and webhook handling.

```typescript
import { Client } from '@notionhq/client';
import { createNotionChannel } from '@flue/notion';
import { dispatch } from '@flue/runtime';
import assistant from '../agents/assistant.ts';

export const client = new Client({ auth: process.env.NOTION_TOKEN! });

export const channel = createNotionChannel({
  verificationToken: process.env.NOTION_WEBHOOK_VERIFICATION_TOKEN!,
  async webhook({ event }) {
    if (event.type !== 'page.content_updated') return;

    await dispatch(assistant, {
      id: `notion-page:${encodeURIComponent(event.entity.id)}`,
      input: {
        type: `notion.${event.type}`,
        deliveryId: event.id,
        pageId: event.entity.id,
      },
    });
  },
});
```

--------------------------------

### Start Flue Development Server

Source: https://github.com/withastro/flue/blob/main/examples/braintrust/README.md

Starts the Node.js development server for the Flue application from the example directory.

```bash
pnpm exec flue dev
```

--------------------------------

### Develop Custom Sandbox Example

Source: https://github.com/withastro/flue/blob/main/examples/imported-skill/README.md

Starts local development for the custom sandbox example targeting Cloudflare Workers. This utilizes the Vite/workerd integration.

```bash
pnpm exec flue dev --target cloudflare
```

--------------------------------

### Stripe Channel Module Example

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/ecosystem/channels/stripe.md

This example demonstrates the setup and usage of the Stripe channel module. It includes client initialization, webhook event handling for checkout sessions, and a tool for retrieving customer information.

```typescript
import Stripe from 'stripe';
import { createStripeChannel } from '@flue/stripe';
import { defineTool, dispatch } from '@flue/runtime';
import billing from '../agents/billing.ts';

export const client = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  httpClient: Stripe.createFetchHttpClient(),
});

export const channel = createStripeChannel({
  client,
  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,

  // Path: /channels/stripe/webhook
  async webhook({ event }) {
    switch (event.type) {
      case 'checkout.session.completed':
      case 'checkout.session.async_payment_succeeded': {
        const session = event.data.object;
        const customerId =
          typeof session.customer === 'string' ? session.customer : session.customer?.id;
        if (!customerId) return;

        await dispatch(billing, {
          id: customerId,
          input: {
            type: `stripe.${event.type}`,
            eventId: event.id,
            checkoutSessionId: session.id,
          },
        });
        return;
      }
      default:
        return;
    }
  },
});

export function retrieveCustomer(customerId: string) {
  return defineTool({
    name: 'retrieve_stripe_customer',
    description: 'Retrieve the Stripe customer bound to this billing agent.',
    parameters: {
      type: 'object',
      properties: {},
      additionalProperties: false,
    },
    async execute() {
      const customer = await client.customers.retrieve(customerId);
      return JSON.stringify(
        'deleted' in customer
          ? { id: customer.id, deleted: true }
          : { id: customer.id, name: customer.name, email: customer.email },
      );
    },
  });
}

```

--------------------------------

### Build and Type Checking for a Provider Example

Source: https://github.com/withastro/flue/blob/main/plans/2026-06-13-multi-platform-first-party-channels.md

Commands to check types and build a specific provider's example.

```sh
pnpm --filter <provider>-channel-example run check:types
pnpm --filter <provider>-channel-example run build
```

--------------------------------

### Install Flue Packages and Initialize Project

Source: https://github.com/withastro/flue/blob/main/apps/www/src/pages/blog/flue-1-0-beta.mdx

Install the necessary Flue runtime and CLI packages, then initialize a new Flue project.

```sh
npm install @flue/runtime
npm install -D @flue/cli
npx flue init
```

--------------------------------

### Initialize boxd VM and create Flue agent

Source: https://github.com/withastro/flue/blob/main/blueprints/sandbox--boxd.md

Example demonstrating how to initialize a boxd Compute client, create a boxd VM, and then wrap it with the boxd adapter for use in a Flue agent. This setup is useful for per-session agents requiring a full OS environment.

```typescript
import { Compute } from '@boxd-sh/sdk';
import { boxd } from './sandboxes/boxd';

const client = new Compute({ apiKey: process.env.BOXD_API_KEY });
const box = await client.box.create({ name: 'my-agent' });
const agent = createAgent(() => ({ sandbox: boxd(box), model: 'anthropic/claude-sonnet-4-6' }));
const harness = await init(agent);
const session = await harness.session();
```

--------------------------------

### Install Flue and Initialize Project

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/getting-started/quickstart.mdx

Installs the Flue runtime and CLI, and initializes the project configuration. It also sets up an environment variable for LLM provider credentials.

```bash
npm install @flue/runtime
npm install --save-dev @flue/cli
echo 'ANTHROPIC_API_KEY="your-api-key"' > .env
npx flue init --target node # or: --target cloudflare
```

--------------------------------

### Initialize E2B Sandbox and Flue Agent

Source: https://github.com/withastro/flue/blob/main/blueprints/sandbox--e2b.md

Example of creating an E2B sandbox, adapting it for Flue, and initializing a Flue agent with it. Ensure the E2B SDK is installed and imported.

```typescript
import { Sandbox } from 'e2b';
import { e2b } from './sandboxes/e2b';

const sandbox = await Sandbox.create();
const agent = createAgent(() => ({ sandbox: e2b(sandbox), model: 'anthropic/claude-sonnet-4-6' }));
const harness = await init(agent);
const session = await harness.session();
```

--------------------------------

### Start a development server with a custom environment file

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/cli/dev.md

Starts a local development server and loads environment variables from a specified file. This allows for different configurations during development.

```bash
flue dev --env .env.staging
```

--------------------------------

### Start a basic development server

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/cli/dev.md

Starts a local development server with default settings. This is the simplest way to begin developing your Flue project.

```bash
flue dev
```

--------------------------------

### Install Flue React and SDK Packages

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/guide/react.md

Install the necessary packages for React integration and the core SDK.

```sh
pnpm add @flue/react @flue/sdk
```

--------------------------------

### Run Custom Bash Sandbox Example

Source: https://github.com/withastro/flue/blob/main/examples/imported-skill/README.md

Executes the 'with-custom-bash' example using Node.js, which utilizes a customized bash sandbox.

```bash
pnpm exec flue run with-custom-bash --target node
```

--------------------------------

### Install Workspace Dependencies

Source: https://github.com/withastro/flue/blob/main/examples/braintrust/README.md

Installs all necessary dependencies for the project using pnpm.

```bash
pnpm install
```

--------------------------------

### Run Imported Skill Example

Source: https://github.com/withastro/flue/blob/main/examples/imported-skill/README.md

Executes the 'with-imported-skill' example using Node.js. Requires an Anthropic API key set in the specified .env file.

```bash
pnpm exec flue run with-imported-skill --target node --env ../../.env
```

--------------------------------

### Install E2B Dependency

Source: https://github.com/withastro/flue/blob/main/blueprints/sandbox--e2b.md

Install the 'e2b' package to use the sandbox adapter. Use your package manager's add command.

```bash
npm install e2b@^2.30.0
```

--------------------------------

### Start a Node.js development server

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/cli/dev.md

Starts a local development server specifically targeting Node.js. This is useful for server-side rendering or backend logic.

```bash
flue dev --target node
```

--------------------------------

### Set Up Node.js Project

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/ecosystem/deploy/node.md

Initialize a new project, set up npm, and install necessary Flue runtime and CLI packages.

```bash
mkdir my-flue-server && cd my-flue-server
npm init -y
npm install @flue/runtime valibot
npm install -D @flue/cli
```

--------------------------------

### Slack Example: Chat Stream

Source: https://github.com/withastro/flue/blob/main/plans/2026-06-13-multi-platform-first-party-channels.md

Demonstrates starting, appending, and stopping a chat stream request using fake Fetch responses in Workerd. This example executes requests without contacting Slack.

```typescript
import {
  SlackFunction,
  SlackResponse,
  SlackResponseError,
} from "@flue/slack";

export const chatStream: SlackFunction<
  "chatStream",
  { channel_id: string; text: string },
  { ok: true; ts: string } | SlackResponseError
> = async (props) => {
  const { channel_id, text } = props.inputs;
  const result = await props.client.chatStream.start({
    channel_id,
    text,
  });
  // Append to the stream
  await props.client.chatStream.append({
    stream_id: result.stream_id,
    text: "...and more!",
  });
  // Stop the stream
  await props.client.chatStream.stop({
    stream_id: result.stream_id,
  });
  return result;
};

```

--------------------------------

### Using the 'tail' parameter

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/api/streaming-protocol.md

The 'tail' query parameter can be used with GET routes for agents and workflow runs to specify the starting position as the last N events. It modifies the '-1' start sentinel.

```APIDOC
## GET /agents/support/{ticketId}

### Description
Retrieves agent support information, allowing specification of the last N events to consider using the `tail` parameter.

### Method
GET

### Endpoint
`/agents/support/{ticketId}`

### Parameters
#### Query Parameters
- **offset** (integer) - Optional - Specifies the starting position. Use `-1` to indicate from the beginning.
- **tail** (integer) - Required - Modifies the start sentinel to be 'from the beginning, but at most the last N events'. Must be an integer greater than or equal to 1.

### Request Example
```http
GET /agents/support/ticket-42?offset=-1&tail=100
```

## GET /runs/{runId}

### Description
Retrieves workflow run information, allowing specification of the last N events to consider using the `tail` parameter.

### Method
GET

### Endpoint
`/runs/{runId}`

### Parameters
#### Query Parameters
- **offset** (integer) - Optional - Specifies the starting position. Use `-1` to indicate from the beginning.
- **tail** (integer) - Required - Modifies the start sentinel to be 'from the beginning, but at most the last N events'. Must be an integer greater than or equal to 1.

### Request Example
```http
GET /runs/run_01JX...?offset=-1&tail=100
```
```

--------------------------------

### Initialize Flue Agent with Islo Sandbox

Source: https://github.com/withastro/flue/blob/main/blueprints/sandbox--islo.md

Example of how to create a Flue agent using the islo sandbox. Ensure the islo CLI is installed and accessible.

```typescript
import { islo } from './sandboxes/islo';

const agent = createAgent(() => ({
  sandbox: islo('my-sandbox'),
  model: 'anthropic/claude-sonnet-4-6',
}));
const harness = await init(agent);
```

--------------------------------

### Channel Namespace Example

Source: https://github.com/withastro/flue/blob/main/plans/2026-06-13-project-owned-channel-sdks-and-tools.md

Illustrates how filenames in the 'channels/' directory map to channel namespaces and provider routes.

```txt
src/channels/stripe.ts
```

```txt
channels/stripe.ts   -> /channels/stripe/webhook
channels/github.ts   -> /channels/github/webhook
channels/slack.ts    -> /channels/slack/events
                        /channels/slack/interactions
channels/discord.ts  -> /channels/discord/interactions
```

--------------------------------

### Build Runtime and CLI

Source: https://github.com/withastro/flue/blob/main/AGENTS.md

Build the runtime library before the CLI or examples. Run these commands from their respective package directories.

```shell
pnpm run build          # in packages/runtime/
pnpm run build          # in packages/cli/
```

--------------------------------

### Postgres Adapter with node-postgres Driver

Source: https://github.com/withastro/flue/blob/main/packages/postgres/README.md

Example of wrapping the node-postgres driver. The transaction function manages acquiring a client, starting a transaction, and releasing the client.

```typescript
import { postgres } from '@flue/postgres';
import { Pool } from 'pg';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

export default postgres({
  query: async (text, params) => (await pool.query(text, params)).rows,
  transaction: async (fn) => {
    const client = await pool.connect();
    try {
      await client.query('BEGIN');
      const result = await fn({ query: async (t, p) => (await client.query(t, p)).rows });
      await client.query('COMMIT');
      return result;
    } catch (error) {
      await client.query('ROLLBACK');
      throw error;
    } finally {
      client.release();
    }
  },
  close: () => pool.end(),
});
```

--------------------------------

### Initialize Flue Agent with Modal Sandbox

Source: https://github.com/withastro/flue/blob/main/blueprints/sandbox--modal.md

Example of initializing a Flue agent using a Modal sandbox. Ensure you have the Modal JS SDK installed and configured.

```typescript
import { ModalClient } from 'modal';
import { modal } from './sandboxes/modal';

const client = new ModalClient();
const app = await client.apps.fromName('my-app', { createIfMissing: true });
const image = client.images.fromRegistry('python:3.13-slim');
const sandbox = await client.sandboxes.create(app, image);

const agent = createAgent(() => ({ sandbox: modal(sandbox), model: 'anthropic/claude-sonnet-4-6' }));
const harness = await init(agent);
const session = await harness.session();
```

--------------------------------

### List All Documentation Pages

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/cli/docs.md

Run `flue docs` with no arguments to display usage hints and a full catalog of available documentation pages.

```bash
flue docs
```

--------------------------------

### Stream Agent Events Example

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/sdk/agents.md

Iterates over events from a persistent agent instance. Use offset to control the starting point and 'live: true' for future events.

```typescript
for await (const event of client.agents.stream('support', 'ticket-42', {
  offset: '-1',
  live: true,
})) {
  console.log(event.type);
  if (event.type === 'idle') break;
}
```

--------------------------------

### Salesforce Marketing Cloud Unsigned Callback Verification

Source: https://github.com/withastro/flue/blob/main/blueprints/channel--salesforce-marketing-cloud.md

Example JSON payload for verifying unsigned callbacks from Salesforce Marketing Cloud. This is used during the setup workflow.

```json
{
  "callbackId": "provider-callback-id",
  "verificationKey": "one-time-verification-key"
}
```

--------------------------------

### Intercom Channel Configuration

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/ecosystem/channels/intercom.md

Configures the Intercom channel, including client creation and webhook handling. This example is abridged and omits environment setup and helper functions.

```typescript
import { createIntercomChannel, type IntercomConversationRef } from '@flue/intercom';
import { dispatch } from '@flue/runtime';
import assistant from '../agents/assistant.ts';
import { createIntercomClient } from '../intercom-client.ts';

export const client = createIntercomClient(process.env.INTERCOM_ACCESS_TOKEN!, { region: 'us' });

export const channel = createIntercomChannel({
  clientSecret: process.env.INTERCOM_CLIENT_SECRET!,
  async webhook({ notification }) {
    if (notification.topic !== 'conversation.user.replied') return;
    const conversationId = conversationIdFromItem(notification.data.item);
    if (!conversationId) return;

    const conversation: IntercomConversationRef = {
      workspaceId: notification.app_id,
      conversationId,
    };
    await dispatch(assistant, {
      id: channel.conversationKey(conversation),
      input: {
        type: 'intercom.conversation.user.replied',
        notificationId: notification.id,
        conversation: notification.data.item,
      },
    });
  },
});
```

--------------------------------

### Prepare Agent Workspace and Run Review

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/guide/workflows.md

This snippet demonstrates how to initialize an agent, write a document to its workspace, and prompt it to review the document and write findings to another file. It utilizes harness.fs for file operations.

```typescript
import { createAgent, type FlueContext } from '@flue/runtime';

const reviewer = createAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  cwd: '/workspace',
}));

export async function run({ init, payload }: FlueContext<{ document: string }>)
  const harness = await init(reviewer);
  await harness.fs.writeFile('document.md', payload.document);

  const session = await harness.session();
  await session.prompt('Review document.md and write your findings to review.md.');

  return { review: await harness.fs.readFile('review.md') };
}
```

--------------------------------

### Create Astro Project with Minimal Template

Source: https://github.com/withastro/flue/blob/main/apps/www/README.md

Use this command to initialize a new Astro project with the minimal template.

```bash
npm create astro@latest -- --template minimal
```

--------------------------------

### Get or Create Session

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/api/agent-api.md

Retrieves or creates a session within the harness. Defaults to the 'default' session. Session names starting with 'task:' are reserved for framework-owned detached task sessions.

```typescript
session(name?: string): Promise<FlueSession>;
```

--------------------------------

### Invoke a workflow and get run details

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/sdk/workflows.md

Starts a workflow run and returns its ID, stream URL, and an offset for event streaming. Use this when you need to monitor the run's progress or events.

```typescript
const run = await client.workflows.invoke('summarize', {
  payload: { text: 'Summarize this document.' },
});

console.log(run.runId); // "run_01JX..."
console.log(run.streamUrl); // "https://example.com/api/runs/run_01JX..."
console.log(run.offset); // "-1"
```

--------------------------------

### Initialize Mirage Workspace and Flue Agent

Source: https://github.com/withastro/flue/blob/main/blueprints/sandbox--mirage.md

Example demonstrating how to set up a Mirage workspace and integrate it with Flue's agent for sandbox operations. Requires Mirage SDK and Flue runtime.

```typescript
// flue-blueprint: sandbox/mirage@1
/**
 * Mirage adapter for Flue.
 *
 * Wraps an already-initialized Mirage `Workspace` (from
 * `@struktoai/mirage-node` or `@struktoai/mirage-browser`) into Flue's
 * SandboxFactory interface. The user constructs the Workspace and mounts
 * resources directly using the Mirage SDK — Flue just adapts it.
 *
 * @example
 * ```typescript
 * import { Workspace, RAMResource, MountMode } from '@struktoai/mirage-node';
 * import { mirage } from '../sandboxes/mirage';
 *
 * const ws = new Workspace({ '/data': new RAMResource() }, { mode: MountMode.WRITE });
 * const agent = createAgent(() => ({ sandbox: mirage(ws), model: 'anthropic/claude-sonnet-4-6' }));
 * const harness = await init(agent);
 * const session = await harness.session();
 * ```
 */
import { createSandboxSessionEnv, SandboxOperationUnsupportedError } from '@flue/runtime';
import type { SandboxApi, SandboxFactory, SessionEnv, FileStat } from '@flue/runtime';
import type { Workspace as MirageWorkspace } from '@struktoai/mirage-core';

export interface MirageAdapterOptions {
	/**
	 * Default working directory for `exec()` calls when the caller doesn't
	 * pass one. Mirage workspaces are rooted at `/` (mounts hang off this
	 * root), so `/` is the safe default. Pin to a specific writable mount
	 * (e.g. `/data`) if you want the agent to default to working there.
	 */
	cwd?: string;
}

/**
 * Quote a string for safe inclusion in a `bash`-style command line.
 * Mirage's shell executor parses POSIX-ish syntax, so the same single-quote
 * escape used for real bash works here.
 */
function shellQuote(value: string): string {
	return `'${value.replace(/'/g, `'\''`)}'`;
}

/**
 * Implements SandboxApi by wrapping a Mirage Workspace.
 *
 * Each Flue context maps onto a Mirage session (created lazily by id) so
 * that cwd, env, history, and lastExitCode stay isolated across agent
 * instances and workflow invocations. Harnesses initialized within the same
 * context intentionally reuse that Mirage session.
 *
 * Filesystem operations route through `workspace.fs.*` (Mirage's direct
 * VFS API) for read/write/readdir/stat/exists/single-level mkdir. 
 * Recursive `mkdir -p` shells out via `workspace.execute()` because
 * `WorkspaceFS` exposes only single-level `mkdir`. Removal stays on the
 * filesystem API and rejects unsupported recursive/force options.
 *
 * `cwd`, `env`, and `signal` (including `AbortSignal.timeout(...)`) all
 * pass directly through to `ExecuteOptions` — Mirage runs each call in an
 * isolated session for `cwd`/`env`, and observes the signal cooperatively
 * at LIST/PIPELINE/loop boundaries. No shell-prefix workarounds.
 */
class MirageSandboxApi implements SandboxApi {
	constructor(
		private workspace: MirageWorkspace,
		private flueContextId: string,
	) {}

	async readFile(path: string): Promise<string> {
		const bytes = await this.workspace.fs.readFile(path);
		return new TextDecoder('utf-8').decode(bytes);
	}

	async readFileBuffer(path: string): Promise<Uint8Array> {
		// Defensive copy: Mirage may hand back a view onto an internal buffer.
		const bytes = await this.workspace.fs.readFile(path);
		return new Uint8Array(bytes);
	}

	async writeFile(path: string, content: string | Uint8Array): Promise<void> {
		const bytes =
			typeof content === 'string' ? new TextEncoder().encode(content) : content;
		await this.workspace.fs.writeFile(path, bytes);
	}

	async stat(path: string): Promise<FileStat> {
		const s = await this.workspace.fs.stat(path);
		// Mirage's FileStat: { name, size: number|null, modified: string|null,
		// type: FileType|null }.
		return {
			isFile: s.type === 'file',
			isDirectory: s.type === 'directory',
			...(s.size === null ? {} : { size: s.size }),
			...(s.modified === null ? {} : { mtime: new Date(s.modified) }),
		};
	}

	async readdir(path: string): Promise<string[]> {
		// Mirage returns absolute paths; some implementations include a
		// trailing `/` for directories, which `lastIndexOf('/') + 1` would
		// turn into an empty string — strip those.
		const entries = await this.workspace.fs.readdir(path);
		return entries.map((p) => p.slice(p.lastIndexOf('/') + 1)).filter((n) => n.length > 0);
	}

	async exists(path: string): Promise<boolean> {
		return this.workspace.fs.exists(path);
	}
}
```

--------------------------------

### MongoDB Adapter Configuration in Flue

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/ecosystem/databases/mongodb.md

Example of a Flue MongoDB adapter setup. It connects to MongoDB using environment variables and passes a runner to the mongodb function. Ensure your MongoDB deployment supports transactions.

```ts
import { mongodb, type MongoOperations, type MongoRunner } from '@flue/mongodb';
import { MongoClient } from 'mongodb';

const client = new MongoClient(process.env.MONGODB_URL!);
await client.connect();

const db = client.db(process.env.MONGODB_DATABASE);
const runner: MongoRunner = {
  /* ... */
};

export default mongodb(runner);
```

--------------------------------

### Verify islo CLI Installation

Source: https://github.com/withastro/flue/blob/main/blueprints/sandbox--islo.md

After installing the islo CLI, run this command to confirm the installation was successful.

```bash
islo --version
```

--------------------------------

### Analyze Incident and Recommend Actions

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/guide/workflows.md

This snippet shows how to initialize an agent and use a session to analyze an incident description and recommend subsequent actions. It demonstrates sequential prompting within a single session.

```typescript
import { createAgent, type FlueContext } from '@flue/runtime';

const investigator = createAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
}));

export async function run({ init, payload }: FlueContext<{ incident: string }>)
  const harness = await init(investigator);
  const session = await harness.session();

  await session.prompt(`Analyze this incident:\n\n${payload.incident}`);
  const response = await session.prompt('Now recommend the next three actions.');

  return { recommendation: response.text };
}
```

--------------------------------

### createExeVm

Source: https://github.com/withastro/flue/blob/main/blueprints/sandbox--exedev.md

Creates a new VM via exe.dev's HTTPS API and waits for SSH readiness.

```APIDOC
## POST /exec (create VM)

### Description
Creates a VM using the `new` command via the exe.dev HTTPS API and waits for it to become SSH-ready.

### Method
POST

### Endpoint
https://exe.dev/exec

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Content-Type** (string) - Required - Must be 'text/plain'.

#### Request Body
- **command** (string) - Required - Should be `new [vm_name]` or just `new`.

### Request Example
```json
{
  "command": "new my-test-vm"
}
```

### Response
#### Success Response (200)
- **vm** (object) - Details of the created VM, including name, host, and port.

#### Error Response (non-200 status)
- Throws an `ExeDevError` if the API call fails or the response cannot be parsed.
```

--------------------------------

### Install Flue Dependencies

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/ecosystem/deploy/github-actions.md

Installs the necessary Flue runtime and CLI packages for your project.

```bash
mkdir my-flue-project && cd my-flue-project
npm init -y
npm install @flue/runtime valibot
npm install -D @flue/cli
```

--------------------------------

### Set Up Sandbox Environment with Files

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/ecosystem/deploy/cloudflare.md

Configure a virtual sandbox environment for an agent by creating directories and files before prompting. This allows agents to access and process context from files within their workspace.

```typescript
import { createAgent, type FlueContext, type WorkflowRouteHandler } from '@flue/runtime';

export const route: WorkflowRouteHandler = async (_c, next) => next();

const reporter = createAgent(() => ({ model: 'openai/gpt-5.5' }));

export async function run({ init, payload }: FlueContext<{ topic: string }>) {
  const harness = await init(reporter);
  const session = await harness.session();

  // The agent has a full virtual filesystem and shell.
  // Set up context files before prompting.
  await session.shell(`mkdir -p /workspace/data`);
  await session.shell(`cat > /workspace/data/config.json << 'EOF'
{
  "rules": ["Be concise", "Use bullet points", "Cite sources"],
  "tone": "professional"
}
EOF`);

  return await session.prompt(
    `Read the config in /workspace/data/config.json.
     Generate a report about: ${payload.topic}`,
  );
}
```

--------------------------------

### Create, Use, and Delete exe.dev VM with Flue

Source: https://github.com/withastro/flue/blob/main/blueprints/sandbox--exedev.md

This example demonstrates a full lifecycle: creating a new exe.dev VM using its HTTPS API, wrapping it with the exedev adapter, initializing the agent, and finally deleting the VM. It requires an EXE_API_TOKEN environment variable and the 'ssh2' package.

```typescript
import { createExeVm, deleteExeVm, exedev } from './sandboxes/exedev';

const vm = await createExeVm({ apiToken: process.env.EXE_API_TOKEN! });
try {
  const agent = createAgent(() => ({
    sandbox: exedev(vm),
    model: 'anthropic/claude-sonnet-4-6',
  }));
  const harness = await init(agent);
} finally {
  await deleteExeVm({ apiToken: process.env.EXE_API_TOKEN!, name: vm.name });
}
```

--------------------------------

### Testing Provider Example with Workerd

Source: https://github.com/withastro/flue/blob/main/plans/2026-06-13-multi-platform-first-party-channels.md

Command to run workerd tests for a specific provider's example.

```sh
pnpm --filter <provider>-channel-example run test:workerd
```

--------------------------------

### Agent System Prompt Example

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/ecosystem/deploy/cloudflare.md

Provides global context about the project for the agent. Sets the agent's persona and operational guidelines.

```markdown
You are a helpful assistant working on the my-project codebase.
Use the project's existing patterns and conventions.
```

--------------------------------

### Install OpenTelemetry Adapter and API

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/ecosystem/tooling/opentelemetry.md

Install the @flue/opentelemetry adapter and the OpenTelemetry API alongside an SDK and exporter for your deployment target.

```sh
pnpm add @flue/opentelemetry @opentelemetry/api
```

--------------------------------

### Initialize Provider SDK and Export Client

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/guide/channels.md

Initialize the provider's SDK and export the client from the channel module. This example uses Octokit for GitHub API interactions.

```typescript
import { defineTool } from '@flue/runtime';
import { Octokit } from '@octokit/rest';
import * as v from 'valibot';

export const client = new Octokit({
  auth: process.env.GITHUB_TOKEN,
});

export function commentOnIssue(ref: { owner: string; repo: string; issueNumber: number }) {
  return defineTool({
    name: 'comment_on_github_issue',
    description: 'Comment on the GitHub issue bound to this agent.',
    parameters: v.object({ body: v.string() }),
    async execute({ body }) {
      await client.rest.issues.createComment({
        owner: ref.owner,
        repo: ref.repo,
        issue_number: ref.issueNumber,
        body,
      });
      return 'Comment posted.';
    },
  });
}
```

--------------------------------

### Create Turso Database and Get Credentials

Source: https://github.com/withastro/flue/blob/main/apps/docs/src/content/docs/ecosystem/databases/turso.md

Use the Turso CLI to create a new database, retrieve its URL, and generate an authentication token. These are required for connecting your application.

```bash
turso db create flue-agents
turso db show --url flue-agents      # → TURSO_DATABASE_URL (libsql://…)
turso db tokens create flue-agents   # → TURSO_AUTH_TOKEN
```