diff --git a/apps/connect-app.mdx b/apps/connect-app.mdx new file mode 100644 index 00000000..140f04e4 --- /dev/null +++ b/apps/connect-app.mdx @@ -0,0 +1,137 @@ +--- +title: "Connect Your App" +description: "Integrate your App with external services and databases" +"og:title": "Connect Your App - Apps" +--- + +Apps become powerful when they can connect to external systems. Hypermode +supports connecting your app to APIs, databases, and model providers through +secure, manageable integrations. + +## Connection Examples + +### OpenAI API connection + +Connect to OpenAI for language models: + +```json modus.json +{ + "models": { + "text-generator": { + "sourceModel": "gpt-4o-mini", + "connection": "openai", + "path": "v1/chat/completions" + } + }, + "connections": { + "openai": { + "type": "http", + "baseUrl": "https://api.openai.com/", + "headers": { + "Authorization": "Bearer {{API_KEY}}" + } + } + } +} +``` + +### PostgreSQL database + +Connect to a PostgreSQL database: + +```json modus.json +{ + "connections": { + "postgres": { + "type": "postgresql", + "connStr": "{{DATABASE_URL}}" + } + } +} +``` + +### Dgraph database + +Connect to a Dgraph database for graph operations: + +```json modus.json +{ + "connections": { + "dgraph": { + "type": "dgraph", + "grpcTarget": "{{DGRAPH_ENDPOINT}}" + } + } +} +``` + +## Environment variables + +### Naming convention + +Hypermode uses a consistent naming pattern for environment variables: +`MODUS__` + +For a connection named `openai` with placeholder `{{API_KEY}}`: + +- Environment variable: `MODUS_OPENAI_API_KEY` + +### Local development + +Set environment variables in `.env.dev.local`: + +```text .env.dev.local +MODUS_OPENAI_API_KEY="your_openai_api_key" +MODUS_POSTGRES_DATABASE_URL="postgresql://localhost:5432/mydb" +MODUS_DGRAPH_DGRAPH_ENDPOINT="localhost:9080" +``` + +### Production environment + +Configure production environment variables in the Hypermode console: + +Environment variables configuration panel + +1. Navigate to your app in the console +2. Click on the **Environment Variables** tab +3. Add your environment variables with the proper naming convention +4. Save the configuration + +## Testing connections + +### Local testing + +Test connections during development: + +```bash +# Start development server +modus dev + +# Test connections in the API Explorer +# Navigate to http://localhost:8686/explorer +``` + +### Production testing + +Verify connections in production: + +```bash +# Test your deployed app's connections +curl -X POST https://your-app-endpoint.hypermode.app/graphql \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"query": "{ testConnection }"}' +``` + +## Best practices + +- **Never commit secrets**: Use environment variables for all sensitive data +- **Use least privilege**: Grant minimal necessary permissions to API tokens +- **Test locally first**: Use `modus dev` to debug connection issues before + deploying +- **Monitor usage**: Track API calls and database connections in production + +Your app can now securely connect to external services and databases. diff --git a/apps/create-app.mdx b/apps/create-app.mdx new file mode 100644 index 00000000..23aaed98 --- /dev/null +++ b/apps/create-app.mdx @@ -0,0 +1,207 @@ +--- +title: "Create Your App" +description: "Get started by creating your first App in Hypermode" +"og:title": "Create Your App - Apps" +--- + +Creating your first App in Hypermode is straightforward. This guide walks you +through the entire process from workspace creation to having a fully configured +app ready for development. + +## Prerequisites + +Before creating your app, ensure you have: + +- A GitHub account +- Access to a repository (existing or new) +- Basic understanding of your app's requirements + +## Getting started + +To create your app, follow these steps in the Hypermode console. If you haven't +created a workspace yet, you'll need to do that first. Workspaces are where you +and your team manage all your apps and configurations. + + + + + +Start by going to [hypermode.com](https://hypermode.com) and creating your +workspace. Workspaces are where you and your team manage all your apps. + +Create workspace interface showing workspace name input field + +Enter a descriptive name for your workspace and click **Create workspace**. +Choose a name that reflects your organization or project scope, as this becomes +the container for all your apps. + + + + + +Once your workspace is created, you'll see the main dashboard. Click on **Apps** +to start creating your first app. + +Hypermode dashboard showing Apps option + +From the Apps section, you have options to create different types of apps or +import existing ones. + + + + + +Click **Import your Modus app** to create a new app. This option works whether +you're importing an existing Modus project or starting fresh. + +Import Modus app configuration form with app name, GitHub repository, and location fields + +### Define your app name + +Enter a descriptive name for your app. This can be used in your app's endpoint +URL and throughout the Hypermode console. + +### Connect to your GitHub repository + +You have two options: + +#### Option 1: use an existing repository + +- Select your repository from the dropdown +- Ensure your repository has the proper Modus structure or is ready for app + development + +#### Option 2: create a new repository + +If you don't have a repository yet, you can create one: + +GitHub repository creation interface with repository name field + +1. Choose the repository owner (your organization or personal account) +2. Enter a memorable repository name +3. Add an optional description +4. Create the repository +5. Return to the app configuration and select your newly created repository + +### Deployment location + +Choose your preferred deployment region. This affects: + +- **Latency**: Choose a region close to your users +- **Compliance**: Select based on data residency requirements +- **Performance**: Consider where your external services are hosted + + + + + +After filling in all the configuration details, click **Create App**. Hypermode +then automatically: + +1. Sets up your app infrastructure +2. Configures the GitHub integration +3. Generates your app's endpoint and API key +4. Prepares your development environment + + + + + +Once created, you'll see your app's configuration panel: + +App details panel showing endpoint, GitHub repository, and API key information + +Your new app includes: + +### Endpoint + +Your production GraphQL endpoint where your app is accessible: + +```text +https://your-app-name-workspace-id.hypermode.app/graphql +``` + +### GitHub repository + +The connected repository for automatic deployments. Any push to the main branch +triggers a deployment. + +### API key + +Your authentication key for accessing the app's API. Keep this secure and use it +in your app headers: + +```bash +Authorization: Bearer YOUR_API_KEY +``` + + + + + +## Development Approaches + +With your app created, you can choose between two development approaches: + +### Code first development + +- Use the Modus CLI locally +- Full control over app structure +- Traditional Git workflows +- See the [Develop guide](/apps/develop-app) for setup instructions + +### Conversational development + +- Use Threads for AI-assisted development +- Natural language app building +- Rapid prototyping and iteration +- See the Threads documentation for details + +## Next steps + +Now that your app is created: + +1. **Set up local development** with `modus dev` (see + [Develop guide](/apps/develop-app)) +2. **Configure connections** to external services (see + [Connect Your App guide](/apps/connect-app)) +3. **Deploy your first version** by pushing to your repository (see + [Deploy guide](/apps/deploy-app)) + +Your app is now ready for development. The GitHub integration is configured, +your endpoint is live, and you have everything needed to start building your +AI-powered app. + +## Troubleshooting + +**Repository not appearing in dropdown?** + +- Ensure you have proper permissions to the repository +- Check that the Hypermode GitHub App is installed on your organization/account + +**App creation failed?** + +- Verify your repository is accessible +- Ensure the app name doesn't conflict with existing apps +- Check that all required fields are filled correctly + +**Need to change configuration?** + +- Most settings can be updated later in the app's configuration panel +- Repository connections can be modified in the app settings diff --git a/apps/deploy-app.mdx b/apps/deploy-app.mdx new file mode 100644 index 00000000..e1ed915e --- /dev/null +++ b/apps/deploy-app.mdx @@ -0,0 +1,161 @@ +--- +title: "Deploy" +sidebarTitle: "Deploy your App" +description: "Deploy your Apps to production with Hypermode" +"og:title": "Deploy - Apps" +--- + +Once you've developed and tested your App locally, you're ready to deploy it to +production on Hypermode. This guide walks you through setting up automatic +deployment for your Modus app. + +## Prerequisites + +Before deploying, ensure you have: + +- A completed Modus app (see the [Develop guide](/apps/develop-app) for setup) +- A GitHub account and repository +- Your app configured in the Hypermode console (see the + [Create Your App guide](/apps/create-app)) + +## Automatic deployment via GitHub Actions + +Add a GitHub Actions workflow to your repository for automatic deployments. + +Create `.github/workflows/ci-modus-build.yml`: + + + This workflow can stray out of date as new Golang releases are made. If you + encounter issues, checkout our [open source recipes + repo](https://github.com/hypermodeinc/modus-recipes/blob/main/.github/workflows/build.yml). + + +```yaml +name: ci-modus-build + +on: + push: + branches: + - main + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: "22" + + - name: Setup Go + uses: actions/setup-go@v5 + with: + go-version: "1.24.4" + + - name: Setup TinyGo + uses: acifani/setup-tinygo@v2 + with: + tinygo-version: "0.38.0" + + - name: Build project + run: npx -p @hypermode/modus-cli -y modus build +``` + +Once the workflow is added, **any push to the `main` branch automatically +deploys your app**: + +```bash +# Commit your changes +git add . +git commit -m "Deploy my Modus app" + +# Push to trigger deployment +git push origin main +``` + +The deployment automatically: + +1. Builds your Modus app via GitHub Actions +2. Deploys to your Hypermode endpoint +3. Makes your functions available via GraphQL + +Deployment output: + +```text +🚀 Deployment started for commit abc123d +📦 Building application... +✓ Functions compiled successfully +🌐 Deploying to production... +✓ Health checks passed +🎉 Deployment complete! + +Endpoint: https://my-modus-app-my-workspace-hurx1.hypermode.app/graphql +``` + +## Production features + +Your deployed app includes: + +- **Automatic scaling**: Functions scale to zero when not in use +- **HTTPS endpoints**: Secure GraphQL API +- **Bearer token auth**: API key authentication +- **Real-time logs**: Monitor function execution in the Activity tab +- **Environment variables**: Manage secrets and configuration + +### Viewing function activity + +Monitor your function executions in the Activity tab: + +Function logs showing execution times and status + +You can see: + +- Function execution history +- Response times and duration +- Success/error status +- Execution timestamps + +### Environment variables + +Configure environment variables in the Environment variables tab: + +Environment variables configuration panel + +Set production environment variables for: + +- API keys and secrets +- Database connection strings +- Feature flags +- External service configurations + +## Testing your deployment + +Test your deployed functions via GraphQL: + +```bash +curl -X POST https://your-app-endpoint.hypermode.app/graphql \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"query": "{ sayHello(name: \"Production\") }"}' +``` + +## Next steps + +With your app deployed, your development workflow becomes: + +1. Develop and test locally with `modus dev` +2. Commit and push changes to GitHub +3. Automatic deployment to production +4. Monitor via Hypermode console + +Your Modus app is now live and ready to handle production traffic with automatic +scaling, built-in observability, and secure endpoints. diff --git a/apps/develop-app.mdx b/apps/develop-app.mdx new file mode 100644 index 00000000..d2911087 --- /dev/null +++ b/apps/develop-app.mdx @@ -0,0 +1,182 @@ +--- +title: "Develop" +sidebarTitle: "Develop with Your App" +description: "Build and iterate on your Apps locally or in Threads" +"og:title": "Develop - Apps" +--- + +Hypermode supports two complementary approaches for building Apps: **code-first +development** using Modus locally and **conversational development** using +Threads. For conversational development, see our Threads documentation. + +## Code-first development with Modus + +For developers who prefer working with code, Modus provides a complete local +development environment. This approach gives you full control over your App's +structure, version control integration, and the ability to work within your +existing development tools. + +### Setting up local development + +Install the Modus CLI to start building Apps locally: + +```bash +npm install -g @hypermode/modus-cli +``` + +Create a new App: + +```bash +modus new my-app +cd my-app +``` + +This scaffolds a complete App structure with: + +- Agent definitions and configurations +- Function definitions for custom tools +- Model integrations and connections +- Environment configuration +- Testing framework + +### Local development workflow + +When developing locally, you get the full Modus runtime experience: + +```bash +# Start local development server +modus dev + +# Build your app +modus build +``` + +Your local environment includes: + +- **Hot reload** for rapid iteration with fast refresh +- **Built-in debugging** with full observability +- **API Explorer** for testing functions and agents interactively +- **Model experimentation** with easy model swapping via Model Router +- **Environment management** with `.env` files + +### Local development environment + +When you run `modus dev`, you get: + +- **Local server** running at `http://localhost:8686` +- **API Explorer** at `http://localhost:8686/explorer` for interactive testing +- **Automatic compilation** of your Go or AssemblyScript code to WebAssembly +- **Fast refresh** that preserves app state during development +- **Environment variable substitution** from `.env.dev.local` files + +### Code structure + +Apps follow the Modus project structure that scales from simple functions to +complex agent systems: + +```text +my-app/ +├── main.go # Functions and agent definitions +├── modus.json # App configuration and manifest +├── .env.dev.local # Local environment variables +├── go.mod # Dependencies (Go projects) +└── README.md # Project documentation +``` + +### Environment and secrets management + +Modus handles environment variables and secrets securely: + +```json modus.json +{ + "connections": { + "external-api": { + "type": "http", + "baseUrl": "https://api.example.com/", + "headers": { + "Authorization": "Bearer {{API_KEY}}" + } + } + } +} +``` + +Set your environment variables in `.env.dev.local`: + +```text .env.dev.local +MODUS_EXTERNAL_API_API_KEY="your_api_key_here" +``` + +Modus automatically substitutes `{{API_KEY}}` with `MODUS_EXTERNAL_API_API_KEY` +following the naming convention: `MODUS__`. + +### Using Hypermode-hosted models + +To access Hypermode's Model Router and hosted models locally: + +```bash +# Install Hyp CLI for authentication +npm install -g @hypermode/hyp-cli + +# Authenticate with Hypermode +hyp login +``` + +Once authenticated, your local Modus environment automatically connects to +Hypermode's model infrastructure, giving you access to multiple AI models for +development and testing. + +## Collaborative development + +Both approaches support team collaboration: + +### Code-first teams + +- Standard Git workflows with branching and pull requests +- Shared development environments +- Code reviews for agent logic and function implementations +- Automated testing and CI/CD integration + +### Mixed teams + +- Subject matter experts build and refine using Threads (see our Threads + documentation) +- Developers enhance and ship Modus code +- Seamless handoff between exploration and implementation +- Shared testing environments using `modus dev` + +## Testing and debugging + +Hypermode provides comprehensive testing tools for both development approaches: + +### Built-in testing with Modus + +- **API Explorer**: Interactive testing of functions and agents +- **Agent behavior tests**: Verify reasoning and decision-making +- **Function integration tests**: Test external API calls and data processing +- **Memory tests**: Validate state persistence and retrieval +- **End-to-end scenarios**: Test complete workflows + +### Observability and debugging + +- **Execution tracing**: See every step of agent reasoning +- **Function call monitoring**: Track all external interactions +- **Memory access logs**: Understand how agents use context +- **Performance metrics**: Monitor response times and resource usage +- **Real-time logs**: Debug issues as they happen during development + +## Environment management + +Apps support multiple environments throughout development: + +### Local development + +- Full-featured Modus runtime with `modus dev` +- Mock external services for testing +- Hot reload and instant feedback +- Local memory persistence +- API Explorer for interactive testing + +Whether you're a developer who prefers code, Hypermode's development experience +provides the tools you need to build production-ready Apps using the power of +the Modus runtime. diff --git a/apps/overview.mdx b/apps/overview.mdx new file mode 100644 index 00000000..5b8ce4c0 --- /dev/null +++ b/apps/overview.mdx @@ -0,0 +1,86 @@ +--- +title: Apps +description: + "Build and deploy AI agents and agentic applications with Hypermode Apps" +mode: "wide" +sidebarTitle: "Overview" +"og:title": "Overview - Apps" +--- + +Apps in Hypermode are how you package and deploy agents and AI-native apps. + +An App is a collection of related agents, tools, and memory, working together to +perform a cohesive set of tasks towards an outcome. Whether you're coordinating +a team of agents or creating multi-step agentic flows, Apps are the top-level +construct that unifies your AI system. + +## Why Apps? + +Building an agent is powerful. But real-world use cases rarely stop at one. As +your AI system grows, you'll often need to: + +- **Coordinate multiple agents** with different roles +- **Share tools and context** across flows +- **Persist memory** and long-term learning for a domain +- **Deploy and version** your system as a single unit + +That's where Apps come in. Apps give structure to your agentic architecture. +They let you group related components - agents, tools, memories, and APIs- into +one deployable unit. + +## What's in an App? + +Apps in Hypermode are modular and flexible, designed to let you build complex +systems by assembling reusable components. + +Every App on Hypermode is made up of the following components: + +### Agents + +Agents are the workers that reason, plan, and act. Apps can include one or many +agents, each with their own role. You can assign different models, tools, and +memory configurations to each agent, or allow them to collaborate via shared +context. + +### Tools + +Tools are how agents take action. These include custom functions, external APIs, +or built-in Hypermode tools (like data fetching or search). Apps define which +tools are available to which agents and can scope tools to specific tasks or +agent roles. + +### Memory + +Apps can define long-term and short-term memory for agents using Hypermode's +memory primitives. This allows your agents to remember past interactions, user +preferences, task outcomes, and more to enable persistent, contextual behavior +over time. + +### Connections + +Apps can include third-party integrations like GitHub, Slack, or internal APIs +via the Model Context Protocol (MCP). These integrations allow agents to +interact with external systems in a structured, secure way. + +### Decision interface + +Apps use a decision interface to let you work asynchronously with agents. This +is useful for long-running tasks, approvals, or cases where agent actions need +to be reviewed before execution. + +### Runtime + +Each App includes metadata for tracking versions, environments, and ownership. +You can define environment variables, set up deployment environment (staging vs +production), and manage runtime settings that affect how agents are executed. + +## Agent development lifecycle + +Apps support the full development lifecycle: + +- **Develop locally** using the [Hyp CLI](/hyp-cli) or in a **conversational + interface** using Threads +- **Test and debug** agent behavior +- **Deploy to production** with versioning and rollback support +- **Monitor and trace** interactions using built-in observability +- **Collaborate and share** across teams with access controls and roles diff --git a/docs.json b/docs.json index 6c3dd1f8..18b38af9 100644 --- a/docs.json +++ b/docs.json @@ -76,6 +76,16 @@ "agents/faq" ] }, + { + "group": "Apps", + "pages": [ + "apps/overview", + "apps/create-app", + "apps/connect-app", + "apps/develop-app", + "apps/deploy-app" + ] + }, { "group": "Graphs", "pages": [ diff --git a/images/apps/app-create.png b/images/apps/app-create.png new file mode 100644 index 00000000..fc497183 Binary files /dev/null and b/images/apps/app-create.png differ diff --git a/images/apps/console-app.png b/images/apps/console-app.png new file mode 100644 index 00000000..3875f597 Binary files /dev/null and b/images/apps/console-app.png differ diff --git a/images/apps/console-envs.png b/images/apps/console-envs.png new file mode 100644 index 00000000..cbc56500 Binary files /dev/null and b/images/apps/console-envs.png differ diff --git a/images/apps/console-logs.png b/images/apps/console-logs.png new file mode 100644 index 00000000..25799aeb Binary files /dev/null and b/images/apps/console-logs.png differ diff --git a/images/apps/github-create.png b/images/apps/github-create.png new file mode 100644 index 00000000..8f161e9d Binary files /dev/null and b/images/apps/github-create.png differ diff --git a/images/apps/workspace-creation.png b/images/apps/workspace-creation.png new file mode 100644 index 00000000..7e802234 Binary files /dev/null and b/images/apps/workspace-creation.png differ diff --git a/images/apps/workspace-landing.png b/images/apps/workspace-landing.png new file mode 100644 index 00000000..3a9f4d85 Binary files /dev/null and b/images/apps/workspace-landing.png differ diff --git a/modus/overview.mdx b/modus/overview.mdx index a93afa5e..16a31fba 100644 --- a/modus/overview.mdx +++ b/modus/overview.mdx @@ -41,7 +41,7 @@ maintainable, scalable intelligent systems. You can run Modus locally for development or deploy it in seconds to Hypermode for production. -## What is Modus good for? {/* vale Google.Contractions = NO */} +## When to use Modus Modus is designed for building applications where AI is at its core capability. It supports sub-second response times for stateless operations and long-running, @@ -56,8 +56,22 @@ what it does best. Both functions and agents can be deployed in the same app, allowing you to choose the right abstraction for each use case. -For more inspiration, check out the -[Modus recipes](https://github.com/hypermodeinc/modus-recipes). +### Language-agnostic logic, safely + +With WebAssembly's secure isolation environment, define agent behavior in Go or +AssemblyScript. Compile to WebAssembly and Modus runs it securely. Each agent +runs as a lightweight actor: self-contained, message-driven, and supervised by +the runtime. + +### Persistent context beyond sessions + +For use-cases like multi-day workflows, personal assistants, tutoring, or +domain-specific agents (for example ticketing systems), long-term context is +crucial. Modus provides it without requiring a dedicated database layer. Modus' +built-in short-term memory handles conversational state and context within +agents. Connect to long-term graph memory for externalized and persisted, but +serverless-friendly memory. You gain full "recall" - across sessions and +workflows- without maintaining stateful servers. ## Where to next? diff --git a/styles/config/vocabularies/general/accept.txt b/styles/config/vocabularies/general/accept.txt index a02542b9..292ace73 100644 --- a/styles/config/vocabularies/general/accept.txt +++ b/styles/config/vocabularies/general/accept.txt @@ -1,5 +1,6 @@ [Aa]gentic [Aa]lterSchema +[Aa]pp Attio [Bb]oolean [Cc]ollections