Getting Started with Godspeed

This guide provides a step-by-step guide to install and get started with Godspeed Meta-Framework. It covers the prerequisites and installation process, both manual and using easy installation scripts. You will learn how to create your first Godspeed project or service and run the development server.

New to the Godspeed Framework?

✅ Use Saarthi — our multi-agent team for VS Code. Install the extension and experience seamless coding, powered by Godspeed. No more stuck moments. Just prompt… and watch it code for you.

🛠️ And explore Godspeed Studio— a powerful visual editor for managing and building your Godspeed projects through an intuitive UI.

📚 Additionally, you can access the FAQs in Guides section

Install Godspeed

The following setup script installs all required prerequisites and the Godspeed runtime components automatically. This simplifies the onboarding process for new users by avoiding manual setup of individual dependencies.

Windows Users

Open Powershell as Administrator and run

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/zero8dotdev/install-godspeed-daemon/main/CompleteInstall.ps1" -OutFile "install.ps1"; Start-Process powershell -ArgumentList "-File .\install.ps1" -Verb RunAs

Mac/Linux Users

curl -fsSL https://raw.githubusercontent.com/zero8dotdev/install-godspeed-daemon/main/CompleteInstall.sh | bash

✅ The Script Will Install:

Component	Purpose
`nvm`	Node Version Manager - helps switch between Node.js versions
`node`	JavaScript runtime (installed via nvm)
`npm`	Node package manager (comes with Node.js)
`pnpm`	Efficient alternative to npm/yarn for managing dependencies
`corepack`	Node’s built-in tool for package manager handling
`git`	Version control system - required to clone repositories
`godspeed` CLI	Command-line interface to scaffold, run and manage services
`godspeed-daemon`	Core Godspeed runtime engine that executes workflows

Manual Installation

If you prefer manual setup, follow the steps below:

1. Ensure the Prerequisites are installed:

nvm (Node Version Manager)
node.js (v18 or higher, installed via nvm)
git
corepack (comes with Node.js)
pnpm (can be enabled via corepack: corepack enable pnpm)

2. Install the Godspeed framework globally:

npm install -g @godspeedsystems/godspeed

Verify Installation

Confirm successful installation:

godspeed --version

Creating Your First Project

Create a new project:

godspeed create my-project

Navigate to project directory:

cd my-project

Start the development server:

godspeed serve

Access Swagger UI

In Godspeed, the Swagger UI is typically accessed at the /api-docs endpoint, appended to the base URL and port where the server is running. Here’s the general format for accessing Swagger UI:

 http://<BASE_URL>:<PORT>/<http_docs_endpoint>` which is by default `localhost:3000/api-docs`

Default port of your service is 3000 and Swagger endpoint is /api-docs. If you want to customise default settings, you can modify the ./src/eventsources/http.yaml

To access Swagger UI, navigate to the following default url:

 http://localhost:3000/api-docs

Test the Helloworld API

In the Swagger UI, locate the /helloworld endpoint.

Click the Try it out button and send a request to test the API, It will ask you to fill the name. Once you fill and submit the name parameter,(e.g. John) then following response will be returned from the server.
```
  Hello `John`      
```

Troubleshooting

Common Issues

Running scripts is disabled on this system Solution: Run PowerShell as Administrator and execute:
```
Set-ExecutionPolicy RemoteSigned
```
Port Already in Use
```
Error: Port 3000 is already in use
```
Solution: Stop other services using port 3000 or modify port in src/eventsources/http.yaml

To understand working of this API Lets Walkthrough your first Godspeed Project

Walking through your first Godspeed project

Scaffolding of a meta-framework project

Scaffolding of a new project

The framework generates different folders like config, datasources, events, eventsources, functions, mappings, plugins,etc
The eslintrc.json file includes a curated list of recommended plugins that can be incorporated into the project.
We configure swagger specs in src/eventsources/http.yaml

tip

To understand more about the scaffolding structure of the project , Check here

Why is Swagger asking you to fill the name?

