---
title: NameRegistry
description: "The CLI's name registry: one owner-only JSON file per name under <stateDir>/names/."
---

The CLI's name registry: one owner-only JSON file per name under `<stateDir>/names/`.

`stateDir` defaults to the CLI's — `$MICROVM_STATE_DIR`, else `~/.microvm/runs` — so a
name registered here resolves in `microvm exec --name` and the reverse.

## Constructors

### Constructor

```ts
new NameRegistry(stateDir?: string | null): NameRegistry;
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `stateDir?` | `string` | `null` |

#### Returns

`NameRegistry`

## Accessors

### directory

#### Get Signature

```ts
get directory(): string;
```

The directory holding the name files.

##### Returns

`string`

## Methods

### delete()

```ts
delete(name: string): boolean;
```

Removes `name`, answering whether a record was there.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |

#### Returns

`boolean`

***

### get()

```ts
get(name: string): NameRecord | null;
```

The record registered as `name`, or `null`. A file that exists but does not parse
throws rather than reading as free.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |

#### Returns

[`NameRecord`](/microvms-agentd/reference/typescript/classes/namerecord/) | `null`

***

### importRecord()

```ts
importRecord(record: NameRecord, session: Session): Promise<boolean>;
```

Registers a record this registry didn't write, once the VM has answered one
authenticated request with the record's token; resolves with whether it refreshed a
record of the same VM.

`session` must be attached with the record's endpoint and token (`Session.attach` from
its fields). A name held by another VM, or by an unreadable file, is refused before any
request, and a probe the daemon refuses writes nothing. Core's `names::import`, the rule
`microvm attach` applies.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `record` | [`NameRecord`](/microvms-agentd/reference/typescript/classes/namerecord/) |
| `session` | [`Session`](/microvms-agentd/reference/typescript/classes/session/) |

#### Returns

`Promise`\<`boolean`>

***

### list()

```ts
list(): NameRecord[];
```

Every readable record, sorted by name.

#### Returns

[`NameRecord`](/microvms-agentd/reference/typescript/classes/namerecord/)\[]

***

### put()

```ts
put(record: NameRecord): void;
```

Writes `record` under its name, replacing any earlier record, owner-only on Unix.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `record` | [`NameRecord`](/microvms-agentd/reference/typescript/classes/namerecord/) |

#### Returns

`void`

***

### register()

```ts
register(name: string, sandbox: Sandbox): Promise<NameRecord>;
```

Names the VM `sandbox` addresses and writes the record; resolves with it.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |
| `sandbox` | [`Sandbox`](/microvms-agentd/reference/typescript/classes/sandbox/) |

#### Returns

`Promise`\<[`NameRecord`](/microvms-agentd/reference/typescript/classes/namerecord/)>

***

### releaseByVm()

```ts
releaseByVm(microvmId: string): string[];
```

Removes every name registered to `microvmId` and returns them — the step after a
terminate, so no name outlives its VM.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `microvmId` | `string` |

#### Returns

`string`\[]

## Provenance

This page is generated from `bindings/microvms-js/index.d.ts` by TypeDoc 0.28.20 and typedoc-plugin-markdown 4.13.1, run from `site/scripts/gen-reference.mjs` on every `pnpm run sync`, so an edit made here is overwritten by the next run.

To change the page, change the doc comment in the binding's Rust source, then regenerate the declarations with `mise run dts`. `mise run dts:check` fails when the committed file no longer matches the source.