Services

Services are long-running processes belonging to a project. The SDK resolves a service (honouring cross-project identifiers and an optional worktree override) and exposes its lifecycle, all attributed to your SDK client.

Retrieving a service

const project = await denvig.projects.retrieve('github:marcqualie/denvig')

const service = await project.services.retrieve('api')

// In a sibling worktree
const featureApi = await project.services.retrieve('api', { worktree: 'feature/x' })

Lifecycle

// Start and return the resulting status
const started = await service.start()

// Stop and return the resulting status
await service.stop()

// Current status, including recent log lines
const status = await service.status()

Start options

await service.start({
  port: 'random',                // a number, or 'random' for a free dev port
  domains: ['api.local'],        // claim these domains for this start
})

Option	Description
port	A specific port number, or 'random' to always allocate a free port. When omitted, uses the configured port and falls back to a random one if it’s busy.
domains	Explicit domains to route to this start, replacing the configured domains. Each domain is claimed unconditionally — any existing route is taken over and handed back to its previous owner when this service stops.

Tip

Passing domains is how you swap a domain between worktrees of the same project while both copies of the service are running. See the Gateway & Worktrees guide.

Listing services

project.services.list() returns rendered rows — each a service plus where it sits in the project/worktree tree.

const rows = await project.services.list({ worktrees: true })

for (const row of rows) {
  console.log(row.depth, row.label, row.service.name, row.service.status)
}

Option	Description
all	List services across all projects and global services.
global	List only global services.
worktrees	Nest each project’s worktree services beneath it.
worktree	Target a sibling worktree by branch name (main = primary).
status	Filter by runtime status — a value, a list, or a comma-separated string.

Resolving a service context

context resolves a service identifier to its manager, name, and target checkout — honouring cross-project identifiers such as slug/service or id:abcd/svc.

const ctx = await project.services.context('marcqualie/denvig/hello')
console.log(ctx.serviceName, ctx.target)