Instances

Instances are running containers created from a workload definition. Each instance is scheduled to a node and managed by the control plane through a declarative state model.

Instances Page Overview

The Instances page shows all deployed containers with their current state:

Instance List

Each instance displays:

• Workload Name: The template used to create the instance
• Node: Which node is hosting this instance
• State: Current status (running, stopped, creating, installing, error, etc.)
• Container ID: Docker container identifier

Actions

Quick actions available from the list:

• Console: Open the interactive terminal
• Start/Stop: Control instance state
• Delete: Remove the instance

Deploy an Instance

1. Navigate to Workloads page
2. Click Deploy on the desired workload
3. Select target Node from available healthy nodes
4. Configure overrides (optional):
   • Instance name
   • Port mappings
   • Environment variables
   • Resource limits
5. Click Deploy

Import from Pterodactyl

Shardlyn supports importing existing servers from Pterodactyl Panel:

1. Click Import Pterodactyl button
2. Enter Pterodactyl API URL and credentials
3. Select servers to import
4. Choose target node for each server
5. Confirm import

This migrates both the workload configuration and server data.

Instance Detail Page

Click on any instance to open the detail view with multiple tabs:

Console Tab

Interactive terminal connected via WebSocket:

• Real-time output from the container
• Send commands directly to the container stdin
• Search within console output
• Download logs as text file
• Clear terminal display

Logs Tab

View container logs with filtering options:

• Install logs (installation progress)
• Runtime logs (application/server output)
• Tail follow mode

Files Tab

Full file browser for the instance volume:

• Navigate directories
• Upload files (drag & drop supported)
• Download files and folders (as tar archive)
• Create new files and directories
• Edit text files inline
• Delete files and folders
• Move/rename files

Git Deploy Tab

Configure automated deployments from Git repositories:

• Connect to GitHub or GitLab
• Set target branch and path
• Enable webhooks for automatic sync on push
• Configure post-sync actions (restart, none)
• View sync history and status

See Git Deploy guide for detailed setup.

Backups Tab

Manage instance backups:

• Create on-demand backups
• Download backup archives
• Restore from previous backups
• Configure backup storage (local or S3/MinIO)

See Backups guide for configuration.

Instance State Machine

Instances transition through states:

pending → creating → running ↔ stopped → removing → removed
                  ↘ error

• pending: Waiting for agent to process
• creating: Container being created
• installing: Running install script (if configured)
• running: Container active and healthy
• stopped: Container stopped but preserved
• error: Failed state, check logs for details
• removing: Container being destroyed

Day-2 Operations

Start/Stop/Restart/Kill

Control instance lifecycle from the detail page header:

• Start: Resume a stopped instance
• Stop: Gracefully stop the container
• Restart: Stop and start in sequence
• Kill: Force terminate (SIGKILL)

Edit Instance

Modify instance configuration:

• Change name
• Update environment variables
• Adjust port mappings
• Modify resource limits

Monitor Resources

Real-time resource metrics displayed in the header:

• CPU usage percentage
• Memory usage and limit
• Network I/O
• Uptime

Next Steps

• Workloads — Create and manage the container templates behind your instances
• File Management — Upload, download, and edit files inside instances
• Backups — Configure scheduled backups and restore from snapshots
• Observability — Monitor instance CPU, memory, and performance metrics