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

```python
@final
class NameRegistry
```

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

`state_dir` defaults to the CLI's — `$MICROVM_STATE_DIR`, else `~/.microvm/runs` — so a
name registered here resolves in `microvm exec --name` and the reverse. To keep names in
your own database instead, store `NameRecord.to_dict()` there and adopt with
`Sandbox.adopt` from the record's fields.

## Constructor

```python
NameRegistry(state_dir: str | PathLike[str] | None = None)
```

## Properties

### `directory`

```python
directory: str
```

The directory holding the name files.

## Methods

### `delete`

```python
def delete(name: str) -> bool
```

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

### `get`

```python
def get(name: str) -> NameRecord | None
```

The record registered as `name`, or `None`. A file that exists but does not parse
raises rather than reading as free: its name stays taken until someone inspects it.

### `import_record`

```python
def import_record(record: NameRecord, session: Session) -> bool
```

Registers a record this registry didn't write, once the VM has answered one
authenticated request with the record's token; returns 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.

### `import_record_async`

```python
def import_record_async(record: NameRecord, session: Session) -> bool
```

The awaitable twin of `import_record`.

### `list`

```python
def list() -> list[NameRecord]
```

Every readable record, sorted by name.

### `put`

```python
def put(record: NameRecord) -> None
```

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

### `register`

```python
def register(name: str, sandbox: Sandbox) -> NameRecord
```

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

### `release_by_vm`

```python
def release_by_vm(microvm_id: str) -> list[str]
```

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

## Special methods

### `__repr__`

```python
def __repr__() -> str
```

## Provenance

This page is generated from `bindings/microvms-py/microvms.pyi` by Griffe 2.3.0, 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 stubs`. `mise run stubs:check` fails when the committed file no longer matches the source.