soulfire.instance_connect.InstanceService

class soulfire.instance_connect.InstanceService[source]

Bases: Protocol

Service for managing SoulFire instances. An instance is a permission and configuration compartment for independently controlled Minecraft bots, settings, accounts, proxies, and remote clients.

All operations require appropriate permissions: - CREATE_INSTANCE (global): Required to create new instances - READ_INSTANCE: Required to list and view instance details - UPDATE_INSTANCE_META: Required to change instance name/icon - UPDATE_INSTANCE_CONFIG: Required to modify settings, accounts, and proxies - DELETE_INSTANCE: Required to delete an instance - READ_INSTANCE_AUDIT_LOGS: Required to view audit logs - READ_BOT_INFO: Required to read account metadata

async get_or_create_instance(request: soulfire.instance_pb2.InstanceGetOrCreateRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceGetOrCreateRequest, soulfire.instance_pb2.InstanceGetOrCreateResponse], /) → soulfire.instance_pb2.InstanceGetOrCreateResponse[source]

Gets or creates an instance owned by the caller without a list/create race.

async get_or_create_bot(request: soulfire.instance_pb2.InstanceGetOrCreateBotRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceGetOrCreateBotRequest, soulfire.instance_pb2.InstanceGetOrCreateBotResponse], /) → soulfire.instance_pb2.InstanceGetOrCreateBotResponse[source]

Gets or creates a named bot account. Does not change its desired state.

async create_instance(request: soulfire.instance_pb2.InstanceCreateRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceCreateRequest, soulfire.instance_pb2.InstanceCreateResponse], /) → soulfire.instance_pb2.InstanceCreateResponse[source]

Creates a new instance with the given friendly name. Requires: CREATE_INSTANCE global permission Returns: The UUID of the newly created instance Errors: INTERNAL if creation fails

async duplicate_instance(request: soulfire.instance_pb2.InstanceDuplicateRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceDuplicateRequest, soulfire.instance_pb2.InstanceDuplicateResponse], /) → soulfire.instance_pb2.InstanceDuplicateResponse[source]

Copies the source configuration and icon into a new instance in one write. Includes accounts, proxies, and persistent metadata. Bots start stopped. Does not copy permissions, files, scripts, audit logs, or runtime state. Requires: CREATE_INSTANCE globally and READ_INSTANCE on the source. Errors: INVALID_ARGUMENT for invalid input, NOT_FOUND for a missing source.

async delete_instance(request: soulfire.instance_pb2.InstanceDeleteRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceDeleteRequest, soulfire.instance_pb2.InstanceDeleteResponse], /) → soulfire.instance_pb2.InstanceDeleteResponse[source]

Permanently deletes an instance and all its data. Connected bots are stopped before the instance is deleted. This operation cannot be undone. Requires: DELETE_INSTANCE permission on the instance Errors: NOT_FOUND if instance does not exist

async list_instances(request: soulfire.instance_pb2.InstanceListRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceListRequest, soulfire.instance_pb2.InstanceListResponse], /) → soulfire.instance_pb2.InstanceListResponse[source]

Lists all instances the current user has permission to view. Only instances where the user has READ_INSTANCE permission are returned. Returns summary information for each instance.

async get_instance_info(request: soulfire.instance_pb2.InstanceInfoRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceInfoRequest, soulfire.instance_pb2.InstanceInfoResponse], /) → soulfire.instance_pb2.InstanceInfoResponse[source]

Gets detailed information about a specific instance. Supports conditional requests via if_modified_since to reduce bandwidth. Requires: READ_INSTANCE permission on the instance Returns: Full instance info or not_modified status Errors: NOT_FOUND if instance does not exist

async update_instance_meta(request: soulfire.instance_pb2.InstanceUpdateMetaRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceUpdateMetaRequest, soulfire.instance_pb2.InstanceUpdateMetaResponse], /) → soulfire.instance_pb2.InstanceUpdateMetaResponse[source]

Updates instance metadata (friendly name or icon). Only one field can be updated per request. Requires: UPDATE_INSTANCE_META permission on the instance Errors: NOT_FOUND if instance does not exist

async update_instance_config(request: soulfire.instance_pb2.InstanceUpdateConfigRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceUpdateConfigRequest, soulfire.instance_pb2.InstanceUpdateConfigResponse], /) → soulfire.instance_pb2.InstanceUpdateConfigResponse[source]

