# Runtime

## Overview

The `@antelopejs/interface-core/runtime` module exposes information about the runtime environment of the running project and a registry for development servers. The implementation is provided by the AntelopeJS core: `ajs project dev` reports development mode, while `ajs project start` and `ajs project run` report production mode.

## Import

```ts
import {
  GetRuntimeInfo,
  RegisterDevServer,
  DEV_REGISTRY_PATH,
} from "@antelopejs/interface-core/runtime";
```

## `GetRuntimeInfo`

Retrieves information about the runtime environment of the running project.

```ts
const info = await GetRuntimeInfo();
// { dev: true, projectPath: "/path/to/project", env: "default" }
```

| Field         | Description                                                    |
| ------------- | -------------------------------------------------------------- |
| `dev`         | `true` when running under `ajs project dev`, `false` otherwise |
| `projectPath` | Absolute path to the root of the running project               |
| `env`         | Name of the active configuration environment                   |

## `RegisterDevServer`

Registers a development server and the endpoints it is listening on. Modules that bind network ports (such as an HTTP API) call this after a successful `listen()` so external tooling can discover the actual endpoints.

```ts
await RegisterDevServer("api", [
  { protocol: "http", host: "localhost", port: 5011 },
]);
```

In development mode, the core merges the registration into the dev registry file and removes the file on shutdown. Outside development mode, the call is a no-op.

## Dev registry file

The dev registry file lives at `DEV_REGISTRY_PATH` (`.antelope/dev.json`) relative to the project root. Its shape is described by the `DevServerRegistry` type:

```json
{
  "pid": 12345,
  "startedAt": "2026-06-12T10:00:00Z",
  "servers": {
    "api": {
      "endpoints": [{ "protocol": "http", "host": "localhost", "port": 5011 }]
    }
  }
}
```

The file is only valid while the process identified by `pid` exists. If that process is gone, the file is orphaned and must be ignored or overwritten.