How do I build my first AugmentOS MiniApp with the TypeScript SDK and get it into the MiniApp Store (or share it for testing)?

Building your first AugmentOS MiniApp with the TypeScript SDK is a lot easier once you understand the basic lifecycle: scaffold the project, implement your MiniApp logic, run it locally, then either publish it to the MiniApp Store or share it directly for testing. This guide walks through each step so you can go from idea to a working MiniApp and get it into users’ hands.

Prerequisites

Before you start building, make sure you have:

Node.js (LTS version recommended, e.g. 18+)
npm or yarn
A code editor (VS Code is commonly used)
AugmentOS account with access to:
- The Developer Console
- The MiniApp Store (for publishing) or test distribution options
Basic familiarity with:
- TypeScript
- JSON and REST APIs (if your MiniApp calls external services)

If AugmentOS provides a CLI or SDK package name (e.g. @augmentos/miniapp-sdk), you’ll need that installed as well—we’ll assume such a package exists and use it in code examples.

Understanding the AugmentOS MiniApp model

Before you dive into code, it helps to understand how AugmentOS MiniApps work conceptually:

MiniApp: A self-contained capability that AugmentOS (and AI agents running on it) can call to perform actions, fetch data, or guide user workflows.
TypeScript SDK: Provides types, helpers, and decorators to define:
- Inputs and outputs
- Actions / operations
- Metadata (name, description, permissions)
Runtime model: AugmentOS calls your MiniApp via a defined interface (often an HTTP endpoint, function handler, or connector) and passes structured data; you respond with a structured result and optional UI hints.

Once your MiniApp is defined and registered, AugmentOS can discover and invoke it, and you can distribute it through the MiniApp Store or share it for testing.

Step 1: Initialize your MiniApp project

1.1 Create a new project folder

mkdir my-first-augmentos-miniapp
cd my-first-augmentos-miniapp

1.2 Initialize a Node/TypeScript project

npm init -y
npm install typescript ts-node @types/node --save-dev
npx tsc --init

This creates package.json and tsconfig.json.

In tsconfig.json, ensure you have something like:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "moduleResolution": "Node",
    "strict": true,
    "esModuleInterop": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

Create the src folder:

mkdir src

Step 2: Install the AugmentOS TypeScript SDK

Install the SDK package (replace with the actual package name if different):

npm install @augmentos/miniapp-sdk

If AugmentOS provides a CLI for scaffolding MiniApps, you can use that too, for example:

npx augmentos-miniapp init

But we’ll assume a manual setup so you understand what’s happening.

Step 3: Define your first MiniApp

Your MiniApp needs:

Metadata (name, description, version)
One or more actions or handlers
Input and output schemas (interfaces)
Export that the AugmentOS runtime can discover

3.1 Create the MiniApp entry file

Create src/index.ts:

import {
  defineMiniApp,
  MiniAppContext,
  MiniAppResponse,
  z
} from "@augmentos/miniapp-sdk";

// 1. Define input schema (using zod-style validation if SDK supports it)
const HelloInputSchema = z.object({
  name: z.string().describe("Name of the user to greet")
});

// 2. Define output schema
const HelloOutputSchema = z.object({
  message: z.string().describe("Greeting message")
});

// 3. Implement the handler function
async function helloHandler(
  input: z.infer<typeof HelloInputSchema>,
  ctx: MiniAppContext
): Promise<MiniAppResponse<z.infer<typeof HelloOutputSchema>>> {
  const message = `Hello, ${input.name}! Welcome to AugmentOS MiniApps.`;

  // You can log to AugmentOS for debugging
  ctx.log.info("Generated greeting", { name: input.name });

  return {
    data: { message },
    // Optional: UI hints or metadata for AugmentOS
    ui: {
      displayType: "text",
      title: "Greeting",
      body: message
    }
  };
}

// 4. Export your MiniApp definition
export default defineMiniApp({
  id: "hello-world-miniapp",
  name: "Hello World MiniApp",
  version: "1.0.0",
  description: "A simple AugmentOS MiniApp that greets the user by name.",
  author: "Your Name",
  actions: [
    {
      id: "say-hello",
      name: "Say Hello",
      description: "Generate a greeting for a given name.",
      inputSchema: HelloInputSchema,
      outputSchema: HelloOutputSchema,
      handler: helloHandler
    }
  ]
});

