### Setup Frontend with npm

Source: https://github.com/lodestone-team/lodestone/wiki/Getting-Started-for-Developers

Commands to navigate to the dashboard directory, install dependencies, and start the development server for the frontend.

```bash
cd dashboard
npm i
npm run dev
```

--------------------------------

### Lodestone API Authentication and Setup

Source: https://context7.com/lodestone-team/lodestone/llms.txt

Demonstrates how to perform initial owner setup using a one-time key and how to log in to obtain a JWT bearer token for subsequent API requests. Requires the setup key from console logs for the initial setup.

```bash
# Initial owner setup (use setup key from console logs)
curl -X POST "http://localhost:16662/api/v1/setup/YOUR_SETUP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "secure_password"
  }'
# Response: {"token": "eyJ...", "user": {"uid": "...", "username": "admin", "is_owner": true, ...}}

# Login to get JWT token
curl -X POST "http://localhost:16662/api/v1/user/login" \
  -H "Authorization: Basic $(echo -n 'admin:secure_password' | base64)"
# Response: {"token": "eyJ...", "user": {...}}
```

--------------------------------

### Setup Backend with Cargo

Source: https://github.com/lodestone-team/lodestone/wiki/Getting-Started-for-Developers

Commands to navigate to the core directory and run the backend service using Cargo. This initiates the server and generates a setup key.

```bash
cd core
cargo run
```

--------------------------------

### Authentication and Setup API

Source: https://context7.com/lodestone-team/lodestone/llms.txt

Handles the initial setup of the owner account and subsequent user login for obtaining JWT tokens.

```APIDOC
## POST /api/v1/setup/:setupKey

### Description
Creates the initial owner account using a one-time setup key. This endpoint is intended for first-time setup only.

### Method
POST

### Endpoint
`/api/v1/setup/:setupKey`

### Parameters
#### Path Parameters
- **setupKey** (string) - Required - The one-time setup key displayed in console logs during initial launch.

#### Request Body
- **username** (string) - Required - The desired username for the owner account.
- **password** (string) - Required - The desired password for the owner account.

### Request Example
```json
{
  "username": "admin",
  "password": "secure_password"
}
```

### Response
#### Success Response (200)
- **token** (string) - JWT token for authentication.
- **user** (object) - User details, including uid, username, and owner status.

#### Response Example
```json
{
  "token": "eyJ...",
  "user": {
    "uid": "...",
    "username": "admin",
    "is_owner": true
  }
}
```

## POST /api/v1/user/login

### Description
Logs in a user and returns a JWT bearer token for subsequent authenticated API calls.

### Method
POST

### Endpoint
`/api/v1/user/login`

### Parameters
#### Query Parameters
- **Authorization** (string) - Required - Basic authentication header formatted as `Basic <base64_encoded_username:password>`.

### Request Example
```bash
curl -X POST "http://localhost:16662/api/v1/user/login" \
  -H "Authorization: Basic $(echo -n 'admin:secure_password' | base64)"
```

### Response
#### Success Response (200)
- **token** (string) - JWT token for authentication.
- **user** (object) - User details.

#### Response Example
```json
{
  "token": "eyJ...",
  "user": {...}
}
```
```

--------------------------------

### Start Atom Execution with start Method in TypeScript

Source: https://github.com/lodestone-team/lodestone/wiki/Intro-to-Lodestone-Atom

The `start` method is called when an Atom instance is requested to begin its operation. It logs a "start" message, updates the Atom's state to "Running", and emits a "Running" state change event. It also initiates a background loop that periodically emits console output until the Atom's state is no longer "Running".

```typescript
    public async start(caused_by: Atom.CausedBy, block: boolean): Promise<void> {
        console.log("start");
        this.event_stream.emitStateChange("Running");
        this._state = "Running";
        (async () => {
            while (this._state == "Running") {
                await new Promise(r => setTimeout(r, 1000));
                this.event_stream.emitConsoleOut("Output");
            }
        })();
        return;
    }

```

--------------------------------

### Initialize Atom with setup Method in TypeScript

Source: https://github.com/lodestone-team/lodestone/wiki/Intro-to-Lodestone-Atom

The `setup` method acts as the Atom's constructor, initializing its state and configuration. It receives user-defined `setupValue`s, Lodestone-generated `dotLodestoneConfig`, a `progression_handler` for reporting progress, and the instance `path`. The method validates input, sets up internal configuration, writes it to a file for persistence, and initiates a progress reporting loop.

```typescript
    public async setup(setupValue: Atom.SetupValue, dotLodestoneConfig: Atom.DotLodestoneConfig, progression_handler: ProgressionHandler, path: string): Promise<void> {
        this.uuid = dotLodestoneConfig.uuid;
        let port: number;
        if (setupValue.setting_sections["section_id1"].settings["setting_id1"].value?.type == "UnsignedInteger") {
            port = setupValue.setting_sections["section_id1"].settings["setting_id1"].value.value;
        } else {
            throw new Error("Invalid value type");
        }
        this.config = {
            name: setupValue.name,
            description: setupValue.description ?? "",
            port: port,
        };

        // write config to file
        await Deno.writeTextFile(path + "/" + TestInstance.restoreConfigName, JSON.stringify(this.config));

        this.event_stream = new EventStream(this.uuid, this.config.name);

        for (let i = 0; i < 100; i++) {
            progression_handler.setProgress(i, `Progress ${i}`);
            await new Promise(r => setTimeout(r, 100));
        }

        // no need to call `progression_handler.complete()` since it's handled. 
        return;
    }

```

