### Install and Run Ash Server

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/introduction.md

This snippet demonstrates how to install the Ash CLI globally and start the Ash server. The server manages agents, sessions, and exposes a REST API for interaction.

```bash
npm install -g @ash-ai/cli
ash start
```

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

### Quick Start Ash AI with Docker

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/contributing/development-setup.md

Builds the Docker image, starts the Ash server, deploys the QA Bot agent, and launches the QA Bot UI using the 'make dev' command.

```bash
make dev
```

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

### Starting Multiple ASH AI Coordinators for High Availability

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/self-hosting/multi-machine.md

This example demonstrates how to start two ASH AI coordinator instances. Both instances share the same database configuration (`ASH_DATABASE_URL`) but can be run on different hosts or ports. This setup is essential for creating a fault-tolerant control plane for ASH AI.

```bash
# Coordinator 1
ASH_MODE=coordinator \
ASH_DATABASE_URL="postgresql://ash:password@db-host:5432/ash" \
ASH_API_KEY=my-api-key \
ASH_INTERNAL_SECRET=my-runner-secret \
ANTHROPIC_API_KEY=sk-ant-... \
ASH_PORT=4100 \
node packages/server/dist/index.js

# Coordinator 2 (same config, different host)
ASH_MODE=coordinator \
ASH_DATABASE_URL="postgresql://ash:password@db-host:5432/ash" \
ASH_API_KEY=my-api-key \
ASH_INTERNAL_SECRET=my-runner-secret \
ANTHROPIC_API_KEY=sk-ant-... \
ASH_PORT=4100 \
node packages/server/dist/index.js

```

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

### Setup Cloud Chat Environment

Source: https://github.com/ash-ai-org/ash-ai/blob/main/examples/cloud-chat/README.md

Copies the example environment file to a local configuration file for the Cloud Chat example. This file should then be edited with the user's API key obtained from the Ash Cloud Platform.

```bash
cd examples/cloud-chat
cp .env.example .env.local

# Edit .env.local with your API key
```

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

### Coordinator Startup Log Example

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/self-hosting/multi-machine.md

This log message indicates that an ASH AI coordinator has successfully started. It includes the mode of operation ('coordinator'), the listening address ('0.0.0.0:4100'), and a unique identifier for the coordinator instance (e.g., 'ip-10-0-1-5-12345'), which is a combination of hostname and process ID.

```text
Ash server listening on 0.0.0.0:4100 (mode: coordinator, id: ip-10-0-1-5-12345)

```

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

### TypeScript SDK

Source: https://github.com/ash-ai-org/ash-ai/blob/main/docs/docusaurus-plan/06-sdks.md

Guide to installing and using the Ash AI TypeScript SDK, including client setup, method references for agents, sessions, messages, and files, along with a streaming example and helper functions.

```APIDOC
## TypeScript SDK

### Description

This section details the Ash AI TypeScript SDK, covering installation, client setup, and a comprehensive reference of available methods for managing agents, sessions, messages, and files. It also includes a practical streaming example and descriptions of utility helper functions.

### Installation

```bash
npm install @ash-ai/sdk
```

### Client Setup

```typescript
import { AshClient } from '@ash-ai/sdk';

const client = new AshClient({
  serverUrl: 'http://localhost:4100',
  apiKey: 'your-api-key', // optional
});
```

### Methods Reference

**Agents:**
- `client.deployAgent(name, path)` - Deploy agent from local folder
- `client.listAgents()` - List all agents
- `client.getAgent(name)` - Get agent by name
- `client.deleteAgent(name)` - Delete agent

**Sessions:**
- `client.createSession(agent)` - Create session
- `client.listSessions(agent?)` - List sessions
- `client.getSession(id)` - Get session
- `client.pauseSession(id)` - Pause session
- `client.resumeSession(id)` - Resume session
- `client.endSession(id)` - End session

**Messages:**
- `client.sendMessage(sessionId, content, opts?)` - Raw Response
- `client.sendMessageStream(sessionId, content, opts?)` - Async generator of `AshStreamEvent`

**Files:**
- `client.getSessionFiles(sessionId)` - List workspace files
- `client.getSessionFile(sessionId, path)` - Read file content

**Health:**
- `client.health()` - Server status

### Streaming Example

```typescript
import { AshClient, extractTextFromEvent } from '@ash-ai/sdk';

