Manage customer servers in the staff console

/staff/servers in the staff console lists every server your customers hold. Each server's page, at /staff/servers/{uuid}, lets your team do most of what the customer can do in their own panel: power, the live console, files, ports, databases, snapshots, schedules, software, startup and subusers. Staff also see what the customer cannot: the node the server runs on, its real address and its last install error. Use these pages to answer a support question, fix an install or act on abuse.

Readonly and Tier 1 members cannot open these pages. On them each role can do everything the roles below it can, and the tasks need:

A step-up is a fresh password or authenticator code, which lasts 10 minutes; Sign in to the staff console explains it. Staff actions have the same limits as the customer's, counted for each member on each server. The sections below give them.

On a server's page and in the fleet's header, a control your role cannot use stays where it is, dimmed, and names the role it needs, such as Needs Tier 3 support or higher. A menu item does the same with a hint beside it. What a role cannot use explains it. The console's saved views, quick view and keyboard shortcuts work on this list as on every other.

1. Open /staff/servers. It opens on the running servers, most players first, as the platform's own server list does. The header says when the list last arrived, such as Updated 3m ago, and its refresh button reloads it.
2. Search by the server's name, hostname or UUID, the owner's email, or the IP address. A * matches any text, so *@example.com finds the servers of every owner at that domain. Press / to move to the search box.
3. Choose a status to narrow the list. The Status choice has three groups, and Every status shows them all:
   • Power: Running, Stopped, Starting, Stopping and No reading yet. They say what the node last saw the server doing, and No reading yet means the node has not reported on it. The API words are running, offline, starting, stopping and unknown.
   • Lifecycle: Installing, Install failed, Suspended and Transferring (installing, install_failed, suspended and transferring). They hold servers that cannot run in that state.
   • To check: Needs attention (attention) holds failed installs, servers moving between nodes, and installs that have run for more than 3 minutes. Watch (watch) holds free servers that have a port beyond the primary, or have run for 7 days without a stop. Neither proves abuse, so treat the list as a place to start checking.
   • A power word never matches the lifecycle column. A server that is suspended is in Suspended, whatever its node last said. A link can also carry free (status=free), which holds every free server. The audience switch does the same job in the console.
4. Choose a node with the Node choice. To narrow further, choose Filters, which opens a drawer with Server name, Owner, Software, Created from and to, Extra ports at least, Up for at least (days) and Average CPU at least, measured as a percentage of one core or of the server's own CPU limit, over the last hour or the last 15 minutes. Use the audience switch to keep only paying or only free customers. A link from a pattern on the Abuse page keeps the servers of that pattern's accounts, and the chip above the list names the pattern (Stop a wave of abusive sign-ups).

Six tiles sit above the list: Needs attention, Install failed, Installing, Running, Suspended and Watch. Each is a status filter, and choosing the active one again shows every status. A tile with nothing behind it rests quietly. The tiles count every server of your brand. They are normally no more than 30 seconds old, and up to 5 minutes old on the first screen after a quiet spell. The list is always current.

Each row shows the server's name and short ID, its status with the time of the last reading, players online, uptime, address and node, and owner, and its CPU, RAM and disk use against its limits. While the page is open it asks the nodes about the servers on screen every 8 seconds, and not while the tab is hidden, so these figures move. A server our abuse review has locked is marked as locked, and one that is suspended with a deletion date says when it deletes.

The list lands sorted by players online, most first. Select any column heading to sort by it, or use the Sort menu, which reaches more keys: uptime, created, updated, name, status, join address, IP address, port, node, owner, runtime, the CPU, RAM and disk in use, their limits, and server ID, with Reverse order at the top. The sort is in the address. Without a sort, the API puts failed installs and transfers first, then the newest.

