AICord Applets

Welcome to the AICord Applet System! Applets are tiny JavaScript tools that let your AI characters do powerful things - like pulling live data, reacting to server events, or integrating with external services. No big setup, no bloated codebase - just one file, one idea.

Applets let your characters do real-world tasks — call APIs, fetch data, trigger webhooks — giving them agentic capabilities beyond just conversation.

✨ What’s an Applet?

An applet is a simple .js file hosted on GitHub that contains one or more named functions. AICord runs them in a safe sandbox and invokes the appropriate one based on context (like a user message, or Discord event).

Think of applets like "mini apps" your characters can use. They're plug-and-play extensions of their minds.

📦 What Does an Applet Look Like?

Here’s the simplest applet:

applet.js

export async function run(input) {
  return "Hello from my applet!";
}

Or add multiple event handlers:

applet.js

export async function run({ city }) {
  const res = await fetch(`https://wttr.in/${city}?format=3`);
  return await res.text();
}

export async function onGuildMemberAdd({ user }) {
  return `Welcome ${user.username}! 🎉`;
}

Your AI character will call the right function when it needs it.

⚡ Supported Functions

Each function gets the inputs as one input param, and you need to unbox it.

Function Name	Triggered When...	Params
run(input)	This is the default function. AI uses the applet as a tool (for example when user asks about weather)	Anything your applet requires
onGuildMemberAdd({user})	A user joins the server	Discord user object within user value

More coming soon! Suggest new events on our Discord server!

🧠 Agentic AI + Applets = Magic

Applets power your AI characters to interact with the world. With applets, they can:

• Fetch stock prices

• Call APIs like OpenWeather or HuggingFace

• Send Discord messages

• React to users joining

• Access user-provided secrets (API keys)

It’s like giving your AI a Swiss Army knife — and you control what tools it gets.

🔐 Using Secrets

Add placeholders like:

const API_KEY = "{{OPENWEATHER_KEY}}";

When run, AICord will inject the actual secret. You keep your code clean and safe. Secrets for applets can be defined on AICord Dashboard.

If your applet is public and someone clones it, they will need to add their own API keys so not yours is used.

Never hardcode your actual secrets & keys into the code directly!!! Especially when the GitHub repo and Applet is public.

✅ What’s Allowed in Applets

Since Applets are executed as serverless functions in a safe container, there are some limitations. AICord Team is always working on extending these to allow you to use truly anything!

• ✅ fetch() — Make external API calls

• ✅ console.log() — Logs visible in your dashboard

• ✅ Use export function style syntax

• ✅ Use multiple named exports

• ✅ AICord passes some common and popular modules to your code automatically without you having to import them. You can suggest modules in Discord server.

• 🚫 3rd party import/require — Not supported (yet!)

• 🚫 fs or file system access

• 🚫 Long-running code (>60s timeout)

Note: You can still expose helper functions within your file and AICord will run it in a controlled Node.js VM with specific permissions you configure.

🌤 Sample Applet: Weather

export async function run({ city }) {
  const res = await fetch(`https://wttr.in/${city}?format=3`);
  return await res.text();
}

⚙️ How Applets Work Behind the Scenes

1. AICord fetches your applet file from GitHub.
2. It replaces all {{secrets}} placeholders.
3. The code is sandboxed and compiled.
4. When an event or tool call happens, the matching function is executed.

Events are dynamically routed. If your applet exports onGuildMemberAdd, it runs only when a user joins.

Applet Manifest JSON schema

{
    "toolMetadata" : {
        "name" : "string", // Appet name without spaces (e.g. "getWeather")
        "description": "string", // Applet description
        "appletID": "string", // Applet ID auto generated by AICord
        "visibility": "public" | "private", // Applet visibility
        "repo" : "string", // Applet's GitHub repo (e.g "aicordapp/applet-example")
        "codePath" : "string", // (Optional) path/to/your_file.js in repo if applet code is in a file different than applet.js
        "branch" : "master", // (Optional) Branch if you use different than "main"
        "ghtoken" : "string" // (Optional) Only for private applets! Your GitHub access token to access repo if it's private
    },
    "input": {
        "key" : "string" // Input fields your Applet run() function receives. You should only specify input names and data types in manifest
        // Example 1: "city" : "string"
        /* Example 2: "person" : {
            "name": "string",
            "age" : "integer"
        }
        */
    },
    "triggers" : ["onGuildMemberAdd"], // Supported trigger events to execute your applet's designated function when fired
    "secrets" : { // User-defined secrets / API keys. If a user installs your applet, they will be required to add their own secrets and won't be able to see yours
        "OPENWEATHER_API_KEY" : "sk-xxx123456" // Secrets added in a key : value format
        // Secrets defined like this are replaced with this secret value in applet code during runtime : {{OPENWEATHER_API_KEY}}
    }
}

Important! For public applets, you can only use public GitHub repositories. Do not use a private repo and ghtoken for public Applets!

🧪 How to Build Your Applet

1. Create a public GitHub repo (e.g., aicordapp/weather-bot)

2. Add your code in applet.js (recommended). Using the main branch is recommended

3. Create an applet on AICord Dashboard and add your JSON manifest (schema is above this section)

4. Once you added your own applet or installed an applet made by someone else, you can select the applet when editing a character in advanced section.

Once done, you can trigger tool runs or wait for event hooks (like user joins).

AICord has a GitHub repo with applet examples & templates here

Planned updates: A more dynamic and secure way to publish and edit applets, ability to update applets from original applet or decentralized applet manifests in GitHub repo