> ## 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.

# Actors Overview

> Learn how actors run shared, live sessions with realtime messages and timers

<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>

An actor is a long-running backend process that multiple clients connect to simultaneously.

With actors, you can build live session instances that support the following functionality:

* **Realtime messaging:** Send and receive messages with clients via WebSockets.
* **Persistent storage:** Keep session state alive between idle periods.
* **Scheduled work:** Run logic at a set interval or at a specific time.

Use actors when you're building features where multiple clients require realtime updates and interaction, such as a chat room or multiplayer game.

## Actors

[`Actor`](/developers/backend/resources/actors/reference) is the class you extend in your backend.

The actor class defines the behavior of a live session. With actors, you can:

* **[Manage connections](#connections):** Accept or reject a client connecting to the session, and identify who is connecting.
* **[Handle messages](#realtime-messages):** Receive a message from a client, update session state, and reply to one client or broadcast to all.
* **[Schedule work](#scheduled-work):** Run logic on an interval or at a scheduled time.

## Sessions

A session is a running instance of an actor, identified by the actor name and a session ID you choose.\
Each session manages its own state, storage, and client connections independently.

### Connections

A connection represents a client's WebSocket to a session. Each client that joins gets a unique connection. An actor uses that connection to identify who is connecting, manage client connections, and send messages.

To learn more, see [connections](/developers/backend/resources/actors/reference#connections). For a sample flow, see [manage client connections](/developers/backend/resources/actors/sample-flows#manage-client-connections).

### Active and idle sessions

A session is always in one of the following states:

* **Active:** The session is live and processing events. A session becomes active when a client connects, when a client messages an idle session, or when a scheduled wake time arrives.
* **Idle:** The session isn't processing events. A session goes idle shortly after it finishes its last message and all scheduled work stops. The session maintains its [stored data](#storage), scheduled times, and open connections until it becomes active again.

When a session goes idle, clients with open connections stay connected. Their next message or a scheduled [wake](#wakes) activates the session again.

## Client

Use [`base44.actors`](/developers/references/sdk/docs/type-aliases/actors) in the JavaScript SDK to connect a client to an actor session and exchange messages.

The actors SDK supports the following functionality:

* **Connect:** Open a WebSocket connection to a session.
* **Subscribe:** Receive messages from the actor.
* **Send:** Send messages to the actor.
* **Close:** Close the WebSocket connection to the actor.

To learn more, see [connect a client to a session](/developers/backend/resources/actors/sample-flows#connect-a-client-to-a-session).

## How actors and clients interact

The following diagram shows the general interaction between a client and an actor:

```mermaid theme={null}
sequenceDiagram
    participant C as Client
    participant A as Actor

    C->>A: 1. connect(sessionId)
    A->>A: 2. handleStart()
    A->>A: 3. handleConnect(conn)
    C->>A: 4. send(data)
    A->>A: 5. handleMessage(conn, msg)
    A-->>C: 6. broadcast(data)
    C->>A: 7. close()
    A->>A: 8. handleClose(conn)
```

1. The client connects to the actor over a WebSocket.
2. The session activates. [`handleStart()`](/developers/backend/resources/actors/reference#lifecycle-handlers) runs on first start and each time the session activates from idle.
3. The actor handles the connection. You can check the client's identity and reject the connection, or send the current state.
4. The client sends a message.
5. The actor handles the message. You can validate the format and the sender's permissions before you change session state.
6. The actor broadcasts the update to every connected client, or replies only to the sender.
7. The client closes the connection.
8. The actor handles the disconnect. You can remove per-connection state.

## Realtime messages

Each connected client belongs to a session and can send messages in realtime via WebSockets. Clients can also listen for incoming messages using [`subscribe()`](/developers/references/sdk/docs/type-aliases/actors#subscribe).

<Note>
  Base44 provides several realtime features that use a subscription-based listener:

  * Actor [`subscribe()`](/developers/references/sdk/docs/type-aliases/actors#subscribe) listens for messages the actor sends to connected clients.
  * Entity [`subscribe()`](/developers/references/sdk/docs/type-aliases/entities#subscribe) listens for changes to app entities.

  Check which service you use so you receive the events you expect.
</Note>

With realtime messages, you can:

* Reply to a specific client.
* Broadcast to all connected clients.
* List the clients that are currently connected.
* Identify each client and check whether the client has logged in.

To learn more, see [connections](#connections). For a sample flow, see [manage client connections](/developers/backend/resources/actors/sample-flows#manage-client-connections).

## Message types

A client and an actor exchange messages over a connection. Messages fall into the following types:

* **Incoming messages:** What a connected client sends to the actor, such as a text, a move, or a vote. The client sends them with [`send()`](/developers/references/sdk/docs/type-aliases/actors#send), and the actor receives them in [`handleMessage()`](/developers/backend/resources/actors/reference#lifecycle-handlers).
* **Outgoing messages:** What the actor sends to connected clients, such as a reply to a client, a broadcast to all connected clients, or the current board when someone joins. The actor sends them with [`conn.send()`](/developers/backend/resources/actors/reference#connections) or `broadcast()`, and the client receives them in a [`subscribe()`](/developers/references/sdk/docs/type-aliases/actors#subscribe) callback.

We recommend typing your messages so the actor and the client agree on each message's shape:

* **Backend:** Pass `Incoming` and `Outgoing` types as generics to the `Actor` class. For a complete example, see [create an actor](/developers/backend/resources/actors/create-actor).
* **Client:** Extend the [`ActorRegistry`](/developers/references/sdk/docs/type-aliases/actors#actorregistry) interface with the same shapes, so TypeScript checks the types of `send()` and `subscribe()`.

## Storage

Actors provide several storage options depending on how your session uses and retains data:

* **[In-memory storage](#in-memory-storage):** Working state that lives in class fields while the session is active and resets when the session goes idle.
* **[Persistent storage](#persistent-storage):** A key-value store for data that needs to survive when the session goes idle.

### In-memory storage

Class fields hold the working state while the session is active, such as the current board or a round timer. Use in-memory storage when your data changes frequently and doesn't need to persist when the session goes idle, such as a live score or a cursor position.

When a session becomes idle, class fields reset.

### Persistent storage

Each session has its own key-value store that you can fully manage.
Use persistent storage when your data needs to survive when the session goes idle, such as chat history or a game board.

To store data that's available across the entire app, use [entities](/developers/backend/resources/entities/overview).

To learn more about actor storage, see [storage](/developers/backend/resources/actors/reference#storage).

### Restoring state

When a session goes idle, in-memory state resets. Persistent storage survives, but the session doesn't automatically load the stored data back into memory when the session activates.

Use [`handleStart()`](/developers/backend/resources/actors/reference#lifecycle-handlers) to restore persistent data, such as the chat history or the game board.

For a sample flow, see [persist session data](/developers/backend/resources/actors/sample-flows#persist-session-data).

## Scheduled work

Actors provide functionality for a session to run logic on a schedule, independent of client messages:

* **[Ticks](#ticks):** Run code on an interval and keep the session active while they repeat.
* **[Wakes](#wakes):** Run once at a time you choose, whether the session is active or idle.

### Ticks

Ticks run code on an interval, and they keep the session active while they repeat.

Use [`shouldTick()`](/developers/backend/resources/actors/reference#timer-handlers-and-settings) to set the conditions for when ticking runs.
An actor re-evaluates `shouldTick()` after every connection, message, disconnection, and tick, so ticking stops as soon as the condition is no longer met.

<Note>
  Ticking needs at least one connected client.
</Note>

With ticks, you can:

* Choose the length of each interval.
* Define a condition that starts and stops ticking, such as "at least two players are in the session."
* Write the code that runs each interval.

Use ticks to keep a session active even when clients aren't sending messages, such as updating a round timer.

To learn more about ticks, see [timer handlers and settings](/developers/backend/resources/actors/reference#timer-handlers-and-settings) and [run ticks](/developers/backend/resources/actors/sample-flows#run-ticks) for a sample flow.

### Wakes

A wake runs once at a time you choose, whether the session is active or idle.

With wakes, you can:

* Schedule when a wake runs.
* Implement logic that runs when a wake occurs.

Use a wake to schedule a one-time action, such as ending a game turn, closing an empty lobby, triggering a reminder, or starting an event at a specific time.

To learn more about wakes, see [timer handlers and settings](/developers/backend/resources/actors/reference#timer-handlers-and-settings) and [schedule wakes](/developers/backend/resources/actors/sample-flows#schedule-wakes) for a sample flow.

## Deploy an actor

Deploy actors with [`actors deploy`](/developers/references/cli/commands/actors-deploy). To push all project resources at once, use [`deploy`](/developers/references/cli/commands/deploy). Deploying adds and updates remote actors and leaves the rest in place.

## Delete an actor

To delete an actor:

* Run [`actors delete`](/developers/references/cli/commands/actors-delete) to delete the remote actor from Base44.
* Delete the actor directory from your local project.

<Note>
  If you don't delete the actor from your local project, the next [`actors deploy`](/developers/references/cli/commands/actors-deploy) or [`deploy`](/developers/references/cli/commands/deploy) recreates and deploys the actor to your Base44 project.
</Note>

## See also

* [Create an Actor](/developers/backend/resources/actors/create-actor): Actor files and a minimal class
* [Actors: Sample Flows](/developers/backend/resources/actors/sample-flows): Lifecycle, timers, connections, storage, entities, and backend functions
* [Actors Files and Code](/developers/backend/resources/actors/reference): Complete backend class API
* [`actors` SDK reference](/developers/references/sdk/docs/type-aliases/actors): Client SDK API


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