Metadata and labels

Every sandbox record carries a metadata object you supply at create time. It is stored on the record and returned on reads. It is free-form: MIOSA stores it and never interprets it.

Set metadata at create

The CLI sets the same field with repeated --meta flags:

miosa create my-box --meta team=growth --meta ticket=ENG-482

Metadata or external IDs?

These are two different things, and the choice matters:

Field	Queryable?	Use it for
`metadata`	Returned on read, not a list filter	Notes, tags, and pointers you read back with the record
`external_user_id`, `external_workspace_id`, `external_project_id`	Yes: list and usage filters	Anything you need to list, group, or bill on

GET /api/v1/sandboxes filters by workspace_id, project_id, external_workspace_id, external_user_id, external_project_id, and state. It does not filter by metadata. If you need to enumerate every sandbox for one of your customers, use an external ID, not a metadata key.

Per-tenant attribution

For per-tenant products, stamp the external IDs at create and read them back on every record:

sandbox = client.sandboxes.create(
    template_id="miosa-sandbox",
    external_workspace_id="acme-corp",
    external_user_id="user-42",
    external_project_id="q3-dashboard",
    metadata={"requested_by": "jane@acme.example"},
)

Both fields are covered end to end in Multi-tenant SaaS.