Replaces the entire instance configuration. Used primarily for profile import operations. For individual setting changes, use UpdateInstanceConfigEntry instead. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist

async update_instance_config_entry(request: soulfire.instance_pb2.InstanceUpdateConfigEntryRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceUpdateConfigEntryRequest, soulfire.instance_pb2.InstanceUpdateConfigEntryResponse], /) → soulfire.instance_pb2.InstanceUpdateConfigEntryResponse[source]

Updates a single configuration entry by namespace and key. More efficient than UpdateInstanceConfig for individual changes. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist

async add_instance_account(request: soulfire.instance_pb2.InstanceAddAccountRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceAddAccountRequest, soulfire.instance_pb2.InstanceAddAccountResponse], /) → soulfire.instance_pb2.InstanceAddAccountResponse[source]

Adds a Minecraft account to the instance. The account’s profile_id must be unique within the instance. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist

async remove_instance_account(request: soulfire.instance_pb2.InstanceRemoveAccountRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceRemoveAccountRequest, soulfire.instance_pb2.InstanceRemoveAccountResponse], /) → soulfire.instance_pb2.InstanceRemoveAccountResponse[source]

Removes a Minecraft account from the instance by profile_id. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist

async update_instance_account(request: soulfire.instance_pb2.InstanceUpdateAccountRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceUpdateAccountRequest, soulfire.instance_pb2.InstanceUpdateAccountResponse], /) → soulfire.instance_pb2.InstanceUpdateAccountResponse[source]

Updates an existing Minecraft account in the instance. The account is matched by profile_id and replaced. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist

async add_instance_accounts_batch(request: soulfire.instance_pb2.InstanceAddAccountsBatchRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceAddAccountsBatchRequest, soulfire.instance_pb2.InstanceAddAccountsBatchResponse], /) → soulfire.instance_pb2.InstanceAddAccountsBatchResponse[source]

Adds multiple Minecraft accounts to the instance in a single operation. More efficient than multiple AddInstanceAccount calls. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist

async replace_instance_accounts(request: soulfire.instance_pb2.InstanceReplaceAccountsRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceReplaceAccountsRequest, soulfire.instance_pb2.InstanceReplaceAccountsResponse], /) → soulfire.instance_pb2.InstanceReplaceAccountsResponse[source]

Atomically replaces the account list and stops bots whose accounts were removed. Other instance configuration remains unchanged. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if the instance does not exist; INVALID_ARGUMENT for invalid accounts

async remove_instance_accounts_batch(request: soulfire.instance_pb2.InstanceRemoveAccountsBatchRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceRemoveAccountsBatchRequest, soulfire.instance_pb2.InstanceRemoveAccountsBatchResponse], /) → soulfire.instance_pb2.InstanceRemoveAccountsBatchResponse[source]

Removes multiple Minecraft accounts from the instance by their profile_ids. More efficient than multiple RemoveInstanceAccount calls. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist

async add_instance_proxy(request: soulfire.instance_pb2.InstanceAddProxyRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceAddProxyRequest, soulfire.instance_pb2.InstanceAddProxyResponse], /) → soulfire.instance_pb2.InstanceAddProxyResponse[source]

Adds a proxy to the instance. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist

async remove_instance_proxy(request: soulfire.instance_pb2.InstanceRemoveProxyRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceRemoveProxyRequest, soulfire.instance_pb2.InstanceRemoveProxyResponse], /) → soulfire.instance_pb2.InstanceRemoveProxyResponse[source]

Removes a proxy from the instance by its index. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist Errors: INVALID_ARGUMENT if index is out of bounds

async update_instance_proxy(request: soulfire.instance_pb2.InstanceUpdateProxyRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceUpdateProxyRequest, soulfire.instance_pb2.InstanceUpdateProxyResponse], /) → soulfire.instance_pb2.InstanceUpdateProxyResponse[source]

Updates an existing proxy in the instance by its index. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist Errors: INVALID_ARGUMENT if index is out of bounds

async add_instance_proxies_batch(request: soulfire.instance_pb2.InstanceAddProxiesBatchRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceAddProxiesBatchRequest, soulfire.instance_pb2.InstanceAddProxiesBatchResponse], /) → soulfire.instance_pb2.InstanceAddProxiesBatchResponse[source]

