> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Internal links on these pages omit the .md extension. Append .md to a docs page URL, or send an Accept: text/markdown header, to get that page as markdown.

# Create an Actor

> Write your first actor and handle the connection lifecycle

<div className="dev-docs-banner">
  <div className="dev-docs-banner-content">
    <div className="dev-docs-banner-title">
      You're viewing developer documentation
    </div>

    <div className="dev-docs-banner-text">
      This documentation is for developers working with the Base44 developer
      platform.
    </div>
  </div>
</div>

Create an [actor](/developers/backend/resources/actors/overview#actors) to run backend logic for a live [session](/developers/backend/resources/actors/overview#sessions) that multiple [clients](/developers/backend/resources/actors/overview#client) share, such as a chat room or a multiplayer game. An actor handles client connections, messages, and disconnections from your backend.

## Actor files

Create actors as TypeScript files in your project's actors directory. Each actor lives in its own subdirectory under `base44/actors/` with an `entry.ts` file:

<Tree>
  <Tree.Folder name="base44" defaultOpen>
    <Tree.Folder name="actors" defaultOpen>
      <Tree.Folder name="chatRoom" defaultOpen>
        <Tree.File name="entry.ts" />
      </Tree.Folder>
    </Tree.Folder>
  </Tree.Folder>
</Tree>

The folder name becomes the actor name in the SDK and determines how clients call the actor, for example `base44.actors.chatRoom`. Export the actor class as the default export from the `entry.ts` file.

You can include additional `.ts`, `.js`, `.json`, and `.jsonc` files in the actor directory and import them from `entry.ts`.

## entry.ts

The code file contains your actor class. Import `Actor` from `base44:runtime/actors` and export a class that extends `Actor` as the default export. Pass `Incoming` and `Outgoing` generics to type the messages the actor receives and sends.

Implement the following class methods. The `handleStart()` method is optional:

* `handleStart()`: Load saved session data from storage into class fields. Base44 calls this handler each time the session activates, so your restored state is ready before Base44 handles any connection. For a full storage example, see [persist session data](/developers/backend/resources/actors/sample-flows#persist-session-data).

* `handleConnect()`: Send the current session state to the connecting client. To reject connections or identify clients, see [manage client connections](/developers/backend/resources/actors/sample-flows#manage-client-connections).

* `handleMessage()`: Update session state, persist the state, and broadcast the change.

* `handleClose()`: Remove any state tied to that connection. If there's no connection state to clear, write an empty body.

* `handleTick()`: Run code on each tick interval. If the actor doesn't use ticks, write an empty body. To set up ticks, see [run ticks](/developers/backend/resources/actors/sample-flows#run-ticks). To schedule a one-time wake, see [schedule wakes](/developers/backend/resources/actors/sample-flows#schedule-wakes).

The following example shows a simplified `ChatRoom` actor:

```typescript theme={null}
import { Actor } from "base44:runtime/actors";

type Incoming = { type: "message"; text: string };
type Outgoing =
  | { type: "history"; messages: string[] }
  | { type: "message"; text: string };

export default class ChatRoom extends Actor<Incoming, Outgoing> {
  messages: string[] = [];

  async handleStart() {
    this.messages = (await this.storage.get<string[]>("messages")) ?? [];
  }

  async handleConnect(conn) {
    conn.send({ type: "history", messages: this.messages });
  }

  async handleMessage(_conn, msg) {
    this.messages.push(msg.text);
    await this.storage.put("messages", this.messages);
    this.broadcast({ type: "message", text: msg.text });
  }

  async handleClose(_conn) {}

  async handleTick() {}
}
```

## See also

* [Actors Overview](/developers/backend/resources/actors/overview): Concepts and terminology
* [Actors Files and Code](/developers/backend/resources/actors/reference): Complete backend class API
* [Actors: Sample Flows](/developers/backend/resources/actors/sample-flows): More patterns for timers, connections, storage, and entities
* [`actors deploy`](/developers/references/cli/commands/actors-deploy): Deploy your actor to Base44


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.