Local development server

GenSX provides a 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.ts

🔍 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:

1. Recompiles when files change
2. Regenerates API schemas
3. 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

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:

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

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 useBlob in local development, data is stored in your local file system:

import { useBlob } from "@gensx/storage";
 
const StoreData = gensx.Component(
  "StoreData",
  async ({ key, data }: StoreDataInput) => {
    // 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 useDatabase locally, GenSX uses libSQL  to provide a SQLite-compatible database:

import { useDatabase } from "@gensx/storage";
 
const QueryData = gensx.Component(
  "QueryData",
  async ({ query }: QueryDataInput) => {
    // 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 useSearch, your local environment connects to the cloud service:

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

Next steps

• Deploying to production
• Working with cloud storage
• Setting up observability and tracing