• The Views menu lists Running, Needs attention, Install failed, Idle, Suspended, Watch and Every server as built in views. Idle is the running servers with the fewest players first. Choose Save this view to keep the status, node and sort under a name, and share it with the team from Tier 3 support. Saved views explains them.
• Select a row for a quick view of the server: its memory, disk and CPU limits, join address, address, node, location, software, owner and last error, with an Open server button. The quick view opens for Tier 2 support and up, which is everyone who can open this page.
• The quick view has more buttons at the start of its footer for the roles that can use them. Tier 3 support and up see Suspend… while the order is active and Unsuspend… while it is suspended. An admin also sees Delete server… until the order has ended. Tier 2 support and below see neither. Suspend… asks for a reason of up to 300 characters, which the customer sees on the suspended server. Delete server… opens the Terminate dialog: a reason of 3–500 characters, the choice to email the customer, and the server's name typed back. An admin must have stepped up in the last 10 minutes, and the console asks for a password or code when they have not. The quick view then loads the server again and the list reloads behind it. After Delete server… the quick view closes. Each member can suspend 120 servers an hour, lift 120 suspensions an hour and terminate 30 servers an hour. Change a customer's service says what each action does.
• Press j and k to move between rows, Enter for the quick view, o to open the server's page and x to tick a row. Hold Ctrl or Cmd and click to open the page in a new tab.

Open the server from the list. Its page names the owner and the order, and for a free server ordered since the free-tier checks began, the address the order came from and the kind of network: a home connection, hosting, a VPN, a proxy or a Tor exit. It shows:

• the live console and the server's resource use;
• the node and location it runs on, and its real address, even on a free server whose customers see only the hosted address;
• its plan limits, its runtime and its last install error.

Tier 2 sees the console and the logs only. To read the rest of a server's files, ask the customer for access from their support conversation, as Answer customer conversations explains.

A free server sleeps when nobody plays on it, as How free servers work explains, and its page shows the phase it is in: awake, starting, queued or asleep.

• Start, restart or stop the server with the buttons in the page's header: Start when it is down, Restart and Stop when it is up. Kill server, in the ⋯ menu, is for a server that will not stop. Each member may send 24 power actions a minute to one server. Below Tier 3 support the buttons stay, dimmed.
• Choose Wake server to wake a sleeping free server. A paid server does not sleep, so start it instead.
• When a free server stays stuck in the start queue, choose Kick the wake queue. We check the server against its node and, if it is still down, start it ahead of the queue. The button is dimmed below Admin, with Needs admin or higher, and Tier 3 support can also do it through the API.
• A free server that stopped while starting three times in a row with the same error says Stopped retrying with the error. We do not start it again until the customer wakes it, an admin kicks the queue, or a day passes.
• Type a command into the live console, or send one of up to 1,000 characters. We record each command in the audit log, up to its first 200 characters. Each member may send 60 commands a minute to one server.

Tier 2 can watch the console but cannot type in it.

Tier 2 may list, read and download files inside logs/ and crash-reports/, where a server writes down its problems. Tier 3 has the customer's whole file manager: edit files, make folders, upload files of up to 100 MB each, rename, copy and delete, change permissions, compress and extract archives, and download a file from a URL onto the server. Compressing, extracting and downloading from a URL each allow 24 a minute for each member on one server.

We record every change in the audit log with the paths it touched.

Your organization can make free customers ask for extra ports instead of adding them, with the port requests switch described in Manage the staff team and console settings. Paid servers are never affected. Each request arrives in the support inbox as a conversation tagged port-request and free, with the subject Extra port for and the server's name, and the customer's reason in the first message.

1. Open the conversation in /staff/inbox and read what the port is for.
2. Choose Add a port on the server in the ticket's Servers card. The console notes the ticket's number on the port and tells you which port it added. You can also open the server and add a port from its Network tab.
3. Reply to the customer with the port number, and close the conversation.

We pick a free port from the node's shared range, 10000–40000, unless you choose one. A server may hold 5 shared ports including its primary, unless its plan sets another number. The ports we manage for Bedrock players and the ports the server's software needs, such as a Rust server's query and RCON ports, do not count. On a server with a Floating IP you can instead open any port from 1024 to 65535 on that address, up to 16 of them. A port added to a running server opens when the server next restarts, and the console offers the restart.

