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

Endpoints

Expose your functions for integration into your frontend or federated API

Connections

Establish connectivity for external endpoints and model hosts

Models

Define inference services for use in your functions

Base manifest

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

modus.json

{
  "$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.

Only a GraphQL endpoint is available currently, but the modular design of Modus allows for the introduction of additional endpoint types in the future.

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:

modus.json

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

type

string

required

Always set to "graphql" for this endpoint type.

path

string

required

The path for the endpoint. Must start with a forward slash /.

auth

string

required

The authentication method for the endpoint. Options are "bearer-token" or "none". See Authentication for additional details.

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:

Type	Purpose	Function Classes
`http`	Connect to an HTTP(S) web server	`http`, `graphql`, `models`
`dgraph`	Connect to a Dgraph database	`dgraph`
`mysql`	Connect to a MySQL database	`mysql`
`neo4j`	Connect to a Neo4j database	`neo4j`
`postgresql`	Connect to a PostgreSQL database	`postgresql`

Don’t include secrets directly in the manifest!If your connection requires authentication, you can include placeholders in connection properties which resolve to their respective secrets at runtime.When developing locally, set secrets using environment variables.When deployed on Hypermode, set the actual secrets via the Hypermode Console, where they’re securely stored until needed.

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:

modus.json

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

type

string

required

Always set to "http" for this connection type.

baseUrl

string

required

Base URL for connections to the host. Must end with a trailing slash and may contain path segments if necessary.Example: "https://api.example.com/v1/"

endpoint

string

required

Full URL endpoint for connections to the host.Example: "https://models.example.com/v1/classifier"

You must include either a baseUrl or an endpoint, but not both.

Use baseUrl for connections to a host with a common base URL.
Use endpoint for connections to a specific URL.

Typically, you’ll use the baseUrl field. However, some APIs, such as graphql.execute, require the full URL in the endpoint field.

headers

object

If provided, requests on the connection include these headers. Each key-value pair is a header name and value.Values may include variables using the {{VARIABLE}} template syntax, which resolve at runtime to environment variables provided for each connection, via the Hypermode Console.

Examples

This example specifies a header named Authorization that uses the Bearer scheme. A secret named AUTH_TOKEN provides the token:

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

This example specifies a header named X-API-Key provided by a secret named API_KEY:

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

You can use a special syntax for connections that require HTTP basic authentication. In this example, secrets named USERNAME and PASSWORD combined and then are base64-encoded to form a compliant Authorization header value:

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

queryParameters

object

If provided, requests on the connection include these query parameters, appended to the URL. Each key-value pair is a parameter name and value.Values may include variables using the {{VARIABLE}} template syntax, which resolve at runtime to secrets provided for each connection, via the Hypermode Console.

Example

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. There are two ways to connect to Dgraph:

Using a connection string (preferred method)
Using a gRPC target (older method)

You can use either approach in Modus, but not both.

Using a Dgraph connection string

This is the preferred method for connecting to Dgraph. It uses a simplified URI based connection string to specify all options, including host, port, options, and authentication. Example:

modus.json

{
  "connections": {
    "my-dgraph": {
      "type": "dgraph",
      "connString": "dgraph://example.hypermode.host:443?sslmode=verify-ca&bearertoken={{DGRAPH_API_KEY}}"
    }
  }
}

type

string

required

Always set to "dgraph" for this connection type.

connString

string

required

The connection string for the Dgraph database, in URI format.

Using a Dgraph gRPC target

This is the older method for connecting to Dgraph. It uses a gRPC target to specify the host and port, and a separate key for authentication. It automatically uses SSL mode (with full CA verification) for the connection - except when connecting to localhost. Additional options such as username/password authentication aren’t supported. If you need to use these options, use the connection string method instead. Example:

modus.json

{
  "connections": {
    "my-dgraph": {
      "type": "dgraph",
      "grpcTarget": "example.grpc.region.aws.cloud.dgraph.io:443",
      "key": "{{DGRAPH_API_KEY}}"
    }
  }
}

type

string

required

Always set to "dgraph" for this connection type.

grpcTarget

string

required

The gRPC target for the Dgraph database.

key

string

required

The API key for the Dgraph database.

MySQL connection

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

modus.json

{
  "connections": {
    "my-database": {
      "type": "mysql",
      "connString": "mysql://{{USERNAME}}:{{PASSWORD}}@db.example.com:3306/dbname?tls=true"
    }
  }
}

type

string

required

Always set to "mysql" for this connection type.

connString

string

required

The connection string for the MySQL database.Values may include variables using the {{VARIABLE}} template syntax, which resolve at runtime to secrets provided for each connection, via the Hypermode Console.The connection string in the preceding example includes:

A username and password provided by secrets named USERNAME & PASSWORD
A host named db.example.com on port 3306
A database named dbname
Encryption enabled via tls=true - which is highly recommended for secure connections

Set the connection string using a URI format as described in the MySQL documentation.However, any optional parameters provided should be in the form specified by the Go MySQL driver used by the Modus Runtime, as described hereFor example, use tls=true to enable encryption (not sslmode=require).

Neo4j connection

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

modus.json

{
  "connections": {
    "my-neo4j": {
      "type": "neo4j",
      "dbUri": "bolt://localhost:7687",
      "username": "neo4j",
      "password": "{{NEO4J_PASSWORD}}"
    }
  }
}

type

string

required

Always set to "neo4j" for this connection type.

dbUri

string

required

The URI for the Neo4j database.

username

string

required

The username for the Neo4j database.

password

string

required

The password for the Neo4j database.

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:

modus.json

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

type

string

required

Always set to "postgresql" for this connection type.

connString

string

required

The connection string for the PostgreSQL database.Values may include variables using the {{VARIABLE}} template syntax, which resolve at runtime to secrets provided for each connection, via the Hypermode Console.The connection string in the preceding example includes:

A username and password provided by secrets named PG_USER & PG_PASSWORD
A host named db.example.com on port 5432
A database named data
SSL mode set to require - which is highly recommended for secure connections

Refer to the PostgreSQL documentation for more details on connection strings.

Managed PostgreSQL providers often provide a pre-made connection string for you to copy. Check your provider’s documentation for details.For example, if using Neon, refer to the Neon documentation.

See Running locally with secrets for more details on how to set secrets for local development.

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.

modus.json

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

sourceModel

string

required

Original relative path of the model within the provider’s repository.

provider

string

Source provider of the model. If the connection value is hypermode, this field is mandatory. hugging-face is currently the only supported option.

connection

string

required

Connection for the model instance.

Specify "hypermode" for models that Hypermode hosts.
Otherwise, specify a name that matches a connection defined in the connections section of the manifest.

When using hugging-face as the provider and hypermode as the connection, Hypermode automatically facilitates the connection to an instance of a shared or dedicated instance of the model. Your project’s functions securely access the hosted model, with no further configuration required.

Getting Started

Building Your App

How-To Guides

SDK Reference

Tools

Resources

App Manifest

Structure

Endpoints

Connections

Models

Base manifest

Endpoints

GraphQL endpoint

Connections

HTTP connection

Dgraph connection

Using a Dgraph connection string

Using a Dgraph gRPC target

MySQL connection

Neo4j connection

PostgreSQL connection

Models

Getting Started

Building Your App

How-To Guides

SDK Reference

Tools

Resources

​Structure

Endpoints

Connections

Models

​Base manifest

​Endpoints

​GraphQL endpoint

​Connections

​HTTP connection

​Dgraph connection

​Using a Dgraph connection string

​Using a Dgraph gRPC target

​MySQL connection

​Neo4j connection

​PostgreSQL connection

​Models

Structure

Base manifest

Endpoints

GraphQL endpoint

Connections

HTTP connection

Dgraph connection

Using a Dgraph connection string

Using a Dgraph gRPC target

MySQL connection

Neo4j connection

PostgreSQL connection

Models