Inngest

https://www.inngest.com/docs
Admin
Inngest is an event-driven durable execution platform that enables developers to run fast, reliable...
Tokens:579,246
Snippets:4,295
Trust Score:9.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Start Dev Server with Bash installer

Source: https://www.inngest.com/docs/getting-started

Installs the Inngest CLI via the Bash installer and starts the Dev Server, pointing to the app URL at http://localhost:3000/api/inngest.

```bash
curl -sSfL https://cli.inngest.com/install.sh | sh
inngest dev -u http://localhost:3000/api/inngest
```

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

### Install the Go SDK with go get

Source: https://www.inngest.com/docs/reference/go

Install the Inngest Go SDK using the go get command. This is the first step to using the SDK.

```bash
go get github.com/inngest/inngestgo@latest

```

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

### Install Inngest CLI and start Dev Server

Source: https://www.inngest.com/docs/durable-execution/quick-start/python-quick-start

Installs the Inngest CLI and starts the Dev Server pointing at the app's /api/inngest endpoint. Open http://localhost:8288 to view the app and functions.

```bash
curl -sSfL https://cli.inngest.com/install.sh | sh
inngest dev -u http://localhost:8000/api/inngest
```

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

### Start Dev Server with Brew

Source: https://www.inngest.com/docs/getting-started

Installs the Inngest CLI via Homebrew and starts the Dev Server, pointing to the app URL at http://localhost:3000/api/inngest.

```bash
brew install inngest/tap/inngest
inngest dev -u http://localhost:3000/api/inngest
```

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

### Create virtual environment and install dependencies

Source: https://www.inngest.com/docs/durable-execution/quick-start/python-quick-start

Sets up a Python 3.10+ virtual environment and installs fastapi, inngest, and uvicorn. Run these commands in a terminal before starting the app.

```bash
mkdir inngest-python-quickstart
cd inngest-python-quickstart
python -m venv .venv
source .venv/bin/activate
pip install fastapi inngest uvicorn
```

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

### Install SDK and run the app

Source: https://www.inngest.com/docs/durable-execution/quick-start/go-quick-start

Commands to fetch the Inngest Go SDK and start the app with INNGEST_DEV=1. The app runs on port 8080.

```bash
go get github.com/inngest/inngestgo@latest
INNGEST_DEV=1 go run .
```

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

### Set up the stephttp provider

Source: https://www.inngest.com/docs/reference/go/durable-endpoints

Create one provider when the process starts with stephttp.Setup and use it for every handler. Setup reads INNGEST_SIGNING_KEY, INNGEST_SIGNING_KEY_FALLBACK, INNGEST_ENV, and INNGEST_DEV from the environment. Set INNGEST_DEV=1 to send runs to the local Dev Server.

```go
import "github.com/inngest/inngestgo/stephttp"

// Create one provider when the process starts, and use it for every handler.
var steps = stephttp.Setup(stephttp.SetupOpts{})
```

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

### Install Inngest CLI and start Dev Server

Source: https://www.inngest.com/docs/durable-execution/quick-start/go-quick-start

Commands to install the Inngest CLI and start the Dev Server pointing at the app's /api/inngest endpoint. The Dev Server UI is at http://localhost:8288.

```bash
curl -sSfL https://cli.inngest.com/install.sh | sh
inngest dev -u http://localhost:8080/api/inngest
```

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

### Inngest Dev Server startup output

Source: https://www.inngest.com/docs/getting-started/tanstack-start-quick-start

Example output from running `inngest dev`. Shows the server starting and the URL to access the dev UI.

```js
$ inngest dev

12:33PM INF executor > service starting
12:33PM INF runner > starting event stream backend=redis
12:33PM INF executor > subscribing to function queue
12:33PM INF runner > service starting
12:33PM INF runner > subscribing to events topic=events
12:33PM INF no shard finder;  skipping shard claiming
12:33PM INF devserver > service starting
12:33PM INF devserver > autodiscovering locally hosted SDKs
12:33PM INF api > starting server addr=0.0.0.0:8288

        Inngest dev server online at 0.0.0.0:8288, visible at the following URLs:

         - http://127.0.0.1:8288 (http://localhost:8288)

        Scanning for available serve handlers.
        To disable scanning run `inngest dev` with flags: --no-discovery -u <your-serve-url>
```

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

### Start Inngest server with Docker

Source: https://www.inngest.com/docs/platform-and-operations/self-host-inngest

First-run example that generates an event key and a hexadecimal signing key, then passes both to the server. It does not mount the SQLite database, so removing the container also removes its local database.