Your team can also:

• Make a port the primary one, which players connect to. We move the server onto it and restart the server if it is running. A port the software needs cannot be the primary.
• Publish a port on the game's default port, 25565 or 19132, of the server's Floating IP.
• Release a port. The primary port, a port we manage, and the last shared port of a server with a Floating IP cannot be released. A running server keeps a released port until it restarts, so the console asks before it releases the port and restarts the server.

Manage server ports explains ports as the customer sees them.

1. Choose Needs attention or Install failed in the Status choice on /staff/servers, or select the matching tile, and open the server.
2. Read the install log: the last 400 lines the install script wrote, and the output we recorded while it ran.
3. Choose Heal install in the server's ⋯ menu. We read the server's disk first: when the files are in place, we mark the server running and reinstall nothing, and otherwise we run the install again. To run the install again without that check, retry it instead, which works only on a server that is install_failed or installing.

To heal every broken install at once, choose Heal every failed install in the header of /staff/servers. It shows how many have failed, asks first, and takes up to 25 servers, oldest first: failed installs, and installs that nothing has moved for 45 seconds. Below Tier 3 support the button is dimmed.

Each member may reinstall, retry or heal one server 8 times in 10 minutes. A reinstall of a working server wipes every file on it, so use it only when the customer wants to start again.

Tier 3 lists the server's snapshots, or every snapshot its owner holds with whether each can be restored onto this server. Tier 3 can also check whether a new snapshot fits, take one, download one, and lock or unlock one. An admin who has stepped up can restore a snapshot onto the server, which replaces its files, or delete one.

Snapshots count against the owner's snapshot storage, as How snapshot storage works explains. Servers made before snapshots may still have backups: your team can list, lock, restore and delete them with the same roles, but cannot take a new one.

Tier 3 lists a server's databases, creates one, sets a new password for one, and retries one that failed to create. Reading a password needs a step-up. Deleting a database needs an admin who has stepped up, because nothing brings it back. For each member on one server, creating allows 24 a minute and setting a new password 16 a minute.

Tier 3 reads a server's schedules and their recent runs, runs a schedule now, and pauses or resumes one that is hurting the server. An admin can delete a schedule. Creating and changing schedules stays with the customer.

• Software: Tier 3 sees what the server runs and what it can change to, changes it, and cancels or retries a stuck add-on install. A change that wipes the server needs its name typed to confirm. Each member may change one server's software 8 times in 10 minutes.
• Bedrock crossplay: on a Java server that can run Geyser, Tier 3 turns Bedrock crossplay on or off with Change, then Turn on crossplay or Turn off crossplay, on the Software tab. While it is on, on a plugin server, Change also offers Use Geyser development builds and Use Geyser releases. A Fabric or NeoForge server takes Geyser's release for its Minecraft version, so it has neither. Each action asks for confirmation, shows the reason when the server cannot run Geyser, and counts toward the same 8 changes in 10 minutes as a software change.
• Startup: Tier 3 reads how the server starts. An admin who has stepped up can move it to another runtime of the same kind, such as Java 17 to Java 21, set or reset its startup command, and set or remove environment variables. The change applies at the next start, and we do not restart the server.
• Settings: Tier 3 renames the server, turns world optimization on or off, changes the subdomain of its join address, and changes the startup variables the customer can change: every one but the platform's own, the Java settings' and safe mode's, and on a free server the one naming the program it runs. When the server has a custom domain, we email the customer the new target for their DNS record.
• Server icon: on a Minecraft Java server, the Server icon panel on the Settings tab shows the server's icon and whether Minecraft shows it. Tier 3 uploads any picture, and we turn it into the 64×64 PNG the game needs, fitted to the square the way the panel's fit choice says. Tier 3 can also remove the icon. When the file is there but Minecraft ignores it, such as a 512×512 logo the customer uploaded over SFTP, Fix it converts it in place. The customer restarts the server to show the change, and each change goes on the audit log.