const client = new AshClient({ serverUrl: 'http://localhost:4100' });

const session = await client.createSession('my-agent');

for await (const event of client.sendMessageStream(session.id, 'Hello!')) {
  if (event.type === 'message') {
    const text = extractTextFromEvent(event);
    if (text) process.stdout.write(text);
  }
}
```

### Helper Functions

- `extractDisplayItems(messages)` - Extract tool results, text blocks for display
- `extractTextFromEvent(event)` - Get text content from a message event
- `extractStreamDelta(event)` - Get incremental text delta for streaming UIs
- `parseSSEStream(stream)` - Low-level SSE parser (async generator)

### Types

All types re-exported from `@ash-ai/shared`:
- `Agent`, `Session`, `SessionStatus`
- `AshStreamEvent`, `AshMessageEvent`, `AshErrorEvent`, `AshDoneEvent`
- `HealthResponse`, `PoolStats`

**Source:** `packages/sdk/src/index.ts`, `packages/sdk/src/sse.ts`
```

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

### Run Cloud Chat Application

Source: https://github.com/ash-ai-org/ash-ai/blob/main/examples/cloud-chat/README.md

Installs project dependencies and starts the development server for the Cloud Chat example. After running, the application can be accessed at http://localhost:3200.

```bash
npm install
npm run dev
# Open http://localhost:3200
```

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

### Install and Use Python SDK

Source: https://github.com/ash-ai-org/ash-ai/blob/main/docs/docusaurus-plan/06-sdks.md

Instructions for installing the Ash AI Python SDK using pip and a basic usage example for client setup, agent deployment, and session creation.

```bash
pip install ash-ai-sdk
```

```python
from ash_sdk import AshClient

client = AshClient(server_url="http://localhost:4100", api_key="your-key")

# Deploy agent
client.deploy_agent("my-agent", "./my-agent")

# Create session
session = client.create_session("my-agent")

# Send message (streaming)
for event in client.send_message_stream(session.id, "Hello!"):
    if event.type == "message":
        print(event.data)
```

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

### Setup Ash Project from Source

Source: https://github.com/ash-ai-org/ash-ai/blob/main/CONTRIBUTING.md

Clones the Ash repository, navigates into the project directory, and installs dependencies and builds the project using pnpm.

```bash
git clone <repo-url> && cd ash
pnpm install
pnpm build
```

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

### Start Ash Server with Local Docker Image

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/getting-started/installation.md

Starts the Ash server using a locally built Docker image (e.g., 'ash-dev') and skips pulling the image from the registry.

```bash
ash start --image ash-dev --no-pull
```

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

### Install Ash CLI and Start Server with Docker

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/self-hosting/docker.md

This snippet shows the initial setup for running Ash AI via Docker. It involves installing the Ash CLI globally using npm and setting the ANTHROPIC_API_KEY environment variable before starting the server with 'ash start'.

```bash
npm install -g @ash-ai/cli

export ANTHROPIC_API_KEY=sk-ant-...
ash start
```

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

### View Startup Script Logs (Bash)

Source: https://github.com/ash-ai-org/ash-ai/blob/main/docs/guides/gce-deployment.md

This command connects to a GCE instance via SSH and displays the logs for the `google-startup-scripts.service`. It's crucial for troubleshooting VM setup issues, allowing you to see errors during the installation of Docker, Node.js, and other dependencies.

```bash
gcloud compute ssh ash-server --zone=us-east1-b
sudo journalctl -u google-startup-scripts.service -f
```

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

### Start Ash Coordinator Node

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/self-hosting/multi-machine.md

Starts the Ash server in coordinator mode, managing client requests and routing them to available runners. Requires environment variables for database connection, API keys, and internal secrets.