--------------------------------

### Create Generic Lodestone Atom Server Instance

Source: https://context7.com/lodestone-team/lodestone/llms.txt

Creates a generic server instance using a provided URL for the server setup script. Requires a URL to the script and setup configuration, including name, description, and settings. Authentication is handled via JWT.

```bash
curl -X POST "http://localhost:16662/api/v1/instance/create_generic" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://raw.githubusercontent.com/Lodestone-Team/lodestone-atom-lib/main/examples/basic.ts",
    "setup_value": {
      "name": "Custom Server",
      "description": "A custom game server",
      "setting_sections": {}
    }
  }'
```

--------------------------------

### Install Build Essentials for Rust Toolchain

Source: https://github.com/lodestone-team/lodestone/blob/main/core/README.md

This command installs the 'build-essential' package on Ubuntu systems, which is a prerequisite for compiling the Rust toolchain. It ensures that necessary development tools and libraries are available for building Rust projects.

```bash
sudo apt-get install build-essential
```

--------------------------------

### Install Development Libraries for Rust Compilation

Source: https://github.com/lodestone-team/lodestone/blob/main/core/README.md

These commands install 'pkg-config', 'libssl-dev', 'cpuidtool', 'libcpuid-dev', 'libffi-dev', 'libmagic-dev', and 'file' on Ubuntu systems. These packages are required for compiling the Axum web framework and for querying CPU information, as well as other dependencies needed for Lodestone.

```bash
sudo apt-get install pkg-config libssl-dev
sudo apt-get install cpuidtool libcpuid-dev
sudo apt-get install libffi-dev libmagic-dev file
```

--------------------------------

### TypeScript Simple Prelaunch Script

Source: https://context7.com/lodestone-team/lodestone/llms.txt

A basic TypeScript prelaunch script for Lodestone instances. This script runs before the instance starts and can perform initialization tasks. It blocks the instance startup until it completes.

```typescript
// prelaunch.ts - Simple prelaunch script
import { EventStream } from "https://raw.githubusercontent.com/Lodestone-Team/lodestone-macro-lib/main/events.ts";
import { Instance } from "https://raw.githubusercontent.com/Lodestone-Team/lodestone-macro-lib/main/instance.ts";

const current = await Instance.current();
const eventStream = new EventStream(current.getUUID(), await current.name());

console.log("Prelaunch script executing...");
eventStream.emitConsoleOut("Server is starting up!");

// Perform any pre-start tasks here
// This script blocks instance start until complete

```

--------------------------------

### Get Server Instance Settings Manifest

Source: https://context7.com/lodestone-team/lodestone/llms.txt

Retrieves the manifest of available settings for a server instance, including section IDs, setting names, and their types. Requires the instance UUID. Authentication is handled via JWT.

```bash
curl -X GET "http://localhost:16662/api/v1/instance/INSTANCE_UUID/settings" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Instance Server Control API

Source: https://context7.com/lodestone-team/lodestone/llms.txt

APIs for controlling the lifecycle of server instances, including starting, stopping, restarting, and killing them, as well as sending console commands.

```APIDOC
## Instance Server Control API

### Description
Start, stop, restart, and kill server instances. Send console commands directly to the game server.

## PUT /api/v1/instance/{INSTANCE_UUID}/start

### Description
Starts a server instance.

### Method
PUT

### Endpoint
`/api/v1/instance/{INSTANCE_UUID}/start`

### Parameters
#### Path Parameters
- **INSTANCE_UUID** (string) - Required - The unique identifier of the instance.

## PUT /api/v1/instance/{INSTANCE_UUID}/stop

### Description
Stops a server instance gracefully.

### Method
PUT

### Endpoint
`/api/v1/instance/{INSTANCE_UUID}/stop`

### Parameters
#### Path Parameters
- **INSTANCE_UUID** (string) - Required - The unique identifier of the instance.

## PUT /api/v1/instance/{INSTANCE_UUID}/restart

### Description
Restarts a server instance.

### Method
PUT

### Endpoint
`/api/v1/instance/{INSTANCE_UUID}/restart`

### Parameters
#### Path Parameters
- **INSTANCE_UUID** (string) - Required - The unique identifier of the instance.

## PUT /api/v1/instance/{INSTANCE_UUID}/kill

### Description
Forcefully stops (kills) a server instance.

### Method
PUT

### Endpoint
`/api/v1/instance/{INSTANCE_UUID}/kill`

### Parameters
#### Path Parameters
- **INSTANCE_UUID** (string) - Required - The unique identifier of the instance.

## GET /api/v1/instance/{INSTANCE_UUID}/state