Tier 3 lists the server's subusers, trims one's permissions, or removes one. We email the person you removed. Removing also cancels an invite that has not been accepted. Adding people stays with the owner, as Share a server with other users explains.

Tick up to 100 servers on /staff/servers, and choose an action in the bar that appears: Suspend, Unsuspend, Pause owners, Terminate or Ban owners. Below Admin the bar leaves out the last three and says Pausing, banning and terminating need an admin. The dialog asks for a reason of 3–500 characters, and the actions are:

• Suspend stops each server as an unpaid invoice would, and keeps its files. An admin who has stepped up can add a deletion date 1–90 days away, when we delete the server.
• Unsuspend lifts the suspension, and calls off a deletion date your team set.
• Terminate, for an admin who has stepped up, ends each order now with no credit and keeps a snapshot. We email the customer only when you choose to.
• Pause owners, for an admin who has stepped up, suspends each owner's account and every order on it, and ends their sessions. Unsuspending the account on its page brings it back.
• Ban, for an admin who has stepped up, bans each owner, ends their sessions and ends every order they have, including servers you did not select.

Unless you turn it off, each customer gets one conversation in your inbox's abuse department, assigned to you. The customer reads a notice that names the servers without saying how you found them, and your reason stays in an internal note. Lifting a suspension opens no conversation. We skip servers that are outside your organization or already ending, and list each with its reason. Each member may run 12 of these an hour.

To act on more than one page, tick the whole page and then select all matching servers, which the bar offers once the list is filtered. The action then starts a bulk run over every server the filter matches, up to 20,000, which works in the background. It opens no conversations unless you ask it to. The extra ports, uptime and CPU filters cannot drive a run, and the bar says so while one is set. Stop a wave of abusive sign-ups explains runs.

Each change shows on the server at once, and the customer sees it in their own panel. The audit log records every action with the member who took it and the server's UUID.

Tier 2 support access required

Readonly and Tier 1 members cannot open servers. Ask an admin for a Tier 2 role or higher.

Support access required

The action needs Tier 3 support or a higher role.

Server is not in this organization

The server belongs to another organization, or its order has been terminated. A UUID that matches no server answers 404 Server not found.

Tier 2 reads a server's logs/ and crash-reports/; ask the customer for access to see the rest

Below Tier 3 you can read only those two folders. Ask the customer for access from their conversation.

423 with reason set to server_locked

Our abuse review has locked the server, because our sensors found abuse on it or because our team locked it by hand. The customer's conversation about the lock is in your inbox's abuse department. Only we can lift the lock, so escalate that conversation to us if you think it is a mistake. When the review finds abuse on a free server and the customer pays for nothing else, we can end it by deleting the server and banning the account. Every other order on the account then ends too, we close the conversation, and we email the customer that the account was closed for breaking the acceptable use policy. Your audit log records the ban as customer.abuse.ban.

409 with reason set to world_optimization_running

We are removing unused chunks and the server cannot start until that ends. Try again after retry_after_seconds.

This server does not sleep; use the power action to start it.

The server is on a paid plan. Start it instead of waking it.

Not a free-tier server; use a power action

Only a free server has a start queue. Start the server instead.

Server is running, not install_failed or installing

A retry only reruns a failed or stuck install. To start a working server again from nothing, reinstall it, which wipes its files.

Allocation limit reached (5). Cannot add more ports to this server.

The server holds every shared port its plan allows. Release one, or open the port on the server's Floating IP.

Port must be between 10000 and 40000

Choose a port in the shared range, or leave the port out and we pick one.

Port 25565 is reserved on the node main IP (gameproxy / platform services)

We keep that port for our own services on the node. Choose another, or leave the port out.

Port 20145 is already in use on this node

Another server holds that port. Choose another, or leave the port out.

Attach a floating IP first; there is no dedicated address to open a port on

The server has no Floating IP. Open the port in the shared range instead.

Cannot release the primary allocation

Make another port primary first.

Keep at least one shared node port: it is what this server falls back to if the floating IP is detached.

A server with a Floating IP keeps one port in the shared range.

