soulfire.instance_connect.InstanceServiceClient¶
- class soulfire.instance_connect.InstanceServiceClient(address: str, *, codec: connectrpc.codec.Codec | None = _PROTO_BINARY_CODEC, protocol: connectrpc.protocol.ProtocolType = ProtocolType.CONNECT, accept_compression: collections.abc.Iterable[connectrpc.compression.Compression] | None = None, send_compression: connectrpc.compression.Compression | None = _GZIP_COMPRESSION, timeout_ms: int | None = None, read_max_bytes: int | None = None, interceptors: collections.abc.Iterable[connectrpc.interceptor.Interceptor] = (), http_client: pyqwest.Client | None = None)[source]¶
Bases:
connectrpc.client.ConnectClientService 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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, *, headers: connectrpc.request.Headers | collections.abc.Mapping[str, str] | None = None, timeout_ms: int | None = None) 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