Getting Started

Create a New Project

Agent8 is built on a Vite-based React TypeScript project, providing a fast and efficient development environment.

To initialize a new project, run one of the following commands based on your package manager:

npm create vite@latest my-app -- --template react-ts

yarn create vite my-app --template react-ts

pnpm create vite my-app --template react-ts

Install Dependencies

After creating your project, navigate to the project directory and install the Agent8 client SDK:

npm install @agent8/gameserver

yarn add @agent8/gameserver

pnpm add @agent8/gameserver

This installs the Agent8 React client (hooks and the server object) and nothing else. The server-side tools are separate packages that you run straight from npm with npx, so there is nothing more to add here:

• @agent8/gameserver-node — scaffolds, tests and builds the server
• @agent8/deploy — deploys it
• @agent8/cli — calls a deployed function from the terminal

Create the Server

Your server lives in server/src/ as a TypeScript class. From the project root, scaffold it:

npx -y @agent8/gameserver-node init

export class Server {
  async add(a: number, b: number): Promise<number> {
    return a + b;
  }
 
  // ...the generated examples (ping, getMyAccount, …)
}

Add the add method to the generated Server class. Every method on it can be called from the client, and it can use the server globals — $global, $room, $asset, $sender and the rest (Server Globals).

Test Locally

Add a test to server/test/server.test.ts:

describe('Server', () => {
  test('add returns the sum', async (server) => {
    expect(await server.add(1, 2)).toBe(3);
  });
});

Then run the tests from the project root (not from server/). test builds the server first:

npx -y @agent8/gameserver-node test

To call functions by hand instead, npx -y @agent8/gameserver-node dev opens an interactive console where you type add(1, 2). More on tests, the console and splitting code across files: Structured Project.

Deploy

On the Agent8 platform, push your code — the platform builds and deploys the server for you.

Hosting the project yourself, build and then deploy:

npx -y @agent8/gameserver-node build
npx -y @agent8/deploy

On the first run the deploy tool creates a verse for your project and writes its id, VITE_AGENT8_VERSE, to two files: .agent8.lock, which the deploy tool targets, and .env, which your Vite client reads (import.meta.env.VITE_AGENT8_VERSE). Both are written only then and never synced, so to point the project at a different verse later, change it in both — editing one alone leaves your deploys and your client on different verses.

Testing the Deployment

You can test your deployed server function by invoking it directly from the terminal:

npx -y @agent8/cli call add '[1, 2]'

This command calls the add function with the arguments 1 and 2, and you should see the result 3 printed in your terminal.

Call the Server from the Client

Now, let’s integrate the server function into your client application, enabling your React components to communicate with the server.

1. Update Client Code

   useGameServer() is the React hook that connects to your deployed server and hands you the server object you call through:

import React from "react";
import { useGameServer } from "@agent8/gameserver";
 
export default function App() {
  const { connected, server } = useGameServer();
 
  if (!connected) return "Connecting...";
 
  const handleCallServer = async () => {
    const result = await server.remoteFunction("add", [1, 2]);
    console.log("Result from server:", result);
  };
 
  return (
    <div>
      <h1>Agent8 Server Communication</h1>
      <button onClick={handleCallServer}>Call Server</button>
    </div>
  );
}

2. Run the Project

   Start your development server by running:

npm run dev

yarn dev

pnpm dev

Open your browser and navigate to the local development server. Click the “Call Server” button to execute the add function on the server. The result should be logged in the browser’s console.

If the Browser Logs Nothing

The terminal test and the Vite dev server do not necessarily talk to the same verse. Under vite dev the SDK connects to <VITE_AGENT8_VERSE>-preview — a separate, empty verse with no fallback to the bare one — while npx -y @agent8/deploy deployed to the bare <VITE_AGENT8_VERSE>, which is what the CLI test called. useGameServer() returns the verse it connected with; log it once connected is true to confirm.

Two ways to line them up for local development:

• Pass the deployed verse explicitly. In dev an explicit verse wins over the suffix:

  const { connected, server } = useGameServer({
    verse: import.meta.env.VITE_AGENT8_VERSE,
  });

• Or run a production build instead of the dev server — npm run build && npm run preview. Outside dev the SDK uses the bare verse with no suffix.

Where to Go Next

You have set up an Agent8 project, tested and deployed a server function, and called it from your client application. From here:

• Remote Function — the call you just made, in full: return-value, fire-and-forget and throttled variants, the limit of 10 standard calls per second per function name, and the connectionStatus a shipped game shows instead of “Connecting…”.
• Server Globals — the reference for $global, $room, $asset, $sender, $lock, $roomTick and the $on* handlers.
• Structured Project — tests, the dev console, handler namespaces, and runtime limits.
• Global State — state that persists across sessions.
• Room System — matchmaking, lifecycle hooks and ephemeral per-room state.

Have an existing single-file server.js? It still deploys as-is — see server.js (Legacy Format), and Structured Project for moving it across.