java-17 is not a nodejs runtime; changing the runtime family is a software change, which reinstalls

A runtime moves only within its kind. Change the server's software instead.

No database host on this server's node

We have not set up databases on the node this server runs on. Contact our support.

402 with reason set to over_allowance

The snapshot does not fit the owner's snapshot storage. Delete an old snapshot, or ask the customer to add storage.

410 with reason set to replaced_by_snapshots

Snapshots have replaced backups. Take a snapshot instead.

Ending servers or accounts, or pausing them, needs an org admin; support can suspend without a deletion date

Terminate, pausing owners, ban and a suspension with a deletion date need an admin. Suspend without a date, or ask an admin.

429 with error set to rate_limited

You reached the limit for that action on this server. Try again after retry_after_seconds.

• Answer customer conversations, where port requests arrive and you ask for access to a server
• Let customers run their servers, the same servers from the customer's side
• Handle billing in the staff console, to suspend, cancel or retry the order behind a server
• Look after customers in the staff console, to open the customer's own panel

These routes live under https://api.coritan.com/api/v1/orgs/{org_slug}/staff/servers/, and take a console session or a member's access token as The staff console explains. A step-up needs a console session. Servers in the staff console lists every route but one: the reference lists PATCH /staff/servers/{uuid}/settings with the brand settings routes.

curl "https://api.coritan.com/api/v1/orgs/acme/staff/servers?status=watch&owner=*@example.com&sort=uptime&limit=50" \
  -H "Authorization: Bearer $STAFF_TOKEN"

The answer is a list of servers, each with uuid, name, hostname, status, power, customer, node_name, address, usage, uptime_seconds, join_address, players_online, extra_ports, is_free, locked and install. The list takes:

• q, up to 200 characters, matched against the name, hostname, UUID, owner's email and IP address. A * is a wildcard here and in name and owner.
• status, one of the words in Find a server, or all.
• node_id, customer_id, or customer_ids with up to 100 comma-separated IDs.
• audience: paid, free or all.
• name (server name or hostname), owner (email, name or company) and software (runtime name), each up to 200 characters; created_after and created_before, whole days that both count; min_extra_ports 0–64; and up_days_min.
• pattern_id: the servers of a pattern's accounts (Stop a wave of abusive sign-ups).
• cpu_min, as a percentage of one core, or cpu_of_limit_min, as a percentage of the server's own limit, averaged over cpu_window: 15m or 1h (the default).
• sort: created, updated, name, status, players, join_address, ip, port, node, owner, template, cpu, memory, disk, cpu_limit, memory_limit, disk_limit, uptime or id. dir is asc or desc; names sort ascending and figures descending unless you say otherwise.
• limit 1–200 (50 by default) and offset.

An unknown sort answers 400 with the words it takes. GET /staff/servers/stats counts the servers in each status, with attention, watch, slow_installs and each node's total and install_failed. The counts are normally no more than 30 seconds old, and up to 5 minutes old on the first request after a quiet spell. GET /staff/servers/live?uuids= takes up to 100 comma-separated UUIDs and answers each one's live state, usage, players_online and join_address. It leaves out any UUID outside your organization.

GET /staff/servers/{uuid} answers the server as the customer sees it, plus customer_id, customer_email, customer_name, org_service_id, org_service_status and infrastructure: the node_name, location, real address, limits, docker_image, template_name, sleep_policy, allocation_limit, database_limit, installed_at, last_error and last_error_at. For a free server ordered since the free-tier creation rules began, grant holds the address it was ordered from (ip), the kind of network (ip_kind: residential, hosting, vpn, proxy, tor or private) and when (created_at); otherwise it is null. GET /resources answers live resource use, and GET /sleep answers the sleep state and the plan's entitlements.

Tier 2 reads logs with the file routes:

curl "https://api.coritan.com/api/v1/orgs/acme/staff/servers/$SERVER_UUID/files/contents?path=/logs/latest.log" \
  -H "Authorization: Bearer $STAFF_TOKEN"