```bash
export ASH_MODE=coordinator
export ASH_DATABASE_URL="postgresql://ash:password@db-host:5432/ash"
export ASH_API_KEY=my-api-key
export ASH_INTERNAL_SECRET=my-runner-secret  # Required: authenticates runner registration
export ANTHROPIC_API_KEY=sk-ant-...

node packages/server/dist/index.js
# Or via Docker:
# ash start -e ASH_MODE=coordinator -e ASH_DATABASE_URL=... -e ASH_INTERNAL_SECRET=...
```

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

### Quick Start Ash AI without Docker

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/contributing/development-setup.md

Starts the Ash server and QA Bot natively without using Docker, suitable for environments where Docker is unavailable. Note that agent code runs in the same process context.

```bash
make dev-no-sandbox
```

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

### Ash AI SDK Usage

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/getting-started/quickstart.md

Integrate Ash AI into your applications using the provided SDKs. Examples are given for TypeScript, Python, and cURL, demonstrating how to create sessions, send messages, stream responses, and manage sessions programmatically.

```APIDOC
## Using the SDKs

For application development, utilize the Ash AI SDKs. The following examples show how to interact with the Ash AI API using TypeScript, Python, and cURL.

### TypeScript SDK

1.  **Installation:**
    ```bash
    npm install @ash-ai/sdk
    ```

2.  **Usage Example:**
    ```typescript
    import { AshClient } from '@ash-ai/sdk';

    const client = new AshClient({
      serverUrl: 'http://localhost:4100',
      apiKey: process.env.ASH_API_KEY,
    });

    // Create a session
    const session = await client.createSession('my-agent');

    // Send a message and stream the response
    for await (const event of client.sendMessageStream(session.id, 'What is a closure?')) {
      if (event.type === 'message') {
        process.stdout.write(event.data);
      }
    }

    // Clean up
    await client.endSession(session.id);
    ```

### Python SDK

1.  **Installation:**
    ```bash
    pip install ash-ai-sdk
    ```

2.  **Usage Example:**
    ```python
    from ash_ai import AshClient
    import os

    client = AshClient(
        server_url="http://localhost:4100",
        api_key=os.environ.get("ASH_API_KEY"),
    )

    # Create a session
    session = client.create_session("my-agent")

    # Send a message and stream the response
    for event in client.send_message_stream(session.id, "What is a closure?"):
        if event.type == "message":
            print(event.data, end="")

    # Clean up
    client.end_session(session.id)
    ```

### cURL Examples

1.  **Create Session:**
    ```bash
    curl -s -X POST http://localhost:4100/api/sessions \
      -H 'Content-Type: application/json' \
      -H "Authorization: Bearer $ASH_API_KEY" \
      -d '{"agent":"my-agent"}'
    ```

2.  **Send Message (SSE Stream):**
    ```bash
    curl -N -X POST http://localhost:4100/api/sessions/SESSION_ID/messages \
      -H 'Content-Type: application/json' \
      -H "Authorization: Bearer $ASH_API_KEY" \
      -d '{"content":"What is a closure?"}'
    ```

3.  **End Session:**
    ```bash
    curl -s -X DELETE http://localhost:4100/api/sessions/SESSION_ID \
      -H "Authorization: Bearer $ASH_API_KEY"
    ```
```

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

### Quick Start Deployment Script

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/self-hosting/ecs-fargate.md

This bash script provides a quick way to clone the Ash repository, configure environment variables, and initiate the deployment process to AWS ECS. It automates the setup and deployment, taking approximately 3-5 minutes to complete.

```bash
# Clone the repo
git clone https://github.com/ash-ai-org/ash.git
cd ash

# Create .env from the example
cp .env.example .env
# Edit .env with your credentials (see below)

# Deploy
./scripts/deploy-ecs.sh
```

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

### Inspect Cloud-Init Output for Setup Issues

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/self-hosting/ec2.md

SSH into the EC2 instance and examine the cloud-init output log to troubleshoot setup failures, such as prolonged Docker and Node.js installation. This log contains detailed information about the instance's initialization process.

