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

```ts
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.

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

```ts
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](/reference/pglite) needs no Docker. See the [Postgres recipe](/recipes/postgres-service).

## Compose services with layers

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

```ts
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.