GET /files/list?directory=/crash-reports lists a folder, and GET /files/download?path= streams one file. GET /websocket answers a token and the socket address of the live console.

curl -X POST https://api.coritan.com/api/v1/orgs/acme/staff/servers/$SERVER_UUID/power \
  -H "Authorization: Bearer $STAFF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"signal": "restart"}'

{"message": "Power action 'restart' sent"}

signal is start, stop, restart or kill. POST /command takes {"command": "say Back in five minutes"}, 1–1000 characters. POST /wake wakes a sleeping free server and answers its sleep state, and POST /wake-queue/kick starts one that is stuck in the queue. POST /reinstall reinstalls the server.

curl -X POST https://api.coritan.com/api/v1/orgs/acme/staff/servers/$SERVER_UUID/allocations \
  -H "Authorization: Bearer $STAFF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"notes": "port request #1042"}'

It answers 201 with the new port's id, ip, port, notes and is_primary. Send port to choose the port, and on_dedicated_ip: true to open it on the server's Floating IP. GET /allocations answers the server's ports as items, with allocation_limit and allocation_used, and GET /allocations/available-ports?limit=50 lists up to 200 free ones. POST /allocations/{allocation_id}/primary makes a port primary, POST /allocations/{allocation_id}/publish-port takes {"port": 25565} or {"port": null} to clear it, and DELETE /allocations/{allocation_id} answers {"message": "Allocation released"}.

GET /install-log answers the status, last_error, the install script's script_log and our recorded_output, each up to 400 lines. POST /heal-install takes {"start_after": true} to start the server once it is healed, and answers the action we took: marked_running, reinstall_started or reinstall_failed. POST /retry-install answers 409 for a server that is not install_failed or installing. POST /staff/servers/heal-installs?limit=25 heals up to 25 broken installs and answers how many were healed, reinstalled and failed.

POST /snapshots takes an optional name of up to 191 characters. A restore replaces the server's files; send {"truncate": false} to keep files the snapshot does not hold. PATCH /startup takes runtime_template_slug, startup_command (one line, up to 4,000 characters) or reset_startup_command: true, variables to set and remove_variables. Variable names are capital letters, digits and underscores, and values are one line of up to 1,024 characters.

GET /software/context says what the server runs, GET /software/catalog lists what it can change to, and POST /software/change takes target_key, version and mode: keep, or wipe with confirm_server_name. PATCH /settings takes name and world_optimization_enabled, PATCH /subdomain takes a subdomain of 1–28 characters, and PATCH /startup-variables takes the variables the game allows. GET /server-icon reads the icon, POST /server-icon takes a multipart file and a fit of cover, contain or stretch and saves it as server-icon.png, and DELETE /server-icon removes it; the audit log records them as server.icon.set and server.icon.remove. POST /software/bedrock takes enabled, and PUT /software/bedrock/channel takes channel set to release or development; the audit log records them as server.bedrock_bridge.set and server.bedrock_bridge.channel, with the reason when the change is refused. GET /users lists subusers, PUT /users/{subuser_id} takes their permissions, which GET /permissions lists, and DELETE /users/{subuser_id} removes one.

curl -X POST https://api.coritan.com/api/v1/orgs/acme/staff/servers/bulk \
  -H "Authorization: Bearer $STAFF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"uuids": ["3f6c2a9e-8b1d-4c57-9e02-5d7a41b8c613", "b72d0e41-5a9c-4f3b-8e61-0c4d2f7a9b35"], "action": "suspend", "reason": "Crypto mining on free servers", "delete_after_days": 14}'

action is suspend, unsuspend, terminate, pause or ban; pause suspends each owner's account and every order it has. To act on every server a filter matches, start a bulk run (Stop a wave of abusive sign-ups). delete_after_days (1–90) applies to a suspension, open_ticket defaults to true, and notify_customer (default false) sends the cancellation email on a termination. The answer lists the UUIDs applied, the ones skipped with a reason, each customer with their servers and ticket_id, and the termination_date.