App Manifest

The manifest for your Modus app allows you to configure the exposure and resources for your functions at runtime. You define the manifest in the modus.json file within the root of directory of your app.

​

Structure

​

Base manifest

A simple manifest, which exposes a single GraphQL endpoint with a bearer token for authentication, looks like this:

{
  "$schema": "https://schema.hypermode.com/modus.json",
  "endpoints": {
    "default": {
      "type": "graphql",
      "path": "/graphql",
      "auth": "bearer-token"
    }
  }
}

​

Endpoints

Endpoints make your functions available outside of your Modus app. The endpoints object in the app manifest allows you to define these endpoints for integration into your frontend or federated API.

Each endpoint requires a unique name, specified as a key containing only alphanumeric characters and hyphens.

​

GraphQL endpoint

This endpoint type supports the GraphQL protocol to communicate with external clients. You can use a GraphQL client, such as urql or Apollo Client, to interact with the endpoint.

Example:

{
  "endpoints": {
    "default": {
      "type": "graphql",
      "path": "/graphql",
      "auth": "bearer-token"
    }
  }
}

​

Connections

Connections establish connectivity and access to external services. They’re used for HTTP and GraphQL APIs, database connections, and externally hosted AI models. The connections object in the app manifest allows you to define these hosts, for secure access from within a function.

Each connection requires a unique name, specified as a key containing only alphanumeric characters and hyphens.

Each connection has a type property, which controls how it’s used and which additional properties are available. The following table lists the available connection types:

​

HTTP connection

This connection type supports the HTTP and HTTPS protocols to communicate with external hosts. You can use the HTTP APIs in the Modus SDK to interact with the host.

This connection type is also used for GraphQL APIs and to invoke externally hosted AI models.

Example:

{
  "connections": {
    "openai": {
      "type": "http",
      "baseUrl": "https://api.openai.com/",
      "headers": {
        "Authorization": "Bearer {{API_KEY}}"
      }
    }
  }
}

"headers": {
  "Authorization": "Bearer {{AUTH_TOKEN}}"
}

"headers": {
  "X-API-Key": "{{API_KEY}}"
}

"headers": {
  "Authorization": "Basic {{base64(USERNAME:PASSWORD)}}"
}

"queryParameters": {
  "key": "{{API_KEY}}"
}

​

PostgreSQL connection

This connection type supports connecting to PostgreSQL databases. You can use the PostgreSQL APIs in the Modus SDK to interact with the database.

Example:

{
  "connections": {
    "my-database": {
      "type": "postgresql",
      "connString": "postgresql://{{PG_USER}}:{{PG_PASSWORD}}@db.example.com:5432/data?sslmode=require"
    }
  }
}

​

Dgraph connection

This connection type supports connecting to Dgraph databases. You can use the Dgraph APIs in the Modus SDK to interact with the database.

Example:

{
  "connections": {
    "my-dgraph": {
      "type": "dgraph",
      "grpcTarget": "frozen-mango.grpc.eu-central-1.aws.cloud.dgraph.io:443",
      "key": "{{DGRAPH_API_KEY}}"
    }
  }
}

​

Working locally with secrets

When you run your app locally using modus dev, the runtime replaces the placeholders of the manifest with values from environment variables defined in your operating system or in .env files.

The environment variables keys must be upper case and follow the naming convention:

MODUS_<CONNECTION NAME>_<PLACEHOLDER>

For example, with the following manifest:

{
  "connections": {
    "openai": {
      "type": "http",
      "baseUrl": "https://api.openai.com/",
      "headers": {
        "Authorization": "Bearer {{API_KEY}}"
      }
    }
  }
}

The Modus runtime substitutes {{API_KEY}} with the value of the environment variable MODUS_OPENAI_API_KEY

An easy way to define the environment variables when working locally is to use the file .env.dev.local located in your app folder.

For the previous manifest, we can set the key in the .env.dev.local file as follow:

MODUS_OPENAI_API_KEY="your openai key"

You should exclude .env files from source control. Projects created with modus new exclude these files automatically when creating your project.

​

Models

AI models are a core resource for inferencing. The models object in the app manifest allows you to easily define models, whether hosted by Hypermode or another host.

Each model requires a unique name, specified as a key, containing only alphanumeric characters and hyphens.

{
  "models": {
    "text-generator": {
      "sourceModel": "meta-llama/Meta-Llama-3.1-8B-Instruct",
      "provider": "hugging-face",
      "connection": "hypermode"
    }
  }
}

​

Collections

Collections simplify the usage of vector embeddings to build natural language search features. The collections object allows you to define indexed data types that are automatically embedded and searchable based on the search method you define.

Each collection requires a unique name, specified as a key, containing only alphanumeric characters and hyphens.

For more detail on implementing Collections, see Search.

{
  "collections": {
    "myProducts": {
      "searchMethods": {
        "searchMethod": {
          "embedder": "myEmbedder",
          "index": {
            "type": "sequential"
          }
        }
      }
    }
  }
}