---
audience: engineers
summary: "How a Core's instance declaration controls memory partitioning and invocation\
  \ routing \u2014 stateless, entity, singleton."
title: Instance modes
path: concepts/instance-modes
status: published
---

Every Core declares an `instance` mode in its `@core` block. It governs whether the Core has memory at all, whether that memory is shared across invocations, and how the host routes incoming requests. Pick it up front — changing it later requires migrating the memory backend.

## :stateless

```scaicore
@core MyCore {
    instance = :stateless
}
```

The default and simplest mode. Every invocation runs against an empty memory namespace; nothing persists across calls. Use this for pure transformations, classifiers, anything where the answer is a function only of the inputs. Multiple invocations run in parallel without coordination.

## :entity

```scaicore
@core OrderAgent {
    instance = :entity {
        entity_key = order_id
        idle_timeout = 600000
        max_concurrent = 1
        max_active_instances = 1000
        overflow = "deactivate_lru"
    }
}
```

One instance per entity. The host extracts `entity_key` from each request's input and routes to a memory partition keyed on that value. Memory writes from one entity don't leak to another. Use this for per-user agents, per-order workflows, anything with a natural sharding key.

The optional fields cover instance lifecycle:

- `idle_timeout` — milliseconds before an idle instance is deactivated. Memory persists; the in-memory cache is dropped.
- `max_concurrent` — concurrent invocations against the same entity. `1` serializes (no races on memory); higher values let the entity handle parallel work.
- `max_active_instances` — cap on resident instances. Combined with `overflow` to control eviction.
- `overflow` — `"deactivate_lru"`, `"reject"`, or `"queue"`. What happens when an incoming request would exceed `max_active_instances`.

The verifier rejects entity-mode Cores whose entity key never appears in any flow's input (`E402`). If you declare it, you must use it.

## :singleton

```scaicore
@core ConfigCore {
    instance = :singleton
}
```

Exactly one instance, exactly one memory partition, shared across all invocations. Use this for configuration agents, global rate limiters, system-wide deduplication caches — anything that needs a single source of truth and tolerates serialized access.

Singleton + high concurrency is a contention recipe; pair it with `max_concurrent = 1` if state correctness matters, or accept the race.

## Picking one

The decision rule, in order:

1. Does the Core need memory at all? If no, `:stateless`. You're done.
2. Is there a natural per-entity boundary in the inputs (user ID, order ID, tenant ID)? If yes, `:entity` with that field as `entity_key`.
3. Does the state genuinely need to be global? If yes, `:singleton`. Be intentional about contention.

If you find yourself wishing for "stateless with shared memory" — that's `:singleton` with no instance bounds. If you find yourself wishing for "entity, but the entity_key is computed" — derive it before invocation and pass it in as a regular input field. The runtime won't infer it.