Adds multiple proxies to the instance in a single operation. More efficient than multiple AddInstanceProxy calls. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist

async remove_instance_proxies_batch(request: soulfire.instance_pb2.InstanceRemoveProxiesBatchRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceRemoveProxiesBatchRequest, soulfire.instance_pb2.InstanceRemoveProxiesBatchResponse], /) → soulfire.instance_pb2.InstanceRemoveProxiesBatchResponse[source]

Removes multiple proxies from the instance by their addresses. More efficient than multiple RemoveInstanceProxy calls. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist

async remove_instance_proxy_entries(request: soulfire.instance_pb2.InstanceRemoveProxyEntriesRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceRemoveProxyEntriesRequest, soulfire.instance_pb2.InstanceRemoveProxyEntriesResponse], /) → soulfire.instance_pb2.InstanceRemoveProxyEntriesResponse[source]

Removes one matching occurrence of each requested proxy entry. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if the instance does not exist; INVALID_ARGUMENT for invalid proxies

async get_audit_log(request: soulfire.instance_pb2.InstanceAuditLogRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.InstanceAuditLogRequest, soulfire.instance_pb2.InstanceAuditLogResponse], /) → soulfire.instance_pb2.InstanceAuditLogResponse[source]

Retrieves the audit log for an instance. Returns a list of recorded actions ordered by timestamp (newest first). Requires: READ_INSTANCE_AUDIT_LOGS permission on the instance Errors: NOT_FOUND if instance does not exist

async get_account_metadata(request: soulfire.instance_pb2.GetAccountMetadataRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.GetAccountMetadataRequest, soulfire.instance_pb2.GetAccountMetadataResponse], /) → soulfire.instance_pb2.GetAccountMetadataResponse[source]

Gets persistent metadata for a Minecraft account. Persistent metadata survives bot restarts and session changes. Requires: READ_BOT_INFO permission on the instance Errors: NOT_FOUND if instance or account does not exist

async set_account_metadata_entry(request: soulfire.instance_pb2.SetAccountMetadataEntryRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.SetAccountMetadataEntryRequest, soulfire.instance_pb2.SetAccountMetadataEntryResponse], /) → soulfire.instance_pb2.SetAccountMetadataEntryResponse[source]

Sets a single persistent metadata entry for a Minecraft account. Creates the namespace and key if they don’t exist, or updates if they do. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist

async delete_account_metadata_entry(request: soulfire.instance_pb2.DeleteAccountMetadataEntryRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.DeleteAccountMetadataEntryRequest, soulfire.instance_pb2.DeleteAccountMetadataEntryResponse], /) → soulfire.instance_pb2.DeleteAccountMetadataEntryResponse[source]

Deletes a persistent metadata entry from a Minecraft account. Requires: UPDATE_INSTANCE_CONFIG permission on the instance Errors: NOT_FOUND if instance does not exist

async get_instance_metadata(request: soulfire.instance_pb2.GetInstanceMetadataRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.GetInstanceMetadataRequest, soulfire.instance_pb2.GetInstanceMetadataResponse], /) → soulfire.instance_pb2.GetInstanceMetadataResponse[source]

Gets persistent metadata for the instance itself. Persistent metadata survives restarts and session changes. Requires: READ_INSTANCE permission on the instance Errors: NOT_FOUND if instance does not exist

async set_instance_metadata_entry(request: soulfire.instance_pb2.SetInstanceMetadataEntryRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.SetInstanceMetadataEntryRequest, soulfire.instance_pb2.SetInstanceMetadataEntryResponse], /) → soulfire.instance_pb2.SetInstanceMetadataEntryResponse[source]

Sets a single persistent metadata entry for the instance. Creates the namespace and key if they don’t exist, or updates if they do. Requires: UPDATE_INSTANCE_META permission on the instance Errors: NOT_FOUND if instance does not exist

async delete_instance_metadata_entry(request: soulfire.instance_pb2.DeleteInstanceMetadataEntryRequest, ctx: connectrpc.request.RequestContext[soulfire.instance_pb2.DeleteInstanceMetadataEntryRequest, soulfire.instance_pb2.DeleteInstanceMetadataEntryResponse], /) → soulfire.instance_pb2.DeleteInstanceMetadataEntryResponse[source]

Deletes a persistent metadata entry from the instance. Requires: UPDATE_INSTANCE_META permission on the instance Errors: NOT_FOUND if instance does not exist