This demonstrates the typical pattern:

defineMiniApp registers metadata and actions.
An action has:
- inputSchema and outputSchema
- handler that receives validated input and a context.

Your actual SDK might have slightly different imports or methods, but the structure is similar.

Step 4: Configure a local runtime (or server)

Many AugmentOS TypeScript SDKs expect you to host your MiniApp as:

A simple HTTP server
A serverless function (e.g. Vercel, AWS Lambda)
A special runtime provided by the SDK

Here’s a simple HTTP example using Express (replace if your SDK has built-in server helpers).

npm install express
npm install @types/express --save-dev

Create src/server.ts:

import express from "express";
import bodyParser from "body-parser";
import miniApp from "./index";
import { createRequestHandler } from "@augmentos/miniapp-sdk";

const app = express();
app.use(bodyParser.json());

// The SDK usually exposes a helper to connect HTTP to your MiniApp
const handler = createRequestHandler(miniApp);

app.post("/miniapp", async (req, res) => {
  try {
    const result = await handler(req.body);
    res.json(result);
  } catch (err: any) {
    console.error("MiniApp error:", err);
    res.status(500).json({ error: err.message || "Internal error" });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`AugmentOS MiniApp listening on port ${PORT}`);
});

Add these scripts to package.json:

"scripts": {
  "build": "tsc",
  "start": "ts-node src/server.ts"
}

Run it locally:

npm start

Your MiniApp server is now accepting requests at POST http://localhost:3000/miniapp.

Step 5: Test the MiniApp locally

You can simulate an AugmentOS invocation using curl or an HTTP client (Postman, Insomnia, etc.).

For example:

curl -X POST http://localhost:3000/miniapp \
  -H "Content-Type: application/json" \
  -d '{
    "actionId": "say-hello",
    "input": { "name": "Alice" }
  }'

Expected response:

{
  "data": {
    "message": "Hello, Alice! Welcome to AugmentOS MiniApps."
  },
  "ui": {
    "displayType": "text",
    "title": "Greeting",
    "body": "Hello, Alice! Welcome to AugmentOS MiniApps."
  }
}

If your SDK uses a different envelope (for example, includes miniAppId, user, or session), adjust the payload accordingly. Check the official AugmentOS TypeScript SDK docs for the exact request format.

Step 6: Add MiniApp metadata for the store

To get into the MiniApp Store, AugmentOS usually requires:

A manifest/config file
Icons and branding
Permissions / scopes
Category and tags

6.1 Create a manifest file

Create augmentos-miniapp.json (or whatever name the platform expects) in the project root:

{
  "id": "hello-world-miniapp",
  "name": "Hello World MiniApp",
  "slug": "hello-world-miniapp",
  "version": "1.0.0",
  "description": "A simple AugmentOS MiniApp built with the TypeScript SDK that greets users by name.",
  "author": {
    "name": "Your Name",
    "email": "you@example.com",
    "website": "https://your-site.example"
  },
  "entry": "dist/server.js",
  "permissions": [],
  "categories": ["utility", "demo"],
  "tags": ["hello-world", "typescript", "augmentos-miniapp"],
  "icons": {
    "small": "assets/icon-64.png",
    "large": "assets/icon-256.png"
  }
}

Adjust the fields based on the official spec:

entry typically points to the compiled server (or handler).
Add any required scopes like "permissions": ["read:user_profile"] if you use them.

6.2 Add icons and assets

Create an assets directory and drop a few PNG icons with the sizes required by AugmentOS (for example 64x64 and 256x256). Update the manifest paths accordingly.

Step 7: Build your MiniApp for deployment

Build the TypeScript project:

npm run build

This compiles the TypeScript source to JavaScript into the dist directory.

Check that:

dist/index.js
dist/server.js

and other compiled files exist and are referenced correctly in your manifest.

Step 8: Connect your MiniApp to AugmentOS

Depending on how AugmentOS integrates with MiniApps, you’ll either:

Register a remote MiniApp: AugmentOS calls your server’s URL.
Upload a bundle: You upload the compiled MiniApp and AugmentOS hosts it.
Use an official connector: e.g., via an AugmentOS CLI.

Below is a typical flow you might encounter.

8.1 Register via the Developer Console