```bash
export INNGEST_EVENT_KEY="replace-with-an-event-key"
export INNGEST_SIGNING_KEY="$(openssl rand -hex 32)"
docker run -p 8288:8288 -p 8289:8289 \
  -e INNGEST_EVENT_KEY -e INNGEST_SIGNING_KEY \
  inngest/inngest inngest start

```

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

### Install Python SDK

Source: https://www.inngest.com/docs/sdks

Install the Python SDK.

```shell
pip install inngest
```

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

### Install dependencies

Source: https://www.inngest.com/docs/getting-started/python-quick-start

Installs FastAPI, Inngest, and Uvicorn.

```sh
pip install fastapi inngest uvicorn
```

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

### Create project directory and initialize Go module

Source: https://www.inngest.com/docs/durable-execution/quick-start/go-quick-start

Commands to create a directory and initialize a Go module named quickstart-go. Run these in a terminal before writing any code.

```bash
mkdir inngest-go-quickstart
cd inngest-go-quickstart
go mod init quickstart-go
```

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

### TypeScript: Use from() to start jobs from another job's machine

Source: https://www.inngest.com/docs/labs/ci/machines

Shows how to define a base job that installs dependencies, then build and test jobs that start from the base or build job using from(). The parent runs once and each child gets an isolated copy. Call from() before the job's first command and once per job.

```TypeScript
const base = ci.job("base", async () => {
  await checkout();
  await $`pnpm install`;
});

const build = ci.job("build", async () => {
  await from(base);
  await $`pnpm build`;
});

const test = ci.job("test", async () => {
  await from(build);
  await $`pnpm test`;
});

```

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

### Go client setup

Source: https://www.inngest.com/docs/sdks

Create an Inngest client to define functions and send events.

```go
import "github.com/inngest/inngestgo"

func NewClient() (inngestgo.Client, error) {
	return inngestgo.NewClient(inngestgo.ClientOpts{
		AppID: "my-app",
	})
}
```

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

### Show Inngest start help

Source: https://www.inngest.com/docs/self-hosting

Displays all available options for the `inngest start` command, including configuration, advanced, and persistence flags. Useful for discovering configuration options.

```bash
$ inngest start --help
NAME:
   inngest start - [Beta] Run Inngest as a single-node service.

USAGE:
   inngest start [options]

DESCRIPTION:
   Example: inngest start

OPTIONS:
   --config string                                              Path to an Inngest configuration file
   --event-key string [ --event-key string ]                    Event key(s) that will be used by apps to send events to the server.
   --help, -h                                                   show help
   --host string                                                Inngest server hostname
   --port string, -p string                                     Inngest server port (default: "8288")
   --sdk-url string, -u string [ --sdk-url string, -u string ]  App serve URLs to sync (ex. http://localhost:3000/api/inngest)
   --signing-key string                                         Signing key used to sign and validate data between the server and apps. Must be hex string with even number of chars

   Advanced

   --connect-gateway-port int  Port to expose connect gateway endpoint (default: 8289)
   --no-ui                     Disable the web UI and GraphQL API endpoint (default: false)
   --poll-interval int         Interval in seconds between polling for updates to apps (default: 0)
   --queue-workers int         Number of executor workers to execute steps from the queue (default: 100)
   --retry-interval int        Retry interval in seconds for linear backoff when retrying functions - must be 1 or above (default: 0)
   --tick int                  The interval (in milliseconds) at which the executor polls the queue (default: 150)

   Persistence

   --postgres-conn-max-idle-time int  Sets the maximum amount of time, in minutes, a PostgreSQL connection may be idle. (default: 5)
   --postgres-conn-max-lifetime int   Sets the maximum amount of time, in minutes, a PostgreSQL connection may be reused. (default: 30)
   --postgres-max-idle-conns int      Sets the maximum number of idle database connections in the PostgreSQL connection pool. (default: 10)
   --postgres-max-open-conns int      Sets the maximum number of open database connections allowed in the PostgreSQL connection pool. (default: 100)
   --postgres-uri string              PostgreSQL database URI for configuration and history persistence. Defaults to SQLite database.
   --redis-uri string                 Redis server URI for external queue and run state. Defaults to self-contained, in-memory Redis server with periodic snapshot backups.
   --sqlite-dir string                Directory for where to write SQLite database.

```

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

### github.comment

Source: https://www.inngest.com/docs/labs/ci/reference

Starts a pipeline when a comment starts with `command`. Checks the author after the run starts; a user without the permission gets a reply and a neutral check.

