A Go SDK on top of any-sync, built around a CRDT data plane: Mongo-style record stores per object, per-field version gating, and an apply pipeline that converges across peers.
go get github.com/anyproto/any-sync-sdk
Requires Go 1.26+.
Everything outside these import paths lives under internal/ and is not importable.
| Path | What it owns |
|---|---|
github.com/anyproto/any-sync-sdk |
Open, Close, the SDK handle (Spaces, Account, Identities, Push, PubSub, P2PStatus, CRDTVersion) |
.../auth |
Provider interface, the file-backed wallet (FileProvider), mnemonic helpers |
.../config |
Config: storage layout, network YAML, sync and p2p tunables, registered types, collections and modules |
.../space |
the caller surface: Service, Space, ObjectService, TypesAPI, CollectionsAPI, PropertiesAPI, Query, ModifyBatch, ACL, MembersAPI, SyncStatusAPI, HistoryAPI, Files, … |
.../handler |
declarations for custom datasets, types, collections and modules |
.../p2p |
local-network discovery driver injection, power hint, p2p status types |
import (
anysyncsdk "github.com/anyproto/any-sync-sdk"
"github.com/anyproto/any-sync-sdk/auth"
"github.com/anyproto/any-sync-sdk/config"
"github.com/anyproto/any-sync-sdk/space"
)
provider, _ := auth.NewFileProvider(auth.FileProviderConfig{
Path: "/path/to/wallet.key",
})
cfg := config.Config{
Storage: config.Storage{DataDir: "/var/data"},
Network: config.Network{NodeConfYAML: nodeConfBytes},
}
sdk, err := anysyncsdk.Open(ctx, cfg, provider)
if err != nil { return err }
defer sdk.Close()
sp, _ := sdk.Spaces().Create(ctx, space.CreateRequest{Name: "My Notes"})
typeId, _ := sp.Types().Create(ctx, space.TypeCreateParams{Name: "Movie"})
titleId, _ := sp.Types().AddProperty(ctx, typeId, space.PropertyDraft{
Name: "Title", Kind: space.PropertyKindString,
})
objId, _ := sp.Objects().Create(ctx, space.CreateObjectOpts{
Type: typeId,
InitialProperties: map[string]map[string]any{
typeId: {titleId: "Casablanca"},
},
})
docs, _ := sp.QueryObjects().
Filter(map[string]any{"any.type": typeId}).
All(ctx)examples/basic/main.go walks through more: property scopes, subscriptions, writes to a type-owned dataset.
Two any-store databases under Config.Storage.DataDir:
<DataDir>/anysync/<spaceId>.db any-sync per-space tree storage (any-store v1)
<DataDir>/sdk.db SDK CRDT collections (any-store v2, shared)
any-sync stays on any-store v1 internally; the SDK uses v2 through the /v2 import path. Separate files keep the two versions from sharing schema or state.
Built-in definitions: any (universal properties: id, author, spaceId, createdAt, modifiedAt, modifiedBy, name, description, …), type (the meta-type that defines other types) and collection.
Callers extend the catalog at Open by registering handler.Type entries. A type declares property definitions, datasets with their handlers, and parts:
import "github.com/anyproto/any-sync-sdk/handler"
cfg.Types = []handler.Type{
{
Id: "movie",
Name: "Movie",
Datasets: []handler.Dataset{{
Name: "scenes",
DataVersion: "scenes-v1",
Handler: &sceneHandler{},
}},
},
}config.Config.Collections registers collections and config.Config.Modules registers dataset modules (docs/user-datasets.md). Registered types appear in Space.Types().List() next to user-created types. The dataset names objects, properties and shortIds are reserved.
Implemented:
- CRDT apply (
$set/$unset/$inc/$incGated/$addToSet/$pull, sticky tombstones, per-field_vergating); per-op rejections surface asModifyResult.Rejections; one batch can create, update and delete (OpDelete) and can be conditional on the dataset being unchanged since an_applySeq(ModifyBatch.IfUnchangedSince) - Local writes and inbound sync replay through one apply path; cold restore, watermarked replay, parked changes drained once their schema arrives
- Derived fields stamped from the tree:
id,author,createdAt,spaceIdfrom the immutable header;modifiedAt/modifiedByfrom the object's latest synced change on any dataset - Types (one per object), collections, property definitions with scopes, runtime datasets and parts, bundles
- Writes:
Modify,ModifyMany,Delete,Upsert - Queries: per-object
Space.Queryand per-spaceSpace.QueryObjectswithFilter/Sort/Limit/Offset/Projectionand terminalsIter/All/One/Count/Snapshot/Subscribe; aggregation pipelines (Aggregate,AggregateObjects) - Live windowed subscriptions:
Query.Subscribe(ctx, opts)returns*QueryResult{Initial, Total, Sub}.Sub.Events()carriesSubscriptionEvent{VersionId, Added, Updated, Removed}with the full post-apply doc and projected$set/$unsetops per record. A window re-reads storage when rows leave it, so it stays equal to a fresh query of the same body. Overflow closes withErrSubscriptionOverflow; a window the engine cannot keep equal to storage closes withErrSubscriptionDrifted; resubscribe to recover - Change index for consumer-side indexers:
Space.Changes() - Version history:
Space.History()(ListChanges,ViewAt,RecordAt,Diff) - Read tracking:
Space.ReadState() - Files:
Space.Files()(Attach,Open,Status,Pin,Offload, …) andSpace.Payloads(); file cache management onSDK - Sync status:
Space.SyncStatus()(Space,Object,SubscribeObject);Service.Status/SubscribeStatus - Tech space (per-account derived index of all spaces); spaces stay resident and are eager-loaded on boot;
Service.Subscribefor space-list events - Space lifecycle:
Create/Join/JoinGuest/Derive/OneToOne/Get/List/Track/Evict/Delete; direct-add and 1-1 accept/decline - Collaboration:
ACL(CreateInvite/RevokeInvite/RevokeAllInvites/AcceptRequest/DeclineRequest/ChangePermissions/AddAccounts/RemoveAccounts/OwnershipChange/RequestSelfRemove/CancelJoinRequest/StopSharing/CreateGuestKey);Members(List/Get/Me/JoinRequests/Invites/Subscribe/Query) - Account:
Account.Metadata/UpdateMetadata, persisted in the tech space and republished to identityRepo on boot;Account.Limits— the network's file-storage pool and shared-spaces limit, served from the device's last answer while offline;SDK.Identities()directory; devices - Push notifications (
SDK.Push()) and pub/sub (SDK.PubSub(),Space.PubSub()) - Direct sync with LAN peers (mDNS) and global peers (iroh, account-level discovery)
- CRDT version mark: an SDK refuses an account written by a newer data model
See docs/:
common-context.md: the layer model and design principlesauth-module.md: wallet / provider contracttech-space.md: derived per-account indexspace.md: space lifecycle, ACL surface, syncobject.md: object lifecyclecrdt.md,crdt-spec.md: apply algorithm and invariantsdata-structure.md: record shape, types, collections, propertiesfiles.md: files and payloadsversioning.md: handler versions, re-indexing, the CRDT version marksync-status-proposal.md: per-space and per-object sync statuschange-index-proposal.md: change feed for consumer-side indexersone-to-one-spaces.md: derived 1-1 spaces and inbox discoveryidentities.md: account-global identity directorydirect-add-invites.md: adding accounts to a space by identityuser-datasets.md: parts, modules, runtime dataset schemas, batch upsertglobal-p2p.md: internet-wide device-to-device syncaccount-discovery.md: finding the account's own devicesbundles.md: per-space registry of installed bundlesread-tracking-proposal.md: read/unread statescoped-properties-proposal.md: property and field scopesspace-index-proposal.md: the per-spacespaceIndexobjecttypes-properties-proposal.md: schema versioning, DataVersion gating, parked changesversion-history-proposal.md: version history
The on-the-wire header.SpaceType is constrained to the any-sync-coordinator's allow-list: the any product's any.space / any.techspace / any.onetoone (fileproto v2 required) plus anytype's anytype.space, anytype.techspace, anytype.chatspace, anytype.onetoone. The SDK mints only the any.* family; it can join anytype.* spaces but never creates them. See docs/space.md § Space type strings.
Released under the MIT License.