```bash
ssh -i ~/.ssh/my-key.pem ubuntu@<PUBLIC_IP>
cat /var/log/cloud-init-output.log
```

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

### Use Ash CLI from Source

Source: https://github.com/ash-ai-org/ash-ai/blob/main/CONTRIBUTING.md

Explains how to execute the Ash CLI commands directly from the source code using `npx tsx`, providing examples for starting, deploying, and checking the status of Ash services.

```bash
npx tsx packages/cli/src/index.ts <command>

# For example:
npx tsx packages/cli/src/index.ts start --image ash-dev --no-pull
npx tsx packages/cli/src/index.ts deploy ./examples/qa-bot/agent --name qa-bot
npx tsx packages/cli/src/index.ts status
```

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

### Ash AI SDK Usage Example in TypeScript

Source: https://github.com/ash-ai-org/ash-ai/blob/main/packages/sdk/README.md

Demonstrates how to use the Ash AI SDK in TypeScript. It covers initializing the client, creating a session, streaming messages, and ending the session. Requires the SDK to be installed.

```typescript
import { AshClient } from '@ash-ai/sdk';

const client = new AshClient({ serverUrl: 'http://localhost:4100' });

// Create a session
const session = await client.createSession('my-agent');

// Stream messages
for await (const event of client.sendMessageStream(session.id, 'Hello!')) {
  if (event.type === 'message') {
    process.stdout.write(event.data);
  }
}

// End session
await client.endSession(session.id);
```

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

### Python SDK

Source: https://github.com/ash-ai-org/ash-ai/blob/main/docs/docusaurus-plan/06-sdks.md

Instructions for installing and using the Ash AI Python SDK, including basic usage examples for deploying agents, creating sessions, and sending messages.

```APIDOC
## Python SDK

### Description

This section provides guidance on the Ash AI Python SDK, including installation instructions and basic usage examples. The Python SDK is auto-generated from the OpenAPI specification.

### Installation

```bash
pip install ash-ai-sdk
```

### Usage

```python
from ash_sdk import AshClient

client = AshClient(server_url="http://localhost:4100", api_key="your-key")

# Deploy agent
client.deploy_agent("my-agent", "./my-agent")

# Create session
session = client.create_session("my-agent")

# Send message (streaming)
for event in client.send_message_stream(session.id, "Hello!"):
    if event.type == "message":
        print(event.data)
```

**Note:** Python SDK is auto-generated from OpenAPI spec. Link to generated docs.

**Source:** `packages/sdk-python/`
```

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

### Blaxel CLI Onboarding (Bash)

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/comparisons/blaxel.md

Illustrates the initial steps for onboarding with Blaxel using its command-line interface. This includes logging into the Blaxel service and initializing a new agent project.

```bash
bl login
bl init my-agent
```

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

### Start Ash Server with Custom Port

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/getting-started/installation.md

Starts the Ash server and exposes it on a custom port (e.g., 5000) instead of the default port 4100.

```bash
ash start --port 5000
```

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

### Interact with Ash AI using Python SDK

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/getting-started/quickstart.md

This Python code shows how to use the ash-ai-sdk to interact with Ash AI. It covers initializing the client, creating a session, sending messages with streaming responses, and ending the session. The SDK needs to be installed via pip.

```python
from ash_ai import AshClient
import os

client = AshClient(
    server_url="http://localhost:4100",
    api_key=os.environ.get("ASH_API_KEY"),
)

# Create a session
session = client.create_session("my-agent")

# Send a message and stream the response
for event in client.send_message_stream(session.id, "What is a closure?"):
    if event.type == "message":
        print(event.data, end="")

# Clean up
client.end_session(session.id);
```

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

### Deploy and Chat with an Agent using Ash CLI

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/getting-started/quickstart.md

This bash snippet shows how to deploy a locally defined agent and initiate a chat session with it using the Ash CLI. It also demonstrates how to continue a conversation within an existing session and how to end a session.