/helloworld API endpoint asks you to fill in the name parameter because the API has been configured to require this parameter as part of the query string. Go to src/events/helloworld.yaml file, which is the event schema of this API in YAML format.

  http.get./helloworld: # `http` server listening via `get` method on `/helloworld` endpoint
  fn: helloworld # the function handler to be called for this endpoint, available in `src/functions`
  params: # JSON-Schema of API parameters like query, headers, path params. Note: This is set as per Swagger standard's `parameters` syntax
    - name: name   # This is our name query param
      in: query    # Notice the in: query, it can be `path` or `headers` as well
      required: true # true means `name` parameter is required
      schema:
        type: string
  responses: # JSON-Schema of API responses for different status codes. Note: This is set as per Swagger standard's `responses` syntax
    200:
      content:
        application/json:
          schema:
            type: string

In this helloworld.yaml file, the params section defines that the API requires a name parameter to be passed in the query string. Let’s break it down:

params: This section describes the input the API expects. In this case, the API expects a name parameter, which must be provided by the user when they call the /helloworld endpoint.
name: name: This line specifies that the query parameter is called name.
in: query: This tells Swagger and the Godspeed server that the name parameter should be included in the query string of the URL (e.g., /helloworld?name=John).
required: true: The name parameter is mandatory. This means the API will not work unless this parameter is provided by the user.
schema: { type: string }: The name parameter must be a string, which further validates that the input should be text.

tip

In the Godspeed meta-framework each API whether REST or Graphql API is called an event. All events, whether API calls or websocket messages, trigger workflows/functions which can be thought of as event handlers (see fn: instruction in the yaml above). The sync events return a response while async events dont have a concept of response.

This naming approach may be new for you. The general norm across the larger developer community is to call only async events as events - for ex. Kafka or web socket message. But in Godspeed world we consider both sync APIs (REST, Graphql) and async events (Message bus, web socket, cron) - as events.

Testing the validation of API inputs and outputs

Almost every application needs validation of data sent in request to the API and response sent back by the service, to make sure that wrong data could not enter your service nor should it return wrong response for an API call. Let's try this feature in the framework.

Open your browser and hit the /helloworld endpoint via localhost:3000/helloworld. Or, run curl -i localhost:3000/helloworld from your terminal.
This should return an error with code 400 because you have not passed name in query - as expected by the schema of helloworld API.

{
  "validation_error": {
    "success": false,
    "code": 400,
    "message": "request validation failed.",
    "error": "must have required property 'name' in query",
    "data": {
      "message": "The API cannot be executed due to a failure in request params schema validation.",
      "error": {
        "instancePath": "",
        "schemaPath": "#/required",
        "keyword": "required",
        "params": {
          "missingProperty": "name"
        },
        "message": "must have required property 'name' in query"
      }
    }
  }
}

If you hit localhost:3000/helloworld?name=mastersilv3r, it should work.

Hello mastersilv3r

Swagger Collection

If you need access to the Swagger collection of godspeed project, open it from /docs folder in your project. This is automatically generated from your API schema which we saw above.

Postman Collection

If you need the Postman Collection, import the Swagger file from src/docs in Postman.

For any help

Try the below command line which will show you the commands that can be used in the godspeed framework. Refer the full CLI spec for more information, including how to add plugins for eventsources and datasources

   godspeed --help

Video Tutorial - Short

There is a longer and detailed introduction video as well, below on this page.

If you want some pre-made examples please check the examples repository

Video Tutorial - Longer and in depth

Walkthrough the Loan Origination System project made using our meta framework

New to the Godspeed Framework?​

Install Godspeed​

Windows Users​

Mac/Linux Users​

✅ The Script Will Install:​

Manual Installation​

Verify Installation​

Creating Your First Project​

Troubleshooting​

Common Issues​

Walking through your first Godspeed project​

Testing the validation of API inputs and outputs​

Swagger Collection​

Postman Collection​

For any help​

Video Tutorial - Short​

Video Tutorial - Longer and in depth​