# Cyoda Documentation

## Getting Started

- [Install cyoda-go and create your first entity](https://docs.cyoda.net/markdown/getting-started/install-and-first-entity.md): Install cyoda-go with SQLite (the default), define an entity model, trigger a workflow, and read state back.

## Concepts

- [APIs and surfaces](https://docs.cyoda.net/markdown/concepts/apis-and-surfaces.md): REST, gRPC, and Trino SQL — when and why to use each.
- [Authentication and identity](https://docs.cyoda.net/markdown/concepts/authentication-and-identity.md): OAuth 2.0 tokens, machine-to-machine credentials, on-behalf-of exchange, and external key trust — conceptually.
- [Design principles](https://docs.cyoda.net/markdown/concepts/design-principles.md): The mental model behind Cyoda: entities as durable state machines, transitions as the unit of change, and history as a first-class query surface.
- [Digital twins and the growth path](https://docs.cyoda.net/markdown/concepts/digital-twins-and-growth-path.md): Why the same Cyoda app runs on any storage tier, and when to pick each tier.
- [Entities and lifecycle](https://docs.cyoda.net/markdown/concepts/entities-and-lifecycle.md): Entities are durable state machines — schemas, states, transitions, and history.
- [What is Cyoda?](https://docs.cyoda.net/markdown/concepts/what-is-cyoda.md): An Entity Database Management System — a database engine where the first-class abstraction is a stateful entity with schema, lifecycle, history, and transactional integrity.
- [Workflows and events](https://docs.cyoda.net/markdown/concepts/workflows-and-events.md): State machines as a first-class concept — triggers, external processors, and audit trails.

## Build

- [Analytics with SQL](https://docs.cyoda.net/markdown/build/analytics-with-sql.md): Query entities with Trino SQL — when its the right surface, how to connect, and where to find the full grammar.
- [Build](https://docs.cyoda.net/markdown/build.md): Develop Cyoda applications — tier-agnostic patterns that work on any runtime.
- [Client compute nodes](https://docs.cyoda.net/markdown/build/client-compute-nodes.md): Patterns for processor and criteria services — implementation, registration, and lifecycle.
- [Modeling entities](https://docs.cyoda.net/markdown/build/modeling-entities.md): Design patterns for entity schemas — boundaries, evolution, and validation.
- [Searching entities](https://docs.cyoda.net/markdown/build/searching-entities.md): Query sets of entities over REST — direct vs async modes, predicates, pagination, and historical reads.
- [Testing with digital twins](https://docs.cyoda.net/markdown/build/testing-with-digital-twins.md): In-memory mode as a test harness; running simulations at volumes exceeding production.
- [Workflows and processors](https://docs.cyoda.net/markdown/build/workflows-and-processors.md): State-machine design, transitions, and external processors — with a preference for gRPC in compute nodes.
- [Working with entities](https://docs.cyoda.net/markdown/build/working-with-entities.md): Create, read, update, and search entities via the cyoda-go API — worked examples.

## Run

- [Cyoda Cloud](https://docs.cyoda.net/markdown/run/cyoda-cloud.md): Hosted Cyoda offering — test/demo today, commercial SLA offering planned.
- [Desktop (single binary)](https://docs.cyoda.net/markdown/run/desktop.md): Run cyoda-go from a single binary — dev, low-volume production, in-memory and SQLite modes.
- [Docker](https://docs.cyoda.net/markdown/run/docker.md): Run cyoda-go in Docker for bespoke integrations and local compositions.
- [Identity and entitlements (Cyoda Cloud)](https://docs.cyoda.net/markdown/run/cyoda-cloud/identity-and-entitlements.md): Configure OIDC, manage signing keys, and assign entitlements on the hosted platform.
- [Kubernetes](https://docs.cyoda.net/markdown/run/kubernetes.md): Deploy cyoda-go with the Helm chart for clustered PostgreSQL-backed production.
- [Provisioning (Cyoda Cloud)](https://docs.cyoda.net/markdown/run/cyoda-cloud/provisioning.md): Provision a Cyoda Cloud environment.
- [Run](https://docs.cyoda.net/markdown/run.md): The cyoda-go packaging ladder — desktop, docker, kubernetes, and hosted Cyoda Cloud.
- [Status and roadmap (Cyoda Cloud)](https://docs.cyoda.net/markdown/run/cyoda-cloud/status-and-roadmap.md): Current status, known limitations, and upcoming work for the hosted Cyoda Cloud platform.

## Reference

- [`cyoda help` — topic tree](https://docs.cyoda.net/markdown/reference/cyoda-help.md): Every flag, env var, endpoint, error, metric, and operation — browsable from the binary. This page is a navigator over the full topic tree.
- [API reference](https://docs.cyoda.net/markdown/reference/api.md): REST and gRPC surfaces.
- [BaseEvent](https://docs.cyoda.net/markdown/reference/schemas/common/base-event.md): Schema definition for BaseEvent
- [CalculationMemberGreetEvent](https://docs.cyoda.net/markdown/reference/schemas/processing/calculation-member-greet-event.md): Schema definition for CalculationMemberGreetEvent
- [CalculationMemberJoinEvent](https://docs.cyoda.net/markdown/reference/schemas/processing/calculation-member-join-event.md): Schema definition for CalculationMemberJoinEvent
- [CalculationMemberKeepAliveEvent](https://docs.cyoda.net/markdown/reference/schemas/processing/calculation-member-keep-alive-event.md): Schema definition for CalculationMemberKeepAliveEvent
- [CLI](https://docs.cyoda.net/markdown/reference/cli.md): cyoda-go command-line interface — narrative navigator over `cyoda help cli`.
- [CloudEventType](https://docs.cyoda.net/markdown/reference/schemas/common/cloud-event-type.md): Schema definition for CloudEventType
- [Common Schemas](https://docs.cyoda.net/markdown/reference/schemas/common.md): JSON schemas in the Common category
- [Configuration](https://docs.cyoda.net/markdown/reference/configuration.md): cyoda-go configuration model — narrative navigator over `cyoda help config`.
- [DataFormat](https://docs.cyoda.net/markdown/reference/schemas/common/data-format.md): Specifies the format of the input data (e.g., JSON).
- [DataPayload](https://docs.cyoda.net/markdown/reference/schemas/common/data-payload.md): Schema definition for DataPayload
- [Entity model export (SIMPLE_VIEW)](https://docs.cyoda.net/markdown/reference/entity-model-export.md): API specification for the SIMPLE_VIEW entity-model export — response format, node descriptors, type descriptors, and error shapes.
- [Entity Schemas](https://docs.cyoda.net/markdown/reference/schemas/entity.md): JSON schemas in the Entity category
- [EntityChangeMeta](https://docs.cyoda.net/markdown/reference/schemas/common/entity-change-meta.md): Metadata about entity changes including transaction information and change type.
- [EntityChangesMetadataGetRequest](https://docs.cyoda.net/markdown/reference/schemas/search/entity-changes-metadata-get-request.md): Schema definition for EntityChangesMetadataGetRequest
- [EntityChangesMetadataResponse](https://docs.cyoda.net/markdown/reference/schemas/search/entity-changes-metadata-response.md): Schema definition for EntityChangesMetadataResponse
- [EntityCreateCollectionRequest](https://docs.cyoda.net/markdown/reference/schemas/entity/entity-create-collection-request.md): Schema definition for EntityCreateCollectionRequest
- [EntityCreatePayload](https://docs.cyoda.net/markdown/reference/schemas/entity/entity-create-payload.md): Schema definition for EntityCreatePayload
- [EntityCreateRequest](https://docs.cyoda.net/markdown/reference/schemas/entity/entity-create-request.md): Schema definition for EntityCreateRequest
- [EntityCriteriaCalculationRequest](https://docs.cyoda.net/markdown/reference/schemas/processing/entity-criteria-calculation-request.md): Schema definition for EntityCriteriaCalculationRequest
- [EntityCriteriaCalculationResponse](https://docs.cyoda.net/markdown/reference/schemas/processing/entity-criteria-calculation-response.md): Schema definition for EntityCriteriaCalculationResponse
- [EntityDeleteAllRequest](https://docs.cyoda.net/markdown/reference/schemas/entity/entity-delete-all-request.md): Schema definition for EntityDeleteAllRequest
- [EntityDeleteAllResponse](https://docs.cyoda.net/markdown/reference/schemas/entity/entity-delete-all-response.md): Schema definition for EntityDeleteAllResponse
- [EntityDeleteRequest](https://docs.cyoda.net/markdown/reference/schemas/entity/entity-delete-request.md): Schema definition for EntityDeleteRequest
- [EntityDeleteResponse](https://docs.cyoda.net/markdown/reference/schemas/entity/entity-delete-response.md): Schema definition for EntityDeleteResponse
- [EntityGetAllRequest](https://docs.cyoda.net/markdown/reference/schemas/search/entity-get-all-request.md): Schema definition for EntityGetAllRequest
- [EntityGetRequest](https://docs.cyoda.net/markdown/reference/schemas/search/entity-get-request.md): Schema definition for EntityGetRequest
- [EntityMetadata](https://docs.cyoda.net/markdown/reference/schemas/common/entity-metadata.md): Metadata about an entity. id, modelKey and creationDate are invariant against the point-in-time. All other values are with respect to the as-at point-in-time for which the entity was retrieved. If the point-in-time was not explicitly set, the values correspond to the latest state of the entity.
- [EntityModelDeleteRequest](https://docs.cyoda.net/markdown/reference/schemas/model/entity-model-delete-request.md): Schema definition for EntityModelDeleteRequest
- [EntityModelDeleteResponse](https://docs.cyoda.net/markdown/reference/schemas/model/entity-model-delete-response.md): Schema definition for EntityModelDeleteResponse
- [EntityModelExportRequest](https://docs.cyoda.net/markdown/reference/schemas/model/entity-model-export-request.md): Schema definition for EntityModelExportRequest
- [EntityModelExportResponse](https://docs.cyoda.net/markdown/reference/schemas/model/entity-model-export-response.md): Schema definition for EntityModelExportResponse
- [EntityModelGetAllRequest](https://docs.cyoda.net/markdown/reference/schemas/model/entity-model-get-all-request.md): Schema definition for EntityModelGetAllRequest
- [EntityModelGetAllResponse](https://docs.cyoda.net/markdown/reference/schemas/model/entity-model-get-all-response.md): Schema definition for EntityModelGetAllResponse
- [EntityModelImportRequest](https://docs.cyoda.net/markdown/reference/schemas/model/entity-model-import-request.md): Schema definition for EntityModelImportRequest
- [EntityModelImportResponse](https://docs.cyoda.net/markdown/reference/schemas/model/entity-model-import-response.md): Schema definition for EntityModelImportResponse
- [EntityModelTransitionRequest](https://docs.cyoda.net/markdown/reference/schemas/model/entity-model-transition-request.md): Schema definition for EntityModelTransitionRequest
- [EntityModelTransitionResponse](https://docs.cyoda.net/markdown/reference/schemas/model/entity-model-transition-response.md): Schema definition for EntityModelTransitionResponse
- [EntityProcessorCalculationRequest](https://docs.cyoda.net/markdown/reference/schemas/processing/entity-processor-calculation-request.md): Schema definition for EntityProcessorCalculationRequest
- [EntityProcessorCalculationResponse](https://docs.cyoda.net/markdown/reference/schemas/processing/entity-processor-calculation-response.md): Schema definition for EntityProcessorCalculationResponse
- [EntityResponse](https://docs.cyoda.net/markdown/reference/schemas/search/entity-response.md): Schema definition for EntityResponse
- [EntitySearchRequest](https://docs.cyoda.net/markdown/reference/schemas/search/entity-search-request.md): Schema definition for EntitySearchRequest
- [EntitySnapshotSearchRequest](https://docs.cyoda.net/markdown/reference/schemas/search/entity-snapshot-search-request.md): Schema definition for EntitySnapshotSearchRequest
- [EntitySnapshotSearchResponse](https://docs.cyoda.net/markdown/reference/schemas/search/entity-snapshot-search-response.md): Schema definition for EntitySnapshotSearchResponse
- [EntityStatsByStateGetRequest](https://docs.cyoda.net/markdown/reference/schemas/search/entity-stats-by-state-get-request.md): Schema definition for EntityStatsByStateGetRequest
- [EntityStatsByStateResponse](https://docs.cyoda.net/markdown/reference/schemas/search/entity-stats-by-state-response.md): Schema definition for EntityStatsByStateResponse
- [EntityStatsGetRequest](https://docs.cyoda.net/markdown/reference/schemas/search/entity-stats-get-request.md): Schema definition for EntityStatsGetRequest
- [EntityStatsResponse](https://docs.cyoda.net/markdown/reference/schemas/search/entity-stats-response.md): Schema definition for EntityStatsResponse
- [EntityTransactionInfo](https://docs.cyoda.net/markdown/reference/schemas/entity/entity-transaction-info.md): Schema definition for EntityTransactionInfo
- [EntityTransactionResponse](https://docs.cyoda.net/markdown/reference/schemas/entity/entity-transaction-response.md): Schema definition for EntityTransactionResponse
- [EntityTransitionRequest](https://docs.cyoda.net/markdown/reference/schemas/entity/entity-transition-request.md): Schema definition for EntityTransitionRequest
- [EntityTransitionResponse](https://docs.cyoda.net/markdown/reference/schemas/entity/entity-transition-response.md): Schema definition for EntityTransitionResponse
- [EntityUpdateCollectionRequest](https://docs.cyoda.net/markdown/reference/schemas/entity/entity-update-collection-request.md): Schema definition for EntityUpdateCollectionRequest
- [EntityUpdatePayload](https://docs.cyoda.net/markdown/reference/schemas/entity/entity-update-payload.md): Schema definition for EntityUpdatePayload
- [EntityUpdateRequest](https://docs.cyoda.net/markdown/reference/schemas/entity/entity-update-request.md): Schema definition for EntityUpdateRequest
- [ErrorCode](https://docs.cyoda.net/markdown/reference/schemas/common/error-code.md): Schema definition for ErrorCode
- [EventAckResponse](https://docs.cyoda.net/markdown/reference/schemas/processing/event-ack-response.md): Schema definition for EventAckResponse
- [Helm values](https://docs.cyoda.net/markdown/reference/helm.md): cyoda-go Helm chart — narrative navigator over `cyoda help helm`.
- [JSON Schemas](https://docs.cyoda.net/markdown/reference/schemas.md): Complete reference for all JSON schemas used in Cyoda
- [Model Schemas](https://docs.cyoda.net/markdown/reference/schemas/model.md): JSON schemas in the Model category
- [ModelConverterType](https://docs.cyoda.net/markdown/reference/schemas/common/model-converter-type.md): Defines the type of converter to use when importing the model (e.g., SAMPLE_DATA to use sample object)
- [ModelInfo](https://docs.cyoda.net/markdown/reference/schemas/common/model-info.md): Schema definition for ModelInfo
- [ModelSpec](https://docs.cyoda.net/markdown/reference/schemas/common/model-spec.md): Schema definition for ModelSpec
- [Processing Schemas](https://docs.cyoda.net/markdown/reference/schemas/processing.md): JSON schemas in the Processing category
- [ProcessorInfo](https://docs.cyoda.net/markdown/reference/schemas/common/statemachine/processor-info.md): Schema definition for ProcessorInfo
- [Reference](https://docs.cyoda.net/markdown/reference.md): Technical references — mostly generated from cyoda-go at build time.
- [Search Schemas](https://docs.cyoda.net/markdown/reference/schemas/search.md): JSON schemas in the Search category
- [SearchSnapshotStatus](https://docs.cyoda.net/markdown/reference/schemas/search/search-snapshot-status.md): Schema definition for SearchSnapshotStatus
- [SnapshotCancelRequest](https://docs.cyoda.net/markdown/reference/schemas/search/snapshot-cancel-request.md): Schema definition for SnapshotCancelRequest
- [SnapshotGetRequest](https://docs.cyoda.net/markdown/reference/schemas/search/snapshot-get-request.md): Schema definition for SnapshotGetRequest
- [SnapshotGetStatusRequest](https://docs.cyoda.net/markdown/reference/schemas/search/snapshot-get-status-request.md): Schema definition for SnapshotGetStatusRequest
- [Statemachine Schemas](https://docs.cyoda.net/markdown/reference/schemas/common/statemachine.md): JSON schemas in the Statemachine category
- [TransitionInfo](https://docs.cyoda.net/markdown/reference/schemas/common/statemachine/transition-info.md): Schema definition for TransitionInfo
- [Trino SQL surface](https://docs.cyoda.net/markdown/reference/trino.md): How entities are projected into virtual SQL tables — naming rules, type mapping, polymorphic fields, and JDBC.
- [WorkflowInfo](https://docs.cyoda.net/markdown/reference/schemas/common/statemachine/workflow-info.md): Schema definition for WorkflowInfo