```APIDOC
## github.comment

### Description
Starts a pipeline when a comment starts with `command`. Checks the author after the run starts; a user without the permission gets a reply and a neutral check.

### Method
github.comment

### Parameters
- **command** (string) - Required - The command prefix.
- **minPermission** (string) - Optional - Minimum permission required. With several `comment()` triggers, each command keeps its own `minPermission`.
- **repo** (string) - Optional - Repository to filter by.

### Response
Returns a trigger object.
```

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

### Install Go SDK

Source: https://www.inngest.com/docs/sdks

Add the Go SDK to your project.

```shell
go get github.com/inngest/inngestgo
```

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

### onRegister static hook example

Source: https://www.inngest.com/docs/reference/typescript/v4/middleware/lifecycle

Called once when the middleware class is registered with a client or function. Example use cases: one-time setup.

```typescript
class MyMiddleware extends Middleware.BaseMiddleware {
  id = "my-middleware";
  static onRegister({ client, functionInfo }: Middleware.OnRegisterArgs) {
    // One-time setup
  }
}

```

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

### Create a client and serve functions (main.go)

Source: https://www.inngest.com/docs/reference/go

Create a client with AppID, define a function triggered by app/task.created, and serve it over HTTP on /api/inngest. Uses step.Run to handle the task.

```go
package main

import (
	"context"
	"log"
	"net/http"

	"github.com/inngest/inngestgo"
	"github.com/inngest/inngestgo/step"
)

func main() {
	client, err := inngestgo.NewClient(inngestgo.ClientOpts{AppID: "my-app"})
	if err != nil {
		log.Fatal(err)
	}

	_, err = inngestgo.CreateFunction(
		client,
		inngestgo.FunctionOpts{ID: "process-task"},
		inngestgo.EventTrigger("app/task.created", nil),
		func(ctx context.Context, input inngestgo.Input[map[string]any]) (any, error) {
			return step.Run(ctx, "handle-task", func(ctx context.Context) (map[string]any, error) {
				return map[string]any{"processed": true}, nil
			})
		},
	)
	if err != nil {
		log.Fatal(err)
	}

	http.Handle("/api/inngest", client.Serve())
	log.Fatal(http.ListenAndServe(":8080", nil))
}

```

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

### sandbox.processes.start/list/get

Source: https://www.inngest.com/docs/sandboxes/reference

Starts, lists, and gets processes in the sandbox. Requires RUNNING state.

```APIDOC
## sandbox.processes.start/list/get

### Description
Starts, lists, and gets processes in the sandbox. Requires RUNNING state.

### Method
Direct client method

### Endpoint
sandbox.processes.start/list/get

### Parameters
- **options** (object) - Optional - Options for the operation.

### Response
Returns process objects.
```

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

### Set up stephttp provider (steps.go)

Source: https://www.inngest.com/docs/reference/go

Create a single stephttp provider when the process starts, to be used for every Durable Endpoint handler.

```go
import "github.com/inngest/inngestgo/stephttp"

// Create one provider when the process starts, and use it for every handler.
var steps = stephttp.Setup(stephttp.SetupOpts{})

```

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

### from(job)

Source: https://www.inngest.com/docs/labs/ci/reference

Starts the current job on a copy of another job's machine, like a Docker layer. The parent runs once, however many jobs start from it, and each child gets its own isolated copy.