```bash
ash deploy ./my-agent --name my-agent
ash chat my-agent "What is a closure in JavaScript?"
ash chat --session 550e8400-e29b-41d4-a716-446655440000 "Now explain with an example"
ash session end 550e8400-e29b-41d4-a716-446655440000
```

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

### Example: Deploy and Interact with an Agent

Source: https://github.com/ash-ai-org/ash-ai/blob/main/docs/docusaurus-plan/05-cli-reference.md

Demonstrates a typical workflow for deploying a new agent, listing agents, and then interacting with a specific agent through sessions.

```bash
# Deploy a minimal agent
mkdir my-agent
echo "You are a code reviewer." > my-agent/CLAUDE.md
ash deploy ./my-agent --name code-reviewer

# List agents
ash agent list
# NAME            DEPLOYED
# code-reviewer   2 minutes ago

# Full session lifecycle example
SESSION=$(ash session create code-reviewer)
ash session send $SESSION "Review this function for bugs: ..."
ash session pause $SESSION
# ... later ...
ash session resume $SESSION
ash session send $SESSION "What about error handling?"
ash session end $SESSION
```

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

### Start Ash Server with Environment Variables

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/getting-started/installation.md

Starts the Ash server and passes additional environment variables to the Docker container. This can be used to configure various aspects of the server, such as snapshot URLs.

```bash
ash start --env ASH_SNAPSHOT_URL=s3://my-bucket/snapshots/
```

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

### Docusaurus Website Build Commands

Source: https://github.com/ash-ai-org/ash-ai/blob/main/docs/docusaurus-plan/10-docusaurus-setup.md

Provides essential commands for managing the Docusaurus website, including installing dependencies, starting a development server, building for production, and serving the production build locally.

```bash
cd website
npm install
npm run start    # Dev server at localhost:3000
npm run build    # Production build to build/
npm run serve    # Serve production build locally
```

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

### Interact with Ash AI using TypeScript SDK

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/getting-started/quickstart.md

This TypeScript code demonstrates how to use the @ash-ai/sdk to create an Ash AI client, establish a session with an agent, send messages, stream responses, and properly end the session. It requires the SDK to be installed via npm.

```typescript
import { AshClient } from '@ash-ai/sdk';

const client = new AshClient({
  serverUrl: 'http://localhost:4100',
  apiKey: process.env.ASH_API_KEY,
});

// Create a session
const session = await client.createSession('my-agent');

// Send a message and stream the response
for await (const event of client.sendMessageStream(session.id, 'What is a closure?')) {
  if (event.type === 'message') {
    process.stdout.write(event.data);
  }
}

// Clean up
await client.endSession(session.id);
```

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

### Define and Deploy an Ash Agent

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/introduction.md

This example shows how to create a simple AI agent by defining a directory with a CLAUDE.md system prompt. It then deploys this agent using the Ash CLI.

```bash
mkdir my-agent
echo "You are a helpful coding assistant." > my-agent/CLAUDE.md
ash deploy ./my-agent --name my-agent
```

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

### Create Session with Agent Template (HTTP API)

Source: https://github.com/ash-ai-org/ash-ai/blob/main/docs/future_tasks/sandbox-overlays.md

This API call demonstrates how a new session is created using a specified agent template. The system creates a sandbox workspace, applies the template (using copy-on-write or symlinking), and starts the bridge immediately, bypassing lengthy setup steps like dependency installation.

```http
POST /api/sessions (agent: "my-agent")
```

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

### Interact with Ash AI using curl

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/getting-started/quickstart.md

This set of curl commands demonstrates how to interact with the Ash AI API directly. It includes examples for creating a session, sending messages to a session (receiving Server-Sent Events), and ending a session. Ensure the ASH_API_KEY environment variable is set.

```bash
# Create a session
curl -s -X POST http://localhost:4100/api/sessions \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ASH_API_KEY" \
  -d '{"agent":"my-agent"}'

# Send a message (returns an SSE stream)
curl -N -X POST http://localhost:4100/api/sessions/SESSION_ID/messages \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ASH_API_KEY" \
  -d '{"content":"What is a closure?"}'

# End the session
curl -s -X DELETE http://localhost:4100/api/sessions/SESSION_ID \
  -H "Authorization: Bearer $ASH_API_KEY"
```

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

