Core

Read Xray core stats, inspect and update the JSON config, and restart the engine through `sdk.core` — fully typed against the Marzban API.

sdk.core provides control over the underlying Xray core — read stats, inspect or update the JSON config, and restart the engine.

Types

`CoreStats`

Returned by getCoreStats.

import type { CoreStats } from 'marzban-sdk'

Field	Type	Description
`version`	`string`	Xray core version, e.g. `"1.8.4"`
`started`	`boolean`	`true` when the Xray process is running
`logs_websocket`	`string`	WebSocket endpoint path for core log streaming

Methods

`getCoreStats()`

Get runtime statistics for the Xray core process.

Returns

const stats = await sdk.core.getCoreStats()

console.log(stats.version)         // "1.8.4"
console.log(stats.started)         // true
console.log(stats.logs_websocket)  // "/api/core/logs"

`getCoreConfig()`

Retrieve the full current Xray JSON configuration — the raw Xray config tree, passed through untyped.

Returns

const config = await sdk.core.getCoreConfig()
// Returns a raw JSON object — the full Xray config tree
console.log(JSON.stringify(config, null, 2))

`modifyCoreConfig(data)`

Replace the Xray configuration with a new (the full Xray config tree). Triggers a core restart.

Returns — the applied config

const config = await sdk.core.getCoreConfig()

await sdk.core.modifyCoreConfig({
  ...config,
  log: {
    ...config.log,
    loglevel: 'warning',
  },
})

Modifying the core config restarts the Xray process and briefly disconnects all users. Test changes in a staging environment first.

`restartCore()`

Restart the Xray core without changing its configuration.

Returns

await sdk.core.restartCore()

Common patterns

Check if the core is running

const stats = await sdk.core.getCoreStats()

if (!stats.started) {
  console.error('Xray core is not running — restarting...')
  await sdk.core.restartCore()
}

Update log level only

const config = await sdk.core.getCoreConfig()

await sdk.core.modifyCoreConfig({
  ...config,
  log: { ...config.log, loglevel: 'debug' },
})

console.log('Core restarted with debug logging')

On this page