​

Deploy

​

What is supported today

• Postgres only. PGlite is for development and tests, one process per data directory. Production PGlite is not supported.
• Single runner or a TCP runner cluster. Runner.socket is the public Postgres configuration for separate processes. Runners authenticate each other with mutual TLS (Runner.mtls). Three-process command, relay, singleton, schedule, SIGKILL, and rolling-drain drills run on one host; separate-host networks and hosting providers still require their own evidence.
• Embedded or served. Actors.serve serves commands, reducers, and queries over HTTP, connections over WebSocket, and feeds, streams, and watches over SSE. These transports are verified behind Bun’s HTTP server on loopback; no proxy, load balancer, or hosting provider has been verified.
• No managed hosting. Hosted runners are planned.
• Not on npm yet. Install @rikalabs/akter from a locally packed tarball, as in the quickstart, until the first alpha release.

​

The process

const runtime = Layer.unwrap(
  Effect.gen(function* () {
    const database = yield* Config.String("DATABASE_URL")

    return RoomLive.pipe(
      Layer.provideMerge(
        Actors.layer({
          authorize: ({ caller, ref }) =>
            Effect.succeed(Schema.is(User)(caller) && ref.tenant === "chat-demo"),
        }),
      ),
      Layer.provide(Database.postgres({ url: Redacted.make(database) })),
    )
  }),
).pipe(Layer.provide(BunCrypto.layer))

HttpRouter.serve(routes).pipe(
  Layer.provide(runtime),
  Layer.provide(BunHttpServer.layer({ port: 3000 })),
  Layer.launch,
  BunRuntime.runMain,
)

​

The database

• Framework tables are created and migrated when the runtime starts; see migrations for how startup refuses a database it cannot migrate safely.
• Owned tables are yours. Create and migrate them with drizzle-kit before the runtime starts; startup fails if a declared table is missing or claimed by another actor type.
• State upcasts through the migrations declared on Actor.state, one actor at a time, inside turns. No batch migration is needed.

​

Several runners

import { readFile } from "node:fs/promises"
import { Effect, Layer, Redacted } from "effect"
import { Actors, Database, Runner } from "@rikalabs/akter/runtime"

const runner = Runner.socket({
  address: { host: "runner-a.internal", port: 4400 },
  listenAddress: { host: "10.0.0.5", port: 4400 },
  transport: Runner.mtls({
    deployment: "shop-production",
    credentials: Effect.promise(async () => ({
      ca: await readFile("/etc/akter/peer/ca.pem", "utf8"),
      certificate: await readFile("/etc/akter/peer/certificate.pem", "utf8"),
      key: Redacted.make(await readFile("/etc/akter/peer/key.pem", "utf8")),
    })),
  }),
  shardsPerGroup: 256,
  shardLockExpiration: "35 seconds",
  shardLockRefreshInterval: "10 seconds",
})

const runtime = RoomLive.pipe(
  Layer.provideMerge(Actors.layer().pipe(Layer.provide(runner))),
  Layer.provide(
    Database.postgres({
      url: Redacted.make(databaseUrl),
      maxConnections: 20,
      offTurnConnections: 5,
    }),
  ),
)

​

Sizing

• Connections. Each command holds one Postgres connection until its transaction ends; a pipelined chain keeps its session until the chain ends. Database.postgres({ maxConnections }) defaults to 50, offTurnConnections and queryConnections to 10 each; count every pool targeting the server, plus migrations, backups, and operator sessions, under its max_connections. A pooler in front of Postgres is unverified.
• Memory. A resident actor holds about 20 KiB of JavaScript heap on the measured runner, so the default maxResidentActors of 10,000 is about 200 MiB. A command that needs a new activation past the limit fails RunnerAtCapacity, and its handle retries until an idle actor hibernates.

​

Serving over HTTP

• TLS. Serve Actors.serve behind TLS. Credentials and Idempotency-Key travel in headers, and the framework cannot tell whether a proxy terminates TLS, so it does not refuse plain HTTP.
• Authentication. Actors.serve requires an auth provider. Use Auth.jwt({ issuer, audience, jwks, tenant }) from @rikalabs/akter/runtime for tokens from an identity provider, Auth.make for your own, and Auth.none only for deliberately public actors. Authorization is still your authorize callback.
• Browsers. List allowed browser origins in origins. Behind a proxy, list the public origin: forwarding headers are not trusted.
• Clients. The OpenAPI document at openapi.path generates clients in any language; see generating clients. Every client must keep one Idempotency-Key across its retries of a command.
• Retry window. Actors.serve refuses a runtime whose retry window is below 60 seconds. The default is one day.

​

Releasing a new version

1. Apply owned-table migrations that the old and new code both accept (expand before contract).
2. If you changed a workflow, check that no open execution needs a removed or renamed step. Startup refuses such a deploy. akter workflows check --entry <module> --database-url <url>, from apps/cli in the repository (not yet published), runs the same check first.
3. Keep every event, job, and workflow payload decodable until the records that use it have passed their retention.

​

Checklist

• Postgres, a database for this app alone, and DATABASE_URL in a secret.
• Owned-table migrations applied before start.
• authorize allows only the callers and tenants you expect, and Actors.serve has a real auth provider.
• TLS in front of the HTTP server, and origins set for browser clients.
• maxConnections × processes within the server’s max_connections.
• One process per runner address, matching shard count and expiration across the database.
• A private peer network, direct advertisement, readiness gating, and drain before closing old runners.
• Logs collected: deterministic defects, dead-lettered jobs, and outbox retries are logged as warnings and errors. See observability.