ContextQMD
Back to Rivet

Destroying Actors

website/src/content/docs/actors/destroy.mdx

2.2.12.9 KB
Original Source
  • User account deletion
  • Ending a user session
  • Closing a room or game
  • Cleaning up temporary resources
  • GDPR/compliance data removal

Actors sleep when idle, so destruction is only needed to permanently remove data — not to save compute.

Destroying An Actor

Destroy via Action

To destroy an actor, use c.destroy() like this:

typescript
import { actor } from "rivetkit";

interface UserInput {
  email: string;
  name: string;
}

const userActor = actor({
  createState: (c, input: UserInput) => ({
    email: input.email,
    name: input.name,
  }),
  actions: {
    deleteAccount: (c) => {
      c.destroy();
    },
  },
});

Destroy via HTTP

Send a DELETE request to destroy an actor. This requires a token for authentication:

  • Rivet Cloud: Use the service key (sk_*) from your RIVET_ENDPOINT URL. Find this in the dashboard under Settings > Advanced > Backend Configuration (e.g. the sk_... portion of https://default:[email protected]).
  • Self-hosted: Use an admin token.
<CodeGroup>
typescript
const actorId = "your-actor-id";
const namespace = "default";
const token = "your-token";

await fetch(`https://api.rivet.dev/actors/${actorId}?namespace=${namespace}`, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
bash
curl -X DELETE "https://api.rivet.dev/actors/{actorId}?namespace={namespace}" \
  -H "Authorization: Bearer {token}"
</CodeGroup>

To find the actor ID, you can list actors first:

bash
curl "https://api.rivet.dev/actors?namespace={namespace}" \
  -H "Authorization: Bearer {token}"

Destroy via Dashboard

To destroy an actor via the dashboard, navigate to the actor and press the red "X" in the top right.

Lifecycle Hook

Once destroyed, the onDestroy hook will be called. This can be used to clean up resources related to the actor. For example:

typescript
import { actor } from "rivetkit";

interface UserState {
  email: string;
  name: string;
}

// Example email service interface
const emailService = {
  send: async (options: { from: string; to: string; subject: string; text: string }) => {},
};

const userActor = actor({
  state: { email: "", name: "" } as UserState,
  onDestroy: async (c) => {
    await emailService.send({
      from: "[email protected]",
      to: c.state.email,
      subject: "Account Deleted",
      text: `Goodbye ${c.state.name}, your account has been deleted.`,
    });
  },
  actions: {
    deleteAccount: (c) => {
      c.destroy();
    },
  },
});

Accessing Actor After Destroy

Once an actor is destroyed, any subsequent requests to it will return an actor_not_found error. The actor's state is permanently deleted.

API Reference