```APIDOC
## from(job)

### Description
Starts the current job on a copy of another job's machine, like a Docker layer. The parent runs once, however many jobs start from it, and each child gets its own isolated copy. If the pipeline already called the parent directly, `from()` uses that run. `from()` shares a job's machine within one run. To reuse it across runs, give the parent a `cache` key.

### Method
Function call

### Signature
`from(job)`

### Parameters
- **job** - The parent job to start from. Pass the parent's input as the second argument when it takes one.

### Usage Notes
- Call `from()` before the job's first command, and once per job.
- `await base()` runs `base` on its own machine. `await from(base)` runs it and then starts this job from where it finished.
- Choose the parent at runtime with `await from((await changed(
```

```APIDOC
## from(job)

### Description
Starts the current job on a copy of another job's machine, like a Docker layer. The parent runs once, however many jobs start from it, and each child gets its own isolated copy. If the pipeline already called the parent directly, `from()` uses that run. `from()` shares a job's machine within one run. To reuse it across runs, give the parent a `cache` key.

### Method
from

### Endpoint
from(job)

### Parameters
#### Function Parameters
- **job** (Job) - Required - The parent job to start from

### Request Example
```typescript
const base = ci.job(
```

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

### Serve Inngest functions in Tanstack Start

Source: https://www.inngest.com/docs/learn/serving-inngest-functions

Add this to `./src/routes/api/inngest.ts` to serve Inngest functions in a Tanstack Start app. It uses the `inngest/edge` package and defines GET, POST, and PUT handlers for the `/api/inngest` route.

```ts
import { createFileRoute } from "@tanstack/react-router";
import { serve } from "inngest/edge";
import { inngest, functions } from "../../inngest";

const handler = serve({ client: inngest, functions });

export const Route = createFileRoute("/api/inngest")({
  server: {
    handlers: {
      GET: async ({ request }) => handler(request),
      POST: async ({ request }) => handler(request),
      PUT: async ({ request }) => handler(request),
    },
  },
});
```

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

### Inspect runs and invoke functions with inngest api

Source: https://www.inngest.com/docs/cli

Examples of API commands to get a function run, get event runs, invoke a function locally, and fetch a full trace. Replace 'production' with your environment's slug.

```bash
# Get a function run
inngest api --prod --env production get-function-run 01KTCTWT8XDEGWDMVX3Q9M69ND

# Get runs triggered by an event
inngest api --prod --env production get-event-runs 01KTCTWSZJEKAFEDA4F9GYHFQW --include-output --limit 5

# Invoke a function locally
inngest api invoke-function my-app my-function --data '{"message": "hello"}'

# Fetch a full trace
inngest api --prod --env production get-function-trace 01KTCTWT8XDEGWDMVX3Q9M69ND --include-output
```

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

### Python client setup

Source: https://www.inngest.com/docs/sdks

Create an Inngest client to define functions and send events.

```python
import inngest
import logging

inngest_client = inngest.Inngest(
    app_id="app_example",
    logger=logging.getLogger("uvicorn"),
)
```

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

### Serve functions over HTTP (main.go)

Source: https://www.inngest.com/docs/reference/go/durable-workflows

Sets up an HTTP server that serves Inngest functions at /api/inngest. Requires an AppID and, in production, an INNGEST_SIGNING_KEY to verify requests. Use client.ServeWithOpts to customize the path.

```go
import (
	"log"
	"net/http"

	"github.com/inngest/inngestgo"
)

func Serve() {
	client, err := inngestgo.NewClient(inngestgo.ClientOpts{AppID: "billing"})
	if err != nil {
		log.Fatal(err)
	}

	// Create your functions with inngestgo.CreateFunction(client, ...) before
	// serving.  Each one registers itself with the client.

	// Inngest calls this endpoint to run your functions.
	http.Handle("/api/inngest", client.Serve())
	log.Fatal(http.ListenAndServe(":8080", nil))
}
```

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

### Define a trigger with github.pullRequest and github.push

Source: https://www.inngest.com/docs/labs/ci/concepts

A trigger starts a pipeline and types its event. This example listens for pull requests and pushes to the main branch.

```TypeScript
on: [github.pullRequest(), github.push({ branches: ["main"] })]
```

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

### Basic Inngest client creation

Source: https://www.inngest.com/docs/reference/typescript/v4/client/create

Creates an Inngest client with a unique application ID. This is the minimal setup required to start using the SDK.

```typescript
import { Inngest } from "inngest";

const inngest = new Inngest({
  id: "my-application",
});

```

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

### Minimal Inngest app in Go SDK v0.8

Source: https://www.inngest.com/docs/reference/go/migrations/v0.7-to-v0.8

Shows the minimal setup for an Inngest app using NewClient and CreateFunction. Note that AppID is now required and CreateFunction returns an error.

```go
import (
	"context"
	"net/http"

	"github.com/inngest/inngestgo"
)

func HighLevel() {
	client, err := inngestgo.NewClient(inngestgo.ClientOpts{AppID: "my-app"})
	if err != nil {
		panic(err)
	}

	_, err = inngestgo.CreateFunction(
		client,
		inngestgo.FunctionOpts{ID: "my-fn"},
		inngestgo.EventTrigger("my-event", nil),
		func(
			ctx context.Context,
			input inngestgo.Input[inngestgo.GenericEvent[any, any]],
		) (any, error) {
			return "Hello, world!", nil
		},
	)
	if err != nil {
		panic(err)
	}

	_ = http.ListenAndServe(":8080", client.Serve())
}
```

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

### Create a new H3 project

Source: https://www.inngest.com/docs/getting-started/h3-quick-start

Initializes a new directory and installs H3.

```shell
mkdir my-h3-app && cd my-h3-app
npm init -y
npm install h3
```

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

### processes.start

Source: https://www.inngest.com/docs/sandboxes/reference

Starts a background process and returns a process handle with a public UUID. The process can be managed via list, get, getOutput, signal, and wait operations.

```APIDOC
## processes.start

### Description
Starts a background process. The returned process has a public UUID. Use `list`, `get`, `getOutput`, `signal`, and `wait` to manage it.

### Method
start

### Parameters
- **command** (string or array) - Required - The command to start as a background process.

### Response
- **processId** (UUID) - Public UUID of the started process.

```

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

### Singleton with cancel mode

Source: https://www.inngest.com/docs/reference/typescript/v4/functions/singleton

Cancels the active run of the `data-sync` function when a new event with the same `user_id` is received, then starts a new run. Includes an example event payload and step runs.

```typescript
// Example event payload:
// {
//   name: "data-sync.start",
//   data: {
//     user_id: "123456789",
//   }
// }
export default inngest.createFunction(
  {
    id: "data-sync",
    triggers: { event: "data-sync.start" },
    singleton: {
      key: "event.data.user_id",
      mode: "cancel",
    },
  },
  async ({ event, step }) => {
    const company = await step.run(
      "fetch-latest-data-from-source",
      async () => {
        return await client.fetchData(event.data.user_id);
      }
    );

    await step.run("update-data-in-database", async () => {
      return await database.upsert({ id: company.id }, company);
    });
  }
);
```

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

### Start Inngest with CLI flags

Source: https://www.inngest.com/docs/self-hosting

Starts the Inngest server using command-line flags to set the event key and signing key. Replace placeholders with your actual keys.

```bash
inngest start --event-key <YOUR_EVENT_KEY> --signing-key <YOUR_SIGNING_KEY>

```

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

### Get run summary with get-function-run

Source: https://www.inngest.com/docs/guides/debug-with-cli

Fetch the summary of a specific run using its run ID. The response shows the run's status, function, timing, and trigger. Replace the example run ID with your own.

```bash
npx inngest-cli@latest api --prod --env production get-function-run 01KTCTWT8XDEGWDMVX3Q9M69ND

```

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

### serve() example with Next.js

Source: https://www.inngest.com/docs/reference/typescript/v4/serve

Basic usage of serve() from the inngest/next package, importing the client and functions, and passing them to serve().

```typescript
import { serve } from "inngest/next"; // or your preferred framework
import { inngest } from "./client";
import {
  importProductImages,
  sendSignupEmail,
  summarizeText,
} from "./functions";

serve({
  client: inngest,
  functions: [sendSignupEmail, summarizeText, importProductImages],
});
```

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

### Start a job from a cached base and checkout the current commit

Source: https://www.inngest.com/docs/labs/ci/caching

Uses `from(base)` to clone the saved machine without running `base` again, then calls `checkout()` to move to the current run's commit while keeping installed dependencies.

```TypeScript
const test = ci.job("test", async () => {
  await from(base);
  await checkout();
  await $`pnpm test`;
});
```

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

### Set timeouts.start to cancel queued runs in TypeScript

Source: https://www.inngest.com/docs/durable-execution/guides-and-advanced/cancellation/timeouts

Configures `timeouts.start` to 10 seconds, cancelling the run if it takes longer than 10 seconds to start the first step. The example function sends a push notification reminder.

```TypeScript
const scheduleReminder = inngest.createFunction(
  {
    id: "schedule-reminder",
    timeouts: {
      // If the run takes longer than 10s to start, cancel the run.
      start: "10s",
    },
    triggers: { event: "tasks/reminder.created" },
  },
  async ({ event, step }) => {
    await step.run('send-reminder-push', async () => {
      await pushNotificationService.push(event.data.reminder)
    })
  }
  // ...
);

```

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

### Install Inngest SDK with bun

Source: https://www.inngest.com/docs/getting-started/astro-quick-start

Run this command in your project root to install the Inngest SDK using bun.

```shell
bun add inngest
```

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

### init

Source: https://www.inngest.com/docs/reference/typescript/v4/middleware/lifecycle

Initializes the middleware with options and input arguments.

```APIDOC
## `init`

### Description
Initializes the middleware with options and input arguments.

### Parameters
- **options** (object) - Required - The options passed to the step (first argument).
- **input** (any) - Required - Arguments passed to the step function (after ID and handler).

```
Tokens:
Raw