### Ash Server Start and Configuration

Source: https://github.com/ash-ai-org/ash-ai/blob/main/docs/getting-started.md

Steps to start the Ash server, including setting the API key and understanding the server output.

```APIDOC
## Ash Server Start and Configuration

### Description
Start the Ash server, which involves pulling the Docker image, launching the container, and waiting for it to become healthy. The server can auto-generate an API key or use a pre-configured one.

### Method
Command Line

### Starting the Server
Set your ANTHROPIC_API_KEY and then start the server:
```bash
export ANTHROPIC_API_KEY=sk-...
ash start
```

### Server Output Example
On first start, an API key is auto-generated and saved:
```
Pulling ghcr.io/ash-ai/ash:latest...
Starting Ash server...
Waiting for server to be ready...

API key auto-generated and saved to ~/.ash/config.json
  Key: ash_7kX9mQ2pL...

Ash server is running.
  URL:      http://localhost:4100
  Data dir: ~/.ash
```

Subsequent starts will reuse the existing key.

### Server Options

| Flag                    | Description                                             |
|-------------------------|---------------------------------------------------------|
| `--port <port>`         | Use a different port (default: 4100)                    |
| `--database-url "..."` | Use Postgres/CockroachDB instead of SQLite              |
| `--env KEY=VALUE`       | Pass extra environment variables to the container       |

### Checking Server Status
```bash
ash status
```
```

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

### Install Docusaurus OpenAPI Plugins

Source: https://github.com/ash-ai-org/ash-ai/blob/main/docs/docusaurus-plan/10-docusaurus-setup.md

Installs the necessary Docusaurus plugins for generating interactive API documentation from OpenAPI specifications. These plugins are optional but recommended for comprehensive API reference.

```bash
npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs
```

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

### Install and Set Up TypeScript SDK

Source: https://github.com/ash-ai-org/ash-ai/blob/main/docs/docusaurus-plan/06-sdks.md

Instructions for installing the Ash AI TypeScript SDK using npm and setting up a client instance with server URL and API key.

```bash
npm install @ash-ai/sdk
```

```typescript
import { AshClient } from '@ash-ai/sdk';

const client = new AshClient({
  serverUrl: 'http://localhost:4100',
  apiKey: 'your-api-key', // optional
});
```

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

### Clean Up Distributed Ash AI Deployment on AWS EC2

Source: https://github.com/ash-ai-org/ash-ai/blob/main/examples/deploy/README.md

This script is part of the EC2 distributed (multi-node) deployment example. It is used to clean up resources provisioned by the deploy.sh script for the coordinator and runner setup.

```bash
#!/bin/bash
# Clean up multi-node Ash AI deployment on AWS EC2
# ... (implementation details)
```

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

### Agent Deployment and Chat (CLI)

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/getting-started/quickstart.md

This section details how to define a simple agent using a CLAUDE.md file, deploy it using the Ash CLI, and then engage in a chat conversation with the deployed agent. It also shows how to manage chat sessions, including continuing conversations and ending sessions.

```APIDOC
## Define an Agent

An agent is a directory containing a `CLAUDE.md` file, which serves as the system prompt defining the agent's persona and behavior.

### Command Example
```bash
mkdir my-agent

cat > my-agent/CLAUDE.md << 'EOF'
You are a helpful coding assistant.
Answer questions about JavaScript and TypeScript.
Keep answers concise. Include working code examples.
EOF
```

## Deploy and Chat

Deploy the agent and start chatting with it. The response streams in real-time, and a session ID is provided for continued interaction.

### Commands

1.  **Deploy Agent:**
    ```bash
    ash deploy ./my-agent --name my-agent
    ```

2.  **Start Chat:**
    ```bash
    ash chat my-agent "What is a closure in JavaScript?"
    ```
    *Example Response:*
    ```
