Server administration

Use soulfire.admin to manage the SoulFire server. It uses the same authentication, timeouts, cancellation, and typed errors as bot automation.

Inspect server stateCopy Anchor Link

const client = yield* soulfire.admin.clientData();
const server = yield* soulfire.admin.serverInfo();
const metrics = yield* soulfire.admin.serverMetrics();

Server information includes settings, setting definitions, pages, and plugin metadata. Use a since timestamp to request only new metrics for a dashboard. Instance metrics include bot health, food, dimension, game mode, and position.

Manage settings and usersCopy Anchor Link

Granular setting updates avoid replacing unrelated configuration:

yield* soulfire.admin.setServerConfigEntry({
  namespace: "dev",
  key: "soulfire-debug",
  value: { kind: { case: "boolValue", value: true } },
});

const userId = yield* soulfire.admin.createUser({
  username: "builder",
  email: "builder@example.com",
  role: UserRole.USER,
});

from google.protobuf.struct_pb2 import Value
from soulfire.server_pb2 import ServerUpdateConfigEntryRequest
from soulfire.user_pb2 import USER_ROLE_USER, UserCreateRequest

await client.admin.set_server_config_entry(
    ServerUpdateConfigEntryRequest(
        namespace="dev",
        key="soulfire-debug",
        value=Value(bool_value=True),
    )
)

user_id = await client.admin.create_user(
    UserCreateRequest(
        username="builder",
        email="builder@example.com",
        role=USER_ROLE_USER,
    )
)

The same surface lists and reads users, updates profiles, deletes users, revokes sessions, and issues user API tokens.

Grant plugin permissionsCopy Anchor Link

Plugin permissions have a default policy, but administrators can grant or deny one permission for one user and one exact resource. A deny overrides defaults such as INSTANCE_OWNER.

import { PluginPermissionScope } from "@soulfiremc/sdk";

yield* soulfire.admin.setUserPluginPermissionGrant(userId, {
  permissionId: "plugin.skyblock.build_island",
  scope: PluginPermissionScope.INSTANCE,
  resourceId: instanceId,
  granted: true,
});

const grants =
  yield* soulfire.admin.userPluginPermissionGrants(userId);

Global permissions omit the resource ID. Instance, bot, and task permissions require the matching UUID. SoulFire keeps overrides after you remove their plugin and returns them with active: false. Reinstalling the plugin does not change these values.

Consume scoped logsCopy Anchor Link

Log scopes can target the whole server, one instance, one bot, one script, or personal messages. Historical reads return up to the server's bounded history. Subscriptions remain live until cancelled.

const scope = {
  scope: {
    case: "instance" as const,
    value: { instanceId: instance.id },
  },
};

const recent = yield* soulfire.admin.previousLogs({
  scope,
  count: 100,
});

yield* soulfire.admin.logs({ scope }).pipe(
  Stream.runForEach((entry) =>
    Effect.logInfo(entry.message?.message ?? "")
  ),
);

Execute commands and inspect audit historyCopy Anchor Link

Command execution and completion accept the protocol's explicit global, instance, or bot scope. Audit entries preserve the user, action type, timestamp, and action-specific data.

const result = yield* soulfire.admin.executeCommand({
  scope: {
    scope: {
      case: "instance",
      value: { instanceId: instance.id },
    },
  },
  command: "help",
});

const audit = yield* soulfire.admin.auditLog(instance.id);

The admin API also exposes permission-scoped server-side downloads and per-instance plugin runtime metrics.

Manage scriptsCopy Anchor Link

The complete script lifecycle is available through the same namespace:

• List, read, create, update, and delete definitions.
• Validate a graph without saving it.
• Activate and deactivate saved scripts.
• Observe execution events and script logs.
• Read runtime status.
• Dry-run a trigger with mock inputs.
• Discover node types and script registry data.

const scripts = yield* soulfire.admin.scripts(instance.id);

yield* soulfire.admin.activateScript(
  instance.id,
  { scriptId: scripts[0]!.id },
).pipe(
  Stream.runForEach((event) => Effect.logDebug(event)),
);

scripts = await client.admin.list_scripts(instance.id)

async for event in client.admin.activate_script(
    instance.id,
    scripts[0].id,
):
    print(event)

Generated service clients remain available through soulfire.service() in TypeScript and client.service() in Python. Use them when a field has no convenience method.