---
title: "Configure an Instance from a Generic node"
description: "Bind a Generic node's port to a real type in the console wizard or with axiom instance create — author nested message-typed fields, toggle repeated/optional, and preview a mapping's exact output before you save."
category: guide
surfaces: [console, cli, http-api]
related: [concepts/nodes-packages-flows, reference/axiom-yaml, reference/cli/axiom-instance-create, reference/cli/axiom-instance-preview, reference/http-api, reference/glossary]
last_reviewed: 2026-07-11
---

# Configure an Instance from a Generic node

An [Instance](../reference/glossary.md#instance) binds a
[Generic node](../reference/glossary.md#generic-node)'s port(s) to a real,
specific message type. The shortest path — one flat, scalar-only message per
port — is covered in [`axiom instance create`](../reference/cli/axiom-instance-create.md)
and the marketplace's Generic Nodes tab. This guide covers the richer
authoring model both surfaces also support: a field whose type is itself
another message, defined inline and recursively; `repeated`/`optional`
field modifiers; and previewing a mapping's exact output before you commit
to a shape.

**Nothing you author while configuring an Instance becomes a real, queryable
registry message until you save (console) or run `axiom instance create`
(CLI) for the whole Instance.** Closing the wizard, hitting Cancel at any
nesting level, or a failed create leaves nothing behind — every nested
message you draft is synthesized transactionally, in the same request that
creates the Instance, never as a separate call per message.

## Prerequisites

- You are logged in to the Axiom app, and the CLI has run `axiom login`
  ([Installation](../getting-started/installation.md)).
- A published **Generic node** exists to instantiate — a package with
  `kind: generic` and at least one `generic_ports` entry (see
  [Generic and Instance nodes](../reference/axiom-yaml.md#generic-and-instance-nodes)).
  Browse one via the marketplace's **Generic Nodes** tab.

## Configure an Instance in the console

Open the wizard from the marketplace's Generic Nodes tab (**Create
Instance** on a node's detail page) or by navigating to `/instances/new`.
Each generic port (output, input, or both) gets its own column with two
steps: **Select message**, then **Map fields**.

### Author a message with nested fields

In Step 1, **Create new message** opens a form: a message name, then a list
of fields. Each field has a name and a type — either a scalar (`string`,
`int32`, `int64`, `uint32`, `uint64`, `double`, `float`, `bool`, `bytes`) or
`message`, a reference to another message.

Picking `message` opens a picker with its own **Create new message**
button — authoring a nested message reuses the exact same form, recursively.
There is no fixed depth limit in the UI; author as many levels as the shape
actually needs (the server enforces a generous cap — see
[Limits on a drafted message tree](#limits-on-a-drafted-message-tree)
below). Today, a nested field's `message` type can only be an inline,
freshly authored message — picking an already-published message as a nested
field's type is not yet supported end to end (it would carry no field
definitions of its own, and the request is rejected). Author the nested
shape inline instead.

Each field also has independent **repeated** and **optional** toggles.
They're mutually exclusive — proto3 forbids `repeated optional` — so
turning one on clears the other.

A **Proto preview** toggle on the form shows the exact `.proto` text your
current name/fields/modifiers produce, live, recomputed on every keystroke —
useful for confirming a nested shape's rendered syntax before committing.

### Map fields and preview the mapping

Step 2 renders the same field-mapping panel used for ordinary flow edges, so
target fields bind to source values by name, CEL expression, or literal.
Its collapsible **Preview** section runs your mapping against sample JSON
you type per source, showing the *exact* value it currently produces or the
mapping error blocking it — the same engine the registry and worker use at
real compile/dispatch time, not an approximation. This works identically
whether every message involved is already real or one is a message you just
authored in Step 1: an as-yet-undrafted message is sent to the preview
endpoint as an inline definition instead of a registry name, so you can
iterate on a brand-new nested shape and see real output before anything is
saved.

### Name and save

Once every declared generic port shows **resolved**, name the Instance
(`your-handle/instance-name`) and click **Save instance**. The whole
draft tree — the top-level facade for each port plus every nested message,
however deep — is synthesized in one transaction; a validation failure at
any level leaves nothing behind.

## Configure an Instance with the CLI

`axiom instance create` supports the same two authoring shapes as the
console, chosen per port.

### Flat fields (the common case)

`--output-field`/`--input-field name=kind` (repeatable) covers a flat,
scalar-only message — see
[`axiom instance create`](../reference/cli/axiom-instance-create.md) for the
full flag reference. This shape is unchanged and always available.

### Nested fields with a fields-file

For repeated/optional modifiers, or a field whose type is another message
(recursively), pass `--output-fields-file`/`--input-fields-file` instead: a
path to a JSON file shaped `{"message_name": "...", "fields": {...}}`. Each
value in `fields` is either:

- a bare scalar-kind string (`"total": "double"`) — identical to the flat
  shape, and
- a JSON object for anything richer: `{"kind": "<scalar>", "repeated":
  true}`, `{"kind": "<scalar>", "optional": true}`, or `{"kind": "message",
  "message": {"message_name": "...", "fields": {...}}}` for a nested,
  not-yet-real message.

`--output-fields-file` is mutually exclusive with `--output-message`/
`--output-field` on the same port — pick one shape of input per port.
`--input-fields-file` is likewise exclusive with `--input-message`/
`--input-field`. The two ports are independent: the output port can use a
fields-file while the input port uses flat flags, or vice versa.

A worked example — an `OrderSummary` output facade with a top-level
`repeated` field and a nested `Customer` message:

```json
{
  "message_name": "OrderSummary",
  "fields": {
    "id": "int64",
    "tags": { "kind": "string", "repeated": true },
    "customer": {
      "kind": "message",
      "message": {
        "message_name": "Customer",
        "fields": {
          "name": "string",
          "age": { "kind": "int32", "optional": true }
        }
      }
    }
  }
}
```

Save that as `order-summary.fields.json` and pass it in:

```bash
axiom instance create acme/orders-query \
  --generic-package acme/postgres-query --generic-node "Postgres Query" \
  --output-fields-file ./order-summary.fields.json
```

`OrderSummary` and `Customer` are both synthesized in the same request that
creates `acme/orders-query` — neither exists as a registry row if the
request fails validation at any level.

### Preview a mapping before you create

`axiom instance preview` wraps `POST /adapters/preview` verbatim — the same
engine the registry compiler and worker use at real dispatch time, run
against sample JSON you supply, with no live invoke. It reads a request body
from `--request-file` (or stdin):

```json
{
  "dst_msg_name": "OrderSummary",
  "sources": [
    {"edge_id": "e1", "msg_name": "Order", "sample": {"id": 1, "amount": 42.5}}
  ],
  "adapter": {"total": "$.amount"}
}
```

Exactly one of `adapter` (a single-edge mapping) or `compose_mapping` (a
multi-source compose consumer) is required. Any `msg_name` slot —
`dst_msg_name`, or a `sources[]` entry — accepts a bare registry message name
(a JSON string, as above) **or** an inline draft in place of it: the
identical `{"message_name": ..., "fields": {...}}` shape the fields-file
above uses, letting you preview a mapping against a message you haven't
created yet:

```json
{
  "dst_msg_name": {"message_name": "OrderSummary", "fields": {"total": "double"}},
  "sources": [{"edge_id": "e1", "msg_name": "Order", "sample": {"amount": 42.5}}],
  "adapter": {"total": "$.amount"}
}
```

```bash
axiom instance preview --request-file ./preview-request.json
```

A mapping-level failure (bad expression, type mismatch, unresolvable field)
prints as an error and exits non-zero — it's a property of the mapping
you're iterating on, not a malformed request. Once the output looks right,
reuse the exact same message shape as the fields-file input to
`axiom instance create`. See
[`axiom instance preview`](../reference/cli/axiom-instance-preview.md) for
the full flag reference.

## Limits on a drafted message tree

Both surfaces synthesize (console Save) or accept (CLI preview/create) a
draft tree under the same bounds, so a request fails fast with a clear error
instead of an unbounded compile:

| Limit | Bound |
|---|---|
| Nesting depth (top-level message counts as depth 1) | 10 |
| Distinct messages in one tree (both ports combined) | 100 |
| Fields on any one message | 200 |
| Request body size | 1 MiB |

A name reused for two different shapes within one request is rejected as a
collision; drafting the identical name and shape twice (for example, the
same nested message referenced from both the output and input port) is a
harmless dedup, not an error.