A closure is a function that retains access to variables from its enclosing
scope, even after the outer function has returned...
Session: 550e8400-e29b-41d4-a716-446655440000
    ```

3.  **Continue Chat (using Session ID):**
    ```bash
    ash chat --session 550e8400-e29b-41d4-a716-446655440000 "Now explain with an example"
    ```

4.  **End Session:**
    ```bash
    ash session end 550e8400-e29b-41d4-a716-446655440000
    ```

### One-Shot Messages

For single messages where follow-ups are not needed, use the `--end` flag to automatically end the session.

```bash
ash chat --end my-agent "What is a closure?"
```

## Detailed Session Management (Optional)

For more granular control over conversations, use the session commands directly.

### Commands

1.  **Create Session:**
    ```bash
    ash session create my-agent
    ```
    *Response Example:*
    ```json
    { "id": "550e8400-...", "status": "active", "agentName": "my-agent" }
    ```

2.  **Send Message:**
    ```bash
    ash session send SESSION_ID "What is a closure in JavaScript?"
    ```

3.  **Send Another Message:**
    ```bash
    ash session send SESSION_ID "Now explain it with an example"
    ```

4.  **End Session:**
    ```bash
    ash session end SESSION_ID
    ```
```

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

### Install Docusaurus Search Plugin (Bash)

Source: https://github.com/ash-ai-org/ash-ai/blob/main/docs/docusaurus-plan/10-docusaurus-setup.md

Commands to install a local search plugin for Docusaurus. This allows users to search documentation directly within the site without relying on external services.

```bash
# Option A: Local search (no external service)
npm install @easyops-cn/docusaurus-search-local

# Option B: Algolia DocSearch (free for open-source)
# Apply at https://docsearch.algolia.com/
```

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

### Start Ash AI with a Postgres-Compatible Database

Source: https://github.com/ash-ai-org/ash-ai/blob/main/docs/getting-started.md

This command demonstrates how to start the Ash AI CLI, connecting it to any Postgres-compatible database. Ash automatically creates necessary tables on the first startup, eliminating the need for manual migrations. The database URL is provided as a command-line argument.

```bash
ash start --database-url "postgresql://localhost:5432/ash"
```

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

### Create and Deploy an Agent

Source: https://github.com/ash-ai-org/ash-ai/blob/main/README.md

Demonstrates how to create a simple agent folder, define its system prompt, deploy it using the Ash CLI, and interact with it via sessions.

```bash
# Define an agent — it's just a folder
mkdir my-agent
cat > my-agent/CLAUDE.md << 'EOF'
You are a helpful coding assistant. Be concise and accurate.
When asked to write code, include working examples.
EOF

# Deploy and use it
ash deploy ./my-agent --name my-agent
ash session create my-agent
ash session send <SESSION_ID> "Write a prime number checker in Python"
```

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

### Install Ash with Kubernetes Secrets (Bash)

Source: https://github.com/ash-ai-org/ash-ai/blob/main/docs/guides/kubernetes-deployment.md

This snippet demonstrates how to create a Kubernetes secret containing Anthropic and Ash API keys, and then install the Ash Helm chart referencing this secret. It's a quick start for deploying Ash.

```bash
# Add your API key to a Kubernetes secret
kubectl create secret generic ash-secrets \
  --from-literal=ANTHROPIC_API_KEY=sk-ant-... \
  --from-literal=ASH_API_KEY=$(openssl rand -hex 32) \

# Install the chart
helm install ash ./charts/ash \
  --set auth.existingSecret=ash-secrets
```

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

### Create and Deploy First Agent

Source: https://github.com/ash-ai-org/ash-ai/blob/main/docs/docusaurus-plan/01-getting-started.md

Demonstrates creating a new agent directory with a system prompt and deploying it using the Ash CLI.

```bash
mkdir my-agent && echo "You are a helpful assistant." > my-agent/CLAUDE.md
ash deploy ./my-agent --name my-agent
```

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

### Start Ash Runner Node

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/self-hosting/multi-machine.md

Starts an Ash runner, responsible for managing sandbox pools and executing sessions. It registers with the coordinator and sends heartbeats. Requires environment variables for runner ID, coordinator URL, ports, and secrets.

