Local development server

GenSX provides local development experience that mirrors the cloud environment, making it easy to build and test workflows on your machine before deploying them.

Starting the dev server

The gensx start command launches a local development server with hot-reloading:


gensx start ./src/workflows.tsx


🔍 Starting GenSX Dev Server...
ℹ Starting development server...
✔ Compilation completed
✔ Generating schema
Importing compiled JavaScript file: /Users/evan/code/gensx-console/samples/support-tools/dist/src/workflows.js
 
🚀 GenSX Dev Server running at http://localhost:1337
🧪 Swagger UI available at http://localhost:1337/swagger-ui
 
📋 Available workflows:
- RAGWorkflow: http://localhost:1337/workflows/RAGWorkflow
- AnalyzeDiscordWorkflow: http://localhost:1337/workflows/AnalyzeDiscordWorkflow
- TextToSQLWorkflow: http://localhost:1337/workflows/TextToSQLWorkflow
- ChatAgent: http://localhost:1337/workflows/ChatAgent
 
✅ Server is running. Press Ctrl+C to stop.

Development server features

Identical API shape

The local API endpoints match exactly what you’ll get in production, making it easy to test your workflows before deploying them. The only difference is that the /org/{org}/project/{project}/environments/{env} path is left out of the url for simplicity.


http://localhost:1337/workflows/{workflow}

Every workflow you export is automatically available as an API endpoint.

Hot reloading

The development server watches your TypeScript files and automatically:

Recompiles when files change
Regenerates API schemas
Restarts the server with your updated code

This enables a fast development cycle without manual restarts.

API documentation

The development server includes a built-in Swagger UI for exploring and testing your workflows:


http://localhost:1337/swagger-ui

Swagger UI for local development

The Swagger interface provides:

Complete documentation of all your workflow APIs
Interactive testing
Request/response examples
Schema information

Running workflows locally

Using the API

You can use any HTTP client to interact with your local API:


# Run a workflow synchronously
curl -X POST http://localhost:1337/workflows/ChatAgent \
  -H "Content-Type: application/json" \
  -d '{"input": {"prompt": "Tell me about GenSX"}}'
 
# Run asynchronously
 
curl -X POST http://localhost:1337/workflows/ChatAgent/start \
  -H "Content-Type: application/json" \
  -d '{"input": {"prompt": "Tell me about GenSX"}}'

The inputs and outputs of the APIs match exactly what you’ll encounter in production.

Using the Swagger UI

The built-in Swagger UI provides an easy way to inspect and test your workflows:

Navigate to http://localhost:1337/swagger-ui
Select the workflow you want to test
Click the “Try it out” button
Enter your input data
Execute the request and view the response

Run a workflow from the Swagger UI

Local storage options

GenSX provides local implementations for cloud storage services, enabling you to develop and test stateful workflows without deploying to the cloud.

Blob storage

When using BlobProvider in local development, data is stored in your local filesystem:


import { BlobProvider, useBlob } from "@gensx/storage";
 
const StoreData = gensx.Component("StoreData", async ({ key, data }) => {
  // Locally, this will write to .gensx/blobs directory
  const blob = useBlob(`data/${key}.json`);
  await blob.putJSON(data);
  return { success: true };
});

Files are stored in the .gensx/blobs directory in your project, making it easy to inspect the stored data.

SQL databases

When using DatabaseProvider locally, GenSX uses libSQL to provide a SQLite-compatible database:


import { DatabaseProvider, useDatabase } from "@gensx/storage";
 
const QueryData = gensx.Component("QueryData", async ({ query }) => {
  // Locally, this creates a SQLite database in .gensx/databases
  const db = await useDatabase("my-database");
  const result = await db.execute(query);
  return result.rows;
});

Database files are stored in the .gensx/databases directory as SQLite files that you can inspect with any SQLite client.

Vector search

For vector search operations with SearchProvider, your local environment connects to the cloud service:


import { SearchProvider, useSearch } from "@gensx/storage";
 
const SearchDocs = gensx.Component("SearchDocs", async ({ query }) => {
  // Uses cloud vector search even in local development
  const namespace = await useSearch("documents");
  const results = await namespace.query({
    text: query,
    topK: 5,
  });
  return results;
});