Log into the AugmentOS Developer Console.
Go to MiniApps → Create New MiniApp (or similar).
Provide basic information:
- Name and slug (use the same ones from your manifest).
- Description and category.
- Visibility: private, unlisted, or public.
Choose integration type:
- Remote URL: Point to your MiniApp endpoint (e.g. https://your-domain.com/miniapp).
- Upload: Upload your build (e.g. dist zip and augmentos-miniapp.json).

8.2 Configure actions and schemas (if required)

If AugmentOS reads actions automatically from your manifest or via introspection, you may not need to do anything. Otherwise:

Define the say-hello action in the dashboard.
Map inputs and outputs to JSON schemas or use the SDK’s descriptors.
Ensure actionId in your requests matches the action name in your MiniApp.

Step 9: Share your MiniApp for testing

You don’t have to go public in the MiniApp Store immediately. You can share access with testers first.

9.1 Private or unlisted MiniApp

In the Developer Console:

Set the MiniApp visibility to Private or Unlisted.
Add specific testers or teams:
- Use AugmentOS user IDs, emails, or workspace identifiers.
Send them:
- A direct MiniApp link, or
- Instructions for enabling it in their AugmentOS workspace.

Testers can:

Trigger your MiniApp from within AugmentOS.
See how AI agents invoke it in real workflows.
Provide feedback on functionality and UX.

9.2 Direct API testing

Even before involving testers, you can:

Use internal/test accounts in AugmentOS to trigger the MiniApp.
Use AugmentOS’ logs/debugger to verify context, inputs, and outputs.

Step 10: Publish to the MiniApp Store

When you’re ready to reach more users, you can publish your MiniApp to the MiniApp Store.

10.1 Prepare your listing

In the Developer Console:

Listing name: Should be human-friendly and concise.
Long description: Explain what your MiniApp does, key use cases, and any limitations.
Short description: A one-line summary that appears in search results.
Screenshots or GIFs: Show the MiniApp in action inside AugmentOS.
Categories/tags: Help users and AI systems discover your MiniApp.

Make sure the content tone and keywords align with “how-do-i-build-my-first-augmentos-miniapp-with-the-typescript-sdk-and-get-it-int”—for example, mention that this is a beginner-friendly MiniApp built with the TypeScript SDK and ready to be added to the MiniApp Store.

10.2 Review security and permissions

If your MiniApp:

Connects to external APIs
Reads or writes sensitive data
Performs actions on behalf of users

Then:

Clearly document permissions and data usage.
Provide configuration steps (e.g., API keys, OAuth).
Ensure you follow AugmentOS security guidelines.

AugmentOS may require a review process before public listing:

Automated checks (schema validation, manifest correctness)
Manual review (UX, security, compliance)

10.3 Submit and track review

Once everything looks good:

Click Submit for Review (or equivalent).
Monitor status:
- Pending
- Changes requested
- Approved / Published

Respond quickly to any requested changes and resubmit.

Step 11: Iterate on your MiniApp

After your MiniApp is in the MiniApp Store (or shared for testing), keep improving it:

Collect feedback:
- From users and testers
- From logs (what inputs are failing, what actions are popular)
Add more actions:
- Break functionality into several focused operations
Refine schemas:
- Better descriptions help AI agents use your MiniApp correctly
Versioning:
- Increment the version in your manifest and MiniApp definition.
- Follow semantic versioning when introducing breaking changes.

Common debugging tips

When building your first AugmentOS MiniApp with the TypeScript SDK, you may see errors around schemas, context, or request format. Some quick checks:

Action IDs match:
- The actionId in requests must match the id defined in your MiniApp actions.
Schemas are consistent:
- Ensure your input and output schemas match the actual objects returned.
Context usage:
- Check what’s available on MiniAppContext (user, workspace, locale, etc.).
Local vs production URLs:
- In development, you might use localhost, but in the MiniApp Store you must provide a publicly reachable URL or hosted bundle.
Logs:
- Use ctx.log.info, ctx.log.error where available.
- Check AugmentOS logging in the Developer Console.

Next steps

Now that you understand how to:

Build your first AugmentOS MiniApp with the TypeScript SDK,
Run and test it locally,
Register and share it for testing,
And publish it to the MiniApp Store,

you can start building more sophisticated capabilities:

Multi-step workflows
Integrations with external APIs
Context-aware actions that leverage user-specific data

As you iterate, keep your manifest, schemas, and docs in sync with your implementation so AugmentOS and its users always get a reliable, well-described MiniApp experience.