### Description
Retrieves the current state of a server instance.

### Method
GET

### Endpoint
`/api/v1/instance/{INSTANCE_UUID}/state`

### Parameters
#### Path Parameters
- **INSTANCE_UUID** (string) - Required - The unique identifier of the instance.

### Response
#### Success Response (200)
- **state** (string) - The current state of the instance (e.g., "Running", "Stopped", "Starting", "Stopping", "Error").

### Response Example
```
"Running"
```

## POST /api/v1/instance/{INSTANCE_UUID}/console

### Description
Sends a console command to the server instance.

### Method
POST

### Endpoint
`/api/v1/instance/{INSTANCE_UUID}/console`

### Parameters
#### Path Parameters
- **INSTANCE_UUID** (string) - Required - The unique identifier of the instance.

#### Request Body
- **command** (string) - Required - The console command to execute.

### Request Example
```json
"say Hello everyone!"
```

### Example Usage
Sending an operator command:
```json
"op PlayerName"
```

Sending a whitelist command:
```json
"whitelist add PlayerName"
```
```

--------------------------------

### Deploy Lodestone with Docker

Source: https://context7.com/lodestone-team/lodestone/llms.txt

These commands demonstrate how to run Lodestone in a Docker container. Options include basic deployment, exposing game ports, handling multiple game ports, viewing setup keys from logs, and using a custom data directory. Persistent storage is managed using Docker volumes.

```bash
# Basic Docker deployment
docker run -d \
  --name lodestone \
  --restart unless-stopped \
  -p 16662:16662 \
  -v lodestone:/home/user/.lodestone \
  ghcr.io/lodestone-team/lodestone_core
```

```bash
# With Minecraft port exposed
docker run -d \
  --name lodestone \
  --restart unless-stopped \
  -p 16662:16662 \
  -p 25565:25565 \
  -v lodestone:/home/user/.lodestone \
  ghcr.io/lodestone-team/lodestone_core
```

```bash
# Multiple game ports
docker run -d \
  --name lodestone \
  --restart unless-stopped \
  -p 16662:16662 \
  -p 25565-25570:25565-25570 \
  -v lodestone:/home/user/.lodestone \
  ghcr.io/lodestone-team/lodestone_core
```

```bash
# View setup key from logs
docker logs lodestone | grep "setup key"
```

```bash
# Custom data directory
docker run -d \
  --name lodestone \
  -p 16662:16662 \
  -v /path/to/data:/home/user/.lodestone \
  ghcr.io/lodestone-team/lodestone_core
```

--------------------------------

### Start Playit.gg CLI Tunnel

Source: https://context7.com/lodestone-team/lodestone/llms.txt

Initiates a Playit.gg CLI tunnel through the Lodestone API. This command is used to connect your server to the internet without manual port forwarding.

```bash
curl -X POST "http://localhost:16662/api/v1/playitgg/start_cli" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Create a 'prelaunch.ts' Macro in TypeScript

Source: https://github.com/lodestone-team/lodestone/wiki/Intro-to-Macro-and-Task

This TypeScript macro is executed before a Lodestone instance launches. It demonstrates how to import Lodestone libraries, get the current instance, create an event stream, and emit a console output message to the instance's console. It utilizes Deno's module import system.

```typescript
import { EventStream } from "https://raw.githubusercontent.com/Lodestone-Team/lodestone-macro-lib/main/events.ts";
import { Instance } from "https://raw.githubusercontent.com/Lodestone-Team/lodestone-macro-lib/main/instance.ts";

const current = await Instance.current()

const eventStream = new EventStream(current.getUUID(), await current.name());

console.log("Start macro");

eventStream.emitConsoleOut("Hello world!");

console.log("End macro");

```

--------------------------------

### Core Backend Codebase Structure

Source: https://github.com/lodestone-team/lodestone/wiki/Getting-Started-for-Developers

A hierarchical view of the Rust backend ('Core') codebase, illustrating the organization of modules such as main entry point, library functions, instance implementations, traits, handlers, and authentication.

```tree
`core`
│   `main.rs` => entry point to the backend, invokes `run` from `lib.rs`
│   `lib.rs`    
│   │   `run` => completes the setup for the app, including initiating `AppState` and API `Routes` to expose
│   │   `restore_instances` => restore instances in `C:/Users/%USER%/.lodestone` to restore the instance to memory
│   └─  `AppState` => global variable that is used and managed by a web server framework Axum
│
└───`implementations` => the code that defines an instance
│   └───`generics` => `PENDING...`
│   └───`minecraft` => normal Minecraft instances
│       └─  `mod.rs` => defines the `MinecraftInstance` struct and all the methods it implements
└───`traits` => defines the traits the instances implements
│   └───`mod.rs`
│        │  `InfoInstance` => completes the setup for the app, including initiating `AppState` and API `Routes` to expose
│        └─ `TInstance` => generic trait that is a composition of multiple traits, implemented by the instances 
└───`handlers` => defines the route handlers for Axum and communication with the frontend
└───`auth` => code for users and authentication
```

--------------------------------