```bash
export ASH_RUNNER_ID=runner-1
export ASH_SERVER_URL=http://coordinator-host:4100
export ASH_RUNNER_PORT=4200
export ASH_RUNNER_ADVERTISE_HOST=10.0.1.5  # IP the coordinator can reach
export ASH_MAX_SANDBOXES=50
export ASH_INTERNAL_SECRET=my-runner-secret  # Must match coordinator
export ANTHROPIC_API_KEY=sk-ant-...

node packages/runner/dist/index.js
```

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

### Connect QA Bot Example (Bash)

Source: https://github.com/ash-ai-org/ash-ai/blob/main/docs/guides/gce-deployment.md

This command connects the 'qa-bot' example agent to the running Ash AI server. It sets the `ASH_SERVER_URL` environment variable to the server's IP address and port, then runs the bot using `pnpm`. The bot's UI will be accessible via `http://localhost:3100`.

```bash
ASH_SERVER_URL=http://<your-gce-ip>:4100 pnpm --filter qa-bot dev
```

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

### Provision and Deploy Distributed Ash AI on AWS EC2

Source: https://github.com/ash-ai-org/ash-ai/blob/main/examples/deploy/README.md

This script is part of the EC2 distributed (multi-node) deployment example. It handles provisioning AWS resources for a coordinator and runner setup, and deploys Ash AI. A corresponding teardown script is available for cleanup.

```bash
#!/bin/bash
# Provision and deploy multi-node Ash AI on AWS EC2
# ... (implementation details)
```

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

### Get Agent API Response (JSON)

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/api/agents.md

Shows the JSON format for retrieving a single agent by its name using the GET /api/agents/:name endpoint. The response includes the details of the specified agent. An example error response for a non-existent agent is also provided.

```json
{
  "agent": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "qa-bot",
    "tenantId": "default",
    "version": 2,
    "path": "/home/user/agents/qa-bot",
    "createdAt": "2025-06-15T10:30:00.000Z",
    "updatedAt": "2025-06-16T14:00:00.000Z"
  }
}
```

```json
{
  "error": "Agent not found",
  "statusCode": 404
}
```

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

### Ash Server Sandbox Setup Process

Source: https://github.com/ash-ai-org/ash-ai/blob/main/docs/diagrams/ash-sidecar-mcp-integration.md

This outlines the internal process on the Ash Server for setting up a sandbox environment after receiving a session creation request. It involves resolving the agent, decrypting credentials, merging environment variables, and creating the sandbox.

```Text
1. Resolve agent folder
2. Decrypt credentials
3. Merge extraEnv
4. createSandbox()
```

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

### Ash AI Development Commands Overview

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/contributing/development-setup.md

Provides a list of Make commands for common development tasks such as building, testing, type checking, running integration tests, and managing Docker containers.

```bash
make build
make test
make typecheck
make test-integration
make dev
make dev-no-sandbox
make docker-build
make docker-start
make docker-stop
make docker-status
make docker-logs
make kill
make clean
```

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

### Define an Agent using Bash

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/getting-started/quickstart.md

This snippet demonstrates how to create a new agent directory and define its system prompt using a bash script. The CLAUDE.md file dictates the agent's persona and behavior.

```bash
mkdir my-agent

cat > my-agent/CLAUDE.md << 'EOF'
You are a helpful coding assistant.
Answer questions about JavaScript and TypeScript.
Keep answers concise. Include working code examples.
EOF
```

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

### View Ash Server Logs

Source: https://github.com/ash-ai-org/ash-ai/blob/main/website/docs/getting-started/installation.md

Displays the logs generated by the Ash server. The `-f` option allows for real-time log following.

```bash
ash logs
ash logs -f
```

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

### Get Session File using Ash SDK

Source: https://github.com/ash-ai-org/ash-ai/blob/main/docs/docusaurus-plan/03-guides.md

SDK method to read the content of a specific file from an agent's workspace for a given session.

```javascript
client.getSessionFile(sessionId, filePath);
```