Skip to content
devsess
Esc
↑↓navigate↵open⌘Jpreview

devsess/services

Define scoped services with custom Effect handlers or Docker containers. Definitions do not start anything; use Service.run(session, def) directly or provide def.layer and yield def.key.

When DEVSESS_SOCKET, DEVSESS_RUN_ID, and DEVSESS_SERVICE are set, ready Service.make and Service.container services report their names and ports to the daemon and retract them when their scopes close. Reporting is silent and best-effort; older daemons can ignore it.

Under devsess start, reported services appear with their ports beneath the owning process in expanded devsess status and the menu bar. Child rows are informational; stop and restart act on the parent process.

Handler services

import { Service } from 'devsess/services'
import { Effect } from 'effect'

const api = Service.make({
	name: 'api',
	ports: ['http'],
	start: (ctx) => Effect.gen(function* () {
		// Acquire your server here and register its cleanup in the scope.
		// Wait until it is ready before returning.
		yield* Effect.logInfo('ready')
		return { url: `http://127.0.0.1:${ctx.ports.http}` }
	}),
})

const running = yield* Service.run(session, api)
running.url
running.ports.http // number, inferred from the declared port names

The start handler receives a ServiceContext<Port>:

  • session: the selected DevSession.
  • ports: allocated host ports for the names in ports (optional, defaults to no ports). They are persisted under <service>:<port> using getStickyPort; remembered ports are preferred, not guaranteed if unavailable.
  • dataDir: <session>/services/<name>, created before start runs and kept after it stops.

start must resolve once the service is ready, not when it stops. Register resource cleanup with the enclosing Effect scope (for example, Effect.acquireRelease); closing that scope stops the service. run merges the handler’s object output with { ports }, replacing any output ports field with the allocated ports. Non-object output is discarded. Handler errors retain their own types; preparation and Docker failures use ServiceError. Log lines from start are annotated with service: <name>.

Long-running subprocesses: runManagedSubprocess resolves only when the child exits. Fork it in the service scope (for example, yield* runManagedSubprocess(...).pipe(Effect.forkScoped)), then wait for a readiness signal or probe before returning from start. Merely forking the child does not establish readiness.

Direct run calls require FileSystem and Path, plus whatever services the handler uses. Supply a scope when the handler acquires scoped resources. Each direct call runs the handler again; use layers to share an instance.

Shared services

Use a shared handler for slow-to-start infrastructure needed by multiple dev processes. The first caller starts a detached host; later callers reuse it, without a daemon. Service.run, def.key, and def.layer keep the same consumer API.

import { Service } from 'devsess/services'
import { Effect, Schema } from 'effect'

export const engine = Service.make({
	name: 'engine',
	ports: ['api'],
	shared: {
		output: Schema.Struct({ url: Schema.String }),
	},
	start: (ctx) => Effect.gen(function* () {
		// Acquire infrastructure and wait for readiness here.
		return { url: `http://127.0.0.1:${ctx.ports.api}` }
	}),
})

output is the only shared option: a required Effect codec for the handler’s return value. The host encodes it, consumers decode it, and devsess adds the allocated ports. Service.make captures its calling file automatically from the stack. Export the shared definition from that file, with exactly one matching export by service name, and keep it free of top-level CLI execution. The host imports that file using the caller’s runtime and loader arguments; TypeScript modules need Bun, a Node TypeScript loader, or a Node version supporting their syntax. Supply any application-specific layers inside start; the host provides Node platform services, not the consumer’s Effect context.

Shared services always belong to the fixed shared-services session at the current worktree’s monorepo root, independent of the caller’s selected session. Starting at the caller’s project directory, devsess walks upward to the nearest .git file or directory and selects the topmost directory containing package.json at or below that boundary. Without a .git boundary it uses the caller’s project directory. A nested worktree’s .git file stops the walk before the outer checkout, so worktrees remain isolated. This differs from DevSessions.layer (nearest package root); --local and awaitRunning routing do not change.

Only the host allocates sticky ports and runs start. Sticky-port state updates are locked across processes, including for non-shared services. Each consumer holds a socket lease until its scope closes. Five seconds after the last consumer leaves, the host stops accepting connections and stops the service under the startup lock. A caller arriving during teardown waits for cleanup before starting a replacement. Startup and lock contention have no fixed timeout: callers wait for readiness or host exit, with the tail of the host log reported on failure. A killed host’s stale socket is recovered by the next caller; existing consumers log an error rather than silently restarting.

ctx.dataDir is <root>/.data/sessions/shared-services/services/<name>/ and belongs exclusively to the handler. Host bookkeeping lives separately in <root>/.data/sessions/shared-services/hosts/<name>/: host.sock carries readiness and leases, startup.lock is a short-lived lock directory, and service.log appends host stdout/stderr. The fixed session is created on first use through DevSessions.getOrCreate; idempotent directory creation needs no lock. Service data survives shutdown. Daemon reporting remains best-effort and scoped to consumers; the host does not inherit their DEVSESS_* identity.

For long directory paths, devsess connects through a stable, short symlink in the OS temporary directory to stay within Unix socket pathname limits; the socket itself remains in the host bookkeeping directory.

Container services

const cache = Service.container({
	name: 'redis', image: 'redis:7',
	ports: { redis: 6379 },
	volumes: { data: '/data' },
	env: { MY_SETTING: 'value' },
	healthcheck: { test: ['CMD', 'redis-cli', 'ping'], interval: '1 second', timeout: '2 seconds', retries: 30, startPeriod: '1 second' },
})
const running = yield* Service.run(session, cache)
running.ports.redis
running.container // Docker container name

Service.container defines a handler backed by Docker. ports maps names to container ports; allocated host ports bind only to 127.0.0.1. volumes maps names to container paths; host directories are <session>/services/<service>/<volume>. Healthcheck test accepts compose-style ['CMD', ...] or ['CMD-SHELL', '...']; durations accept Effect Duration inputs. When configured, the healthcheck must pass before start resolves; without one, it resolves after the container starts. Containers require a scope, DevSessions, FileSystem, Path, and the platform’s ChildProcessSpawner.

The container runs as your host UID:GID, with no root override. This keeps session files owned by you; otherwise, rootful Docker on Linux can leave root-owned bind-mount files that block copying branch data, removing worktrees, or deleting .data without sudo (Docker Desktop and OrbStack on macOS work either way). Images requiring root may fail; ServiceError includes a hint if they exit before healthy. On each container start, devsess removes containers labelled with this project root whose session directory no longer exists. On scope close it removes the active container but leaves all data directories intact. A cold image pull prints progress. Docker Desktop, OrbStack, or a running Docker daemon is required; PGlite needs no Docker. See the Postgres recipe.

Compose services with layers

Yield a definition’s key inside another handler to declare a dependency. Provide its layer to satisfy that dependency:

import { CurrentSession, DevSessions } from 'devsess'
import { NodeServices } from '@effect/platform-node'
import { Effect, Layer } from 'effect'

const worker = Service.make({
	name: 'worker',
	start: () => Effect.gen(function* () {
		const redis = yield* cache.key
		return { redisPort: redis.ports.redis }
	}),
})

const services = Layer.mergeAll(
	cache.layer,
	worker.layer.pipe(Layer.provide(cache.layer)),
)

const program = Effect.gen(function* () {
	const redis = yield* cache.key
	const runningWorker = yield* worker.key
	// Both consumers share the same cache instance.
}).pipe(
	Effect.provide(services),
	Effect.provide(CurrentSession.layer),
	Effect.provide(DevSessions.layer),
	Effect.provide(NodeServices.layer),
	Effect.scoped,
)

Each def.layer builds the service from CurrentSession once per layer build and shares it between consumers. Keep and reuse that layer value when wiring dependencies; its resources stop when the layer’s scope closes. For an explicit session, provide CurrentSession.layerOf(session) instead.

Was this page helpful?