Development Setup
Build Ash from source and run it locally.
Prerequisites
- Node.js >= 20
- pnpm >= 9
- Docker (for sandbox isolation and
ash start)
Clone and Install
git clone https://github.com/ash-ai-org/ash.git
cd ash
pnpm install
pnpm build
Dev Commands
| Command | Description |
|---|---|
make build | Build all packages |
make test | Run unit tests |
make typecheck | Type-check all packages |
make test-integration | Run integration tests (starts real processes) |
make dev | Build Docker image, start server, deploy QA Bot agent, start QA Bot UI |
make dev-no-sandbox | Start server + QA Bot natively (no Docker, no sandbox isolation) |
make docker-build | Build local ash-dev Docker image |
make docker-start | Build image and start server in Docker |
make docker-stop | Stop the server container |
make docker-status | Show container status and health |
make docker-logs | Show container logs |
make kill | Kill processes on dev ports (4100, 3100) and stop Docker |
make clean | Remove build artifacts |
Quick Start (with Docker)
make dev
This builds the Docker image, starts the Ash server at http://localhost:4100, deploys the QA Bot example agent, and starts the QA Bot web UI at http://localhost:3100.
Quick Start (without Docker)
make dev-no-sandbox
This starts both the server and QA Bot natively. No sandbox isolation -- agent code runs in the same process context. Suitable for development when Docker is unavailable.
Running a Single Package
# Server only (native, with real Claude SDK)
ASH_REAL_SDK=1 pnpm --filter '@ash-ai/server' dev
# QA Bot web UI only (needs server running separately)
pnpm --filter qa-bot dev
# Build a single package
pnpm --filter '@ash-ai/shared' build
# Test a single package
pnpm --filter '@ash-ai/server' test
Using the CLI from Source
Instead of the globally installed ash, run the CLI directly with tsx:
npx tsx packages/cli/src/index.ts <command>
Examples:
# Start server with local dev image
npx tsx packages/cli/src/index.ts start --image ash-dev --no-pull
# Deploy an agent
npx tsx packages/cli/src/index.ts deploy ./examples/qa-bot/agent --name qa-bot
# Check status
npx tsx packages/cli/src/index.ts status
# Check health
npx tsx packages/cli/src/index.ts health
OpenAPI and Python SDK Generation
# Generate OpenAPI spec from Fastify route schemas
make openapi
# Generate Python SDK from OpenAPI spec (requires openapi-python-client)
make sdk-python
The OpenAPI spec is generated by starting the server, extracting the schema from Fastify's Swagger plugin, and writing it to packages/server/openapi.json (also copied to docs/openapi.json).
The Python SDK is generated from this spec using openapi-python-client, producing the packages/sdk-python/ package.