### Get Instance Information

Source: https://context7.com/lodestone-team/lodestone/llms.txt

Retrieves detailed information about a specific server instance using its UUID. Includes details like name, state, and player count. Authentication is handled via JWT.

```bash
curl -X GET "http://localhost:16662/api/v1/instance/INSTANCE_UUID/info" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Run Lodestone Core Docker Container

Source: https://github.com/lodestone-team/lodestone/wiki/Docker-Support

This snippet demonstrates how to create a Docker volume for persistent storage and then run the Lodestone Core Docker container. It maps the container's port to the host and ensures the container restarts automatically. The volume 'lodestone' is used for data persistence.

```sh
docker volume create lodestone
docker run -d \
    --name lodestone \
    --restart unless-stopped \
    -p 16662:16662 \
    -v lodestone:/home/user/.lodestone \
    ghcr.io/lodestone-team/lodestone_core
```

--------------------------------

### Build Lodestone Core Docker Image

Source: https://github.com/lodestone-team/lodestone/wiki/Docker-Support

This command shows how to build a custom Docker image for Lodestone Core using the provided Dockerfile. The image is tagged as 'lodestone_core:latest'. This is useful if you need to customize the build process or use a specific version not available in prebuilt images.

```sh
docker build -t lodestone_core:latest .
```

--------------------------------

### File System Operations (curl)

Source: https://context7.com/lodestone-team/lodestone/llms.txt

This section covers various file system operations using curl commands. It includes listing files, reading content, writing to files, creating new files and directories, deleting files and directories, copying and moving files, getting download URLs, uploading files, and unzipping/zipping archives. Each operation requires an instance UUID and a JWT token for authorization.

```bash
curl -X GET "http://localhost:16662/api/v1/instance/INSTANCE_UUID/fs/Lg==/ls" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
# Response: [{"name": "server.properties", "path": "server.properties", "file_type": "File", "size": 1024, ...}]
```

```bash
curl -X GET "http://localhost:16662/api/v1/instance/INSTANCE_UUID/fs/c2VydmVyLnByb3BlcnRpZXM=/read" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
# Response: "server-port=25565\nmotd=A Minecraft Server\n..."
```

```bash
curl -X PUT "http://localhost:16662/api/v1/instance/INSTANCE_UUID/fs/c2VydmVyLnByb3BlcnRpZXM=/write" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  -d 'server-port=25565
motd=My Awesome Server
max-players=20
online-mode=true'
```

```bash
curl -X PUT "http://localhost:16662/api/v1/instance/INSTANCE_UUID/fs/bmV3ZmlsZS50eHQ=/new" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

```bash
curl -X PUT "http://localhost:16662/api/v1/instance/INSTANCE_UUID/fs/YmFja3Vwcw==/mkdir" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

```bash
curl -X DELETE "http://localhost:16662/api/v1/instance/INSTANCE_UUID/fs/b2xkZmlsZS50eHQ=/rm" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

```bash
curl -X DELETE "http://localhost:16662/api/v1/instance/INSTANCE_UUID/fs/b2xkX2ZvbGRlcg==/rmdir" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

```bash
curl -X PUT "http://localhost:16662/api/v1/instance/INSTANCE_UUID/fs/cpr" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "relative_paths_source": ["world", "world_nether"],
    "relative_path_dest": "backups"
  }'
```

```bash
curl -X PUT "http://localhost:16662/api/v1/instance/INSTANCE_UUID/fs/b2xkLnR4dA==/move/bmV3LnR4dA==" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

```bash
curl -X GET "http://localhost:16662/api/v1/instance/INSTANCE_UUID/fs/d29ybGQ=/url" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
# Response: "random_download_key_32chars"
```

```bash
curl -X PUT "http://localhost:16662/api/v1/instance/INSTANCE_UUID/fs/bW9kcw==/upload" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "file=@path/to/mod.jar"
```

```bash
curl -X PUT "http://localhost:16662/api/v1/instance/INSTANCE_UUID/fs/YmFja3VwLnppcA==/unzip" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '"InPlace"'
# Or unzip to specific directory:
# -d '{"ToDir": "extracted_folder"}'
```

```bash
curl -X PUT "http://localhost:16662/api/v1/instance/INSTANCE_UUID/fs/zip" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target_relative_paths": ["world", "world_nether", "world_the_end"],
    "destination_relative_path": "worlds_backup.zip"
  }'
```

--------------------------------

### Get Server Instance State

Source: https://context7.com/lodestone-team/lodestone/llms.txt

Retrieves the current state of a server instance (e.g., Running, Stopped, Starting). Requires the instance UUID. Authentication is handled via JWT.

```bash
curl -X GET "http://localhost:16662/api/v1/instance/INSTANCE_UUID/state" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Define Atom Settings with setupManifest in TypeScript

Source: https://github.com/lodestone-team/lodestone/wiki/Intro-to-Lodestone-Atom

The `setupManifest` method defines the configurable settings for an Atom instance. It returns a `SetupManifest` object, which is a map of `SettingSection`s. Each section groups related settings, specifying their IDs, names, descriptions, values, types, and mutability. All section and setting IDs must be unique across all sections.

```typescript
    public async setupManifest(): Promise<Atom.SetupManifest> {
        return {
            setting_sections: {
                "section_id1": {
                    section_id: "section_id1",
                    name: "section_name1",
                    description: "section_description1",
                    settings: {
                        "setting_id1": {
                            setting_id: "setting_id1",
                            name: "Port",
                            description: "Port to run the server on",
                            value: null,
                            value_type: { type: "UnsignedInteger", min: 0, max: 65535 },
                            default_value: { type: "UnsignedInteger", value: 6969 },
                            is_secret: false,
                            is_required: true,
                            is_mutable: true,
                        }
                    },
                }
            }
        };
    }

```

--------------------------------

### Get Macro Execution History

Source: https://context7.com/lodestone-team/lodestone/llms.txt

Retrieves a list of historical executions for macros run on the instance.

```APIDOC
## GET /api/v1/instance/INSTANCE_UUID/history/list

### Description
Fetches the execution history of macros for the specified instance.

### Method
GET

### Endpoint
`/api/v1/instance/INSTANCE_UUID/history/list`

### Parameters
#### Path Parameters
- **INSTANCE_UUID** (string) - Required - The unique identifier for the instance.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
GET http://localhost:16662/api/v1/instance/INSTANCE_UUID/history/list
Authorization: Bearer YOUR_JWT_TOKEN
```

### Response
#### Success Response (200)
Details of the success response are not provided in the source text. It is expected to return a list of historical macro executions.

#### Response Example
None provided.
```

--------------------------------

### Get Lodestone Macro Configuration

Source: https://context7.com/lodestone-team/lodestone/llms.txt

Retrieves the current configuration settings for a specific macro on a Lodestone instance. The response includes the configuration details and any associated messages.

```bash
curl -X GET "http://localhost:16662/api/v1/instance/INSTANCE_UUID/macro/config/get/auto-backup" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Clone Lodestone Client Repository

Source: https://github.com/lodestone-team/lodestone/blob/main/core/README.md

This command clones the Lodestone client repository from GitHub. It is the first step in setting up the client locally.

```shell
git clone https://github.com/Lodestone-Team/client
```

--------------------------------

### Get Lodestone Macro Execution History

Source: https://context7.com/lodestone-team/lodestone/llms.txt

Retrieves a list of past macro execution events for a given Lodestone instance. This helps in monitoring macro performance and troubleshooting issues.

```bash
curl -X GET "http://localhost:16662/api/v1/instance/INSTANCE_UUID/history/list" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Generate Playit.gg Signup Link

Source: https://context7.com/lodestone-team/lodestone/llms.txt

Generates a signup link for Playit.gg, allowing users to create an account. This is part of the Playit.gg integration with Lodestone.

```bash
curl -X GET "http://localhost:16662/api/v1/playitgg/generate_signup_link" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### System and Monitor API

Source: https://context7.com/lodestone-team/lodestone/llms.txt

Retrieve system information, resource usage, and performance metrics for Lodestone instances.

```APIDOC
## GET /api/v1/system

### Description
Retrieves general system information.

### Method
GET

### Endpoint
/api/v1/system

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer YOUR_JWT_TOKEN

### Request Example
```bash
curl -X GET "http://localhost:16662/api/v1/system" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Response
#### Success Response (200)
- **info** (object) - Contains system details.

## GET /api/v1/core/info

### Description
Retrieves information about the Lodestone core.

### Method
GET

### Endpoint
/api/v1/core/info

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer YOUR_JWT_TOKEN

### Request Example
```bash
curl -X GET "http://localhost:16662/api/v1/core/info" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Response
#### Success Response (200)
- **uuid** (string) - The unique identifier of the core.
- **version** (string) - The version of the Lodestone core.
- **up_since** (integer) - Timestamp indicating when the core was started.

### Response Example
```json
{
  "uuid": "...",
  "version": "0.5.1",
  "up_since": 1699123456
}
```

## GET /api/v1/instance/:INSTANCE_UUID/monitor

### Description
Gets instance monitor data, including CPU and memory usage over time.

### Method
GET

### Endpoint
/api/v1/instance/:INSTANCE_UUID/monitor

### Parameters
#### Path Parameters
- **INSTANCE_UUID** (string) - Required - The UUID of the instance to monitor.
#### Headers
- **Authorization** (string) - Required - Bearer YOUR_JWT_TOKEN

### Request Example
```bash
curl -X GET "http://localhost:16662/api/v1/instance/INSTANCE_UUID/monitor" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Response
#### Success Response (200)
- **cpuUsage** (array) - Array of CPU usage data points over time.
- **memoryUsage** (array) - Array of memory usage data points over time.

## GET /api/v1/checks/health

### Description
Performs a health check on the Lodestone service.

### Method
GET

### Endpoint
/api/v1/checks/health

### Parameters
(No parameters required)

### Request Example
```bash
curl -X GET "http://localhost:16662/api/v1/checks/health"
```

### Response
#### Success Response (200)
(No specific response body detailed, assume a success indicator like 'OK' or a status object.)
```

--------------------------------

### Instance Configuration API

Source: https://context7.com/lodestone-team/lodestone/llms.txt

APIs for modifying server settings, changing versions, and updating instance properties.

```APIDOC
## Instance Configuration API

### Description
Modify server settings, change versions, and update instance properties. Settings are organized into sections with typed values.

## GET /api/v1/instance/{INSTANCE_UUID}/settings

### Description
Retrieves the settings manifest for a given instance, showing available settings and their types.

### Method
GET

### Endpoint
`/api/v1/instance/{INSTANCE_UUID}/settings`

### Parameters
#### Path Parameters
- **INSTANCE_UUID** (string) - Required - The unique identifier of the instance.

### Response
#### Success Response (200)
- **settings_manifest** (object) - An object detailing the settings structure.
  - **section_id** (object) - Represents a settings section.
    - **name** (string) - The display name of the section.
    - **settings** (object) - Contains individual settings within the section.
      - **setting_id** (object) - Represents a specific setting.
        - **value** (any) - The current value of the setting.
        - **value_type** (string) - The data type of the setting (e.g., "UnsignedInteger", "String").

### Response Example
```json
{
  "section_id": {
    "name": "...",
    "settings": {
      "setting_id": {
        "value": ...,
        "value_type": "..."
      }
    }
  }
}
```

## PUT /api/v1/instance/{INSTANCE_UUID}/settings/{SECTION_ID}/{SETTING_ID}

### Description
Updates a specific setting for a server instance.

### Method
PUT

### Endpoint
`/api/v1/instance/{INSTANCE_UUID}/settings/{SECTION_ID}/{SETTING_ID}`

### Parameters
#### Path Parameters
- **INSTANCE_UUID** (string) - Required - The unique identifier of the instance.
- **SECTION_ID** (string) - Required - The ID of the settings section.
- **SETTING_ID** (string) - Required - The ID of the setting to update.

#### Request Body
- **type** (string) - Required - The data type of the value being set.
- **value** (any) - Required - The new value for the setting.

### Request Example (Updating max RAM)
```json
{
  "type": "UnsignedInteger",
  "value": 8192
}
```

### Request Example (Setting server port)
```json
{
  "type": "UnsignedInteger",
  "value": 25565
}
```

## PUT /api/v1/instance/{INSTANCE_UUID}/name

### Description
Updates the name of a server instance.

### Method
PUT

### Endpoint
`/api/v1/instance/{INSTANCE_UUID}/name`

### Parameters
#### Path Parameters
- **INSTANCE_UUID** (string) - Required - The unique identifier of the instance.

#### Request Body
- **name** (string) - Required - The new name for the instance.

### Request Example
```json
"New Server Name"
```

## PUT /api/v1/instance/{INSTANCE_UUID}/description

### Description
Updates the description of a server instance.

### Method
PUT

### Endpoint
`/api/v1/instance/{INSTANCE_UUID}/description`

### Parameters
#### Path Parameters
- **INSTANCE_UUID** (string) - Required - The unique identifier of the instance.

#### Request Body
- **description** (string) - Required - The new description for the instance.

### Request Example
```json
"Updated server description"
```

## PUT /api/v1/instance/{INSTANCE_UUID}/version/{VERSION}

### Description
Changes the Minecraft version for a server instance.

### Method
PUT

### Endpoint
`/api/v1/instance/{INSTANCE_UUID}/version/{VERSION}`

### Parameters
#### Path Parameters
- **INSTANCE_UUID** (string) - Required - The unique identifier of the instance.
- **VERSION** (string) - Required - The new Minecraft version to set (e.g., "1.20.2").
```

--------------------------------

### TypeScript Automatic World Backup Macro

Source: https://context7.com/lodestone-team/lodestone/llms.txt

An example TypeScript macro for Lodestone that automatically backs up the Minecraft world. It uses Deno and the Lodestone macro library to copy the world folder at a configurable interval.

```typescript
// macros/auto-backup/index.ts - Automatic world backup macro
import { format } from "https://deno.land/std@0.177.1/datetime/format.ts";
import { copy } from "https://deno.land/std@0.191.0/fs/copy.ts";
import { sleep } from "https://deno.land/x/sleep@v1.2.1/mod.ts";
import { EventStream } from "https://raw.githubusercontent.com/Lodestone-Team/lodestone-macro-lib/main/events.ts";
import { MinecraftJavaInstance } from "https://raw.githubusercontent.com/Lodestone-Team/lodestone-macro-lib/main/instance.ts";

// Get handle to current instance
const currentInstance = await MinecraftJavaInstance.current();
const eventStream = new EventStream(currentInstance.getUUID(), await currentInstance.name());

// Configuration class - Lodestone parses and injects values
class LodestoneConfig {
  backupFolderRelative: string = "backups";
  delaySec: number = 3600;
}
declare const config: LodestoneConfig;

const instancePath = await currentInstance.path();
const backupFolder = `${instancePath}/${config.backupFolderRelative}`;

// Detach from prelaunch to allow instance to start
EventStream.emitDetach();

while (true) {
  eventStream.emitConsoleOut("[Backup Macro] Backing up world...");

  if (await currentInstance.state() === "Stopped") {
    eventStream.emitConsoleOut("[Backup Macro] Instance stopped, exiting...");
    break;
  }

  const now_str = format(new Date(), "yy-MM-dd_HH-mm");
  try {
    await copy(`${instancePath}/world`, `${backupFolder}/backup_${now_str}`);
    eventStream.emitConsoleOut(`[Backup Macro] Backup created: backup_${now_str}`);
  } catch (e) {
    console.error("Backup failed:", e);
  }

  await sleep(config.delaySec);
}
```

--------------------------------

### Instance Creation API

Source: https://context7.com/lodestone-team/lodestone/llms.txt

Endpoints for creating different types of game server instances, including Paper, Fabric, and generic instances.

```APIDOC
## POST /api/v1/instance/create/MinecraftJavaPaper

### Description
Creates a new Paper Minecraft server instance.

### Method
POST

### Endpoint
`/api/v1/instance/create/MinecraftJavaPaper`

### Parameters
#### Request Body
- **name** (string) - Required - The name of the server instance.
- **description** (string) - Optional - A description for the server instance.
- **port** (integer) - Required - The port number for the server.
- **min_ram** (integer) - Required - The minimum RAM allocation in MB.
- **max_ram** (integer) - Required - The maximum RAM allocation in MB.
- **version** (string) - Required - The Minecraft version to use.
- **auto_start** (boolean) - Optional - Whether to automatically start the server on creation.
- **restart_on_crash** (boolean) - Optional - Whether to restart the server if it crashes.

### Request Example
```json
{
  "name": "Paper SMP",
  "description": "High performance Paper server",
  "port": 25566,
  "min_ram": 2048,
  "max_ram": 8192,
  "version": "1.20.1",
  "auto_start": true,
  "restart_on_crash": true
}
```

## POST /api/v1/instance/create/MinecraftJavaFabric

### Description
Creates a new Fabric Minecraft server instance.

### Method
POST

### Endpoint
`/api/v1/instance/create/MinecraftJavaFabric`

### Parameters
#### Request Body
- **name** (string) - Required - The name of the server instance.
- **port** (integer) - Required - The port number for the server.
- **min_ram** (integer) - Required - The minimum RAM allocation in MB.
- **max_ram** (integer) - Required - The maximum RAM allocation in MB.
- **version** (string) - Required - The Minecraft version to use.
- **loader_version** (string) - Required - The Fabric loader version.
- **installer_version** (string) - Required - The Fabric installer version.

### Request Example
```json
{
  "name": "Modded Fabric",
  "port": 25567,
  "min_ram": 4096,
  "max_ram": 8192,
  "version": "1.20.1",
  "loader_version": "0.14.21",
  "installer_version": "0.11.2"
}
```

## POST /api/v1/instance/create_generic

### Description
Creates a generic game server instance using a provided URL for setup.

### Method
POST

### Endpoint
`/api/v1/instance/create_generic`

### Parameters
#### Request Body
- **url** (string) - Required - The URL to the setup script or configuration.
- **setup_value** (object) - Required - Configuration object for the generic instance.
  - **name** (string) - Required - The name of the server instance.
  - **description** (string) - Optional - A description for the server instance.
  - **setting_sections** (object) - Optional - Additional settings sections.

### Request Example
```json
{
  "url": "https://raw.githubusercontent.com/Lodestone-Team/lodestone-atom-lib/main/examples/basic.ts",
  "setup_value": {
    "name": "Custom Server",
    "description": "A custom game server",
    "setting_sections": {}
  }
}
```
```

--------------------------------

### Control Server Instance Lifecycle

Source: https://context7.com/lodestone-team/lodestone/llms.txt

Provides endpoints to control the lifecycle of a server instance, including starting, stopping (gracefully), restarting, and killing (forcefully). Requires the instance UUID. Authentication is handled via JWT.

```bash
# Start instance
curl -X PUT "http://localhost:16662/api/v1/instance/INSTANCE_UUID/start" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Stop instance (graceful shutdown)
curl -X PUT "http://localhost:16662/api/v1/instance/INSTANCE_UUID/stop" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Restart instance
curl -X PUT "http://localhost:16662/api/v1/instance/INSTANCE_UUID/restart" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Kill instance (force stop)
curl -X PUT "http://localhost:16662/api/v1/instance/INSTANCE_UUID/kill" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Create Minecraft Java Paper Server Instance

Source: https://context7.com/lodestone-team/lodestone/llms.txt

Creates a new Minecraft Java Paper server instance. Requires specifying server name, port, RAM allocation, version, and optional auto-start/restart settings. Authentication is handled via JWT.

```bash
curl -X POST "http://localhost:16662/api/v1/instance/create/MinecraftJavaPaper" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Paper SMP",
    "description": "High performance Paper server",
    "port": 25566,
    "min_ram": 2048,
    "max_ram": 8192,
    "version": "1.20.1",
    "auto_start": true,
    "restart_on_crash": true
  }'
```

--------------------------------

### Create Minecraft Java Fabric Server Instance

Source: https://context7.com/lodestone-team/lodestone/llms.txt

Creates a new Minecraft Java Fabric server instance. Requires specifying server name, port, RAM allocation, version, and Fabric loader/installer versions. Authentication is handled via JWT.

```bash
curl -X POST "http://localhost:16662/api/v1/instance/create/MinecraftJavaFabric" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Modded Fabric",
    "port": 25567,
    "min_ram": 4096,
    "max_ram": 8192,
    "version": "1.20.1",
    "loader_version": "0.14.21",
    "installer_version": "0.11.2"
  }'
```

--------------------------------

### Lodestone API User Management Operations

Source: https://context7.com/lodestone-team/lodestone/llms.txt

Provides examples for managing users within Lodestone, including retrieving user information, creating new users, updating permissions, listing all users, deleting users, and changing passwords. Requires appropriate JWT authentication and permissions.

```bash
# Get current user info
curl -X GET "http://localhost:16662/api/v1/user/info" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
# Response: {"uid": "user_id", "username": "admin", "is_owner": true, "permissions": {...}}

# Create new user (requires ManageUser permission)
curl -X POST "http://localhost:16662/api/v1/user" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "player1",
    "password": "user_password"
  }'
# Response: {"token": "eyJ...", "user": {"uid": "...", "username": "player1", ...}}

# Update user permissions
curl -X PUT "http://localhost:16662/api/v1/user/USER_ID/update_perm" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "can_view_instance": ["instance-uuid-1"],
    "can_start_instance": ["instance-uuid-1"],
    "can_stop_instance": ["instance-uuid-1"],
    "can_read_instance_file": ["instance-uuid-1"],
    "can_write_instance_file": [],
    "can_access_instance_console": ["instance-uuid-1"],
    "can_access_instance_setting": [],
    "can_create_instance": false,
    "can_delete_instance": false,
    "can_read_global_file": false,
    "can_write_global_file": false,
    "can_manage_permission": false,
    "can_manage_user": false
  }'

# List all users
curl -X GET "http://localhost:16662/api/v1/user/list" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Delete user
curl -X DELETE "http://localhost:16662/api/v1/user/USER_ID" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Change password
curl -X PUT "http://localhost:16662/api/v1/user/USER_ID/password" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "USER_ID",
    "old_password": "current_password",
    "new_password": "new_secure_password"
  }'
```

--------------------------------

### Instance Management API

Source: https://context7.com/lodestone-team/lodestone/llms.txt

Provides endpoints for creating, listing, and deleting game server instances.

```APIDOC
## GET /api/v1/instance/list

### Description
Retrieves a list of all configured game server instances.

### Method
GET

### Endpoint
`/api/v1/instance/list`

### Parameters
#### Query Parameters
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200)
- Returns an array of instance objects, each containing details like uuid, name, game_type, state, port, and version.

#### Response Example
```json
[
  {
    "uuid": "abc12345",
    "name": "My Server",
    "game_type": {"MinecraftJava": "Vanilla"},
    "state": "Stopped",
    "port": 25565,
    "version": "1.20.1"
  }
]
```

## POST /api/v1/instance/create/:gameType

### Description
Creates a new game server instance. The `gameType` parameter specifies the type of server to create (e.g., `MinecraftJavaVanilla`).

### Method
POST

### Endpoint
`/api/v1/instance/create/:gameType`

### Parameters
#### Path Parameters
- **gameType** (string) - Required - The type of game server to create (e.g., `MinecraftJavaVanilla`, `MinecraftJavaPaper`).

#### Query Parameters
- **Authorization** (string) - Required - Bearer token for authentication.

#### Request Body
- **name** (string) - Required - The name of the server instance.
- **description** (string) - Optional - A description for the server instance.
- **port** (integer) - Required - The port the server will listen on.
- **min_ram** (integer) - Required - Minimum RAM allocation in MB.
- **max_ram** (integer) - Required - Maximum RAM allocation in MB.
- **version** (string) - Required - The game version to install.
- **auto_start** (boolean) - Optional - Whether the instance should start automatically.
- **restart_on_crash** (boolean) - Optional - Whether the instance should restart if it crashes.

### Request Example
```json
{
  "name": "Survival Server",
  "description": "A vanilla survival world",
  "port": 25565,
  "min_ram": 1024,
  "max_ram": 4096,
  "version": "1.20.1",
  "auto_start": false,
  "restart_on_crash": true
}
```

### Response
#### Success Response (200)
- Returns the UUID of the newly created instance as a string.

#### Response Example
```
"instance-uuid-string"
```

## DELETE /api/v1/instance/:instanceId

### Description
Deletes a game server instance.

### Method
DELETE

### Endpoint
`/api/v1/instance/:instanceId`

### Parameters
#### Path Parameters
- **instanceId** (string) - Required - The UUID of the instance to delete.

#### Query Parameters
- **Authorization** (string) - Required - Bearer token for authentication.
```