Documentation

Introduction

What GuildScript is, who it is for, and the core concepts you need before writing your first agent.

What is GuildScript?

GuildScript is a Discord bot that ships with no built-in behaviors. Instead of giving you a fixed menu of commands, it gives you a secure JavaScript runtime inside your server. You write small programs called agents, upload them through a slash command, and GuildScript runs them automatically whenever the event they subscribe to happens: a message arrives, a member joins, a button is clicked, and so on.

You never host anything. There is no server to rent, no process to keep alive, no deploy step. You upload a .js file inside Discord and it is live immediately.

Who is it for?

• Server owners and admins who want automations built precisely for their community instead of bending a general-purpose bot to fit.
• Developers who know some JavaScript and want bot-level power without running infrastructure.
• Non-programmers too: the built-in /vibe-code-agent command can write agents for you using an AI provider you connect.

What problems does it solve?

• Hosting: running your own bot means servers, uptime, tokens, and deploys. GuildScript removes all of it.
• Inflexibility: off-the-shelf bots do what their developers imagined. Agents do exactly what you write.
• Bot sprawl: instead of inviting ten single-purpose bots, one GuildScript installation runs all of your custom behaviors side by side.
• Safety: every agent runs in an isolated sandbox with memory, time, and rate limits, so a buggy script cannot take your server (or the bot) down.

Core concepts

Agents

An agent is a single JavaScript file that exports one async function. Each agent is bound to exactly one event. When that event fires in your server, GuildScript calls your function with a snapshot of what happened. Agents are created and managed entirely with the /agents command.

Events

Events are the triggers agents react to. GuildScript currently supports 15 events, including messageCreate, guildMemberAdd, messageReactionAdd, and interactionCreate. The full list and each event's payload shape are covered in Lesson 2.

The sandbox

Agent code runs inside a QuickJS sandbox on GuildScript's infrastructure, not inside Discord and not on your machine. The sandbox has no network access, no file system, and no timers. It talks to Discord through a controlled API surface (the payload object), to your own MongoDB through the db helper, and to an AI provider through the llm helper. The Differences from discord.js page explains exactly what is and is not available.

Bring your own database and AI

GuildScript does not store your application data. If an agent needs persistence (scores, warnings, settings), you connect your own MongoDB Atlas cluster with /database. If an agent needs AI, you connect your own Groq, Mistral, or Gemini API key with /llm. Both credentials are stored encrypted and are never exposed to agent code.

Plans

Every server starts on the Free plan, which is enough to build and run real automations. Premium raises every limit: more agents, more servers, more runs per minute, more memory, and longer execution time. See Premium vs Free for the full comparison.

Quick start

1. Invite GuildScript to your server.
2. Run /initialize once. This switches the runtime on for the server.
3. Optionally run /database and /llm to connect storage and AI.
4. Run /agents, click Create New, name your agent, pick an event, and upload a .js file.
5. The agent runs automatically from that moment on. Manage it any time with /agents.