Server management tools
These tools cover everything about the servers themselves: finding and updating server records, keeping notes on them, controlling the Alpacon agent, rebooting or upgrading the OS, and enrolling new hosts with registration tokens. They answer requests like “which servers do we have,” “restart the agent on web-01,” or “give me an install script for a new Debian box.”
All tools accept workspace (required) and region (optional, defaults to the configured region). These common parameters are omitted from the tables below.
Summary
| Tool | Description | Access |
|---|---|---|
list_servers | List all servers in a workspace | Read-only |
get_server | Get detailed information about one server | Read-only |
update_server | Rename or relabel a server | Idempotent write |
unregister_server | Remove a server from the workspace | Destructive |
star_server | Pin or unpin a server for quick access | Idempotent write |
list_server_notes | List documentation notes on a server | Read-only |
create_server_note | Add a documentation note to a server | Additive |
get_server_note | Get a single server note | Read-only |
update_server_note | Update an existing server note | Idempotent write |
delete_server_note | Delete a server note | Destructive |
restart_agent | Restart the Alpacon agent | Destructive |
shutdown_agent | Shut down the Alpacon agent | Destructive |
upgrade_agent | Upgrade the Alpacon agent to the latest version | Destructive |
update_information | Refresh collected hardware, OS, network, and package data | Additive |
upgrade_system | Upgrade all OS packages | Destructive |
reboot_system | Reboot the server | Destructive |
shutdown_system | Power off the server | Destructive |
list_registration_tokens | List Alpamon registration tokens | Read-only |
create_registration_token | Mint a new registration token | Additive |
delete_registration_token | Revoke a registration token | Destructive |
get_registration_guide | Get the platform-specific install script | Read-only |
Server inventory
Discover, rename, pin, and remove servers from the workspace inventory.
list_servers
List all servers in a workspace, returning name, UUID, status, OS, and connection info for each. Use this first to discover available servers and to obtain the UUIDs required by nearly every other server tool.
Access: Read-only
Example
“What servers do I have in production?”
Returns the full server inventory so you can find the one you need by name, OS, or status.
get_server
Get detailed information about a specific server by its UUID, including hostname, IP address, OS, agent version, and online status. Look up the UUID with list_servers first if you don’t already have it.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
Example
“Show me the details for web-01”
Looks up the UUID via list_servers, then fetches hostname, IP, OS, and status for that one server. For a fuller picture that includes hardware and OS internals, see System information tools.
update_server
Rename or relabel a server’s name or description by UUID. This only updates Alpacon’s inventory metadata—it doesn’t change anything on the host itself. At least one of name or description must be provided.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
name | string | No | New server name |
description | string | No | New server description |
Example
“Rename server 7e3984de-49ab-4cc6-bcdf-21fbd35858b8 to web-01-tokyo”
Updates the server’s display name in the inventory; the host itself is unaffected.
unregister_server
Remove a server from the workspace by UUID. The server disappears from all listings and can no longer be targeted by new Work Sessions, but the Alpamon agent keeps running on the host until it’s uninstalled there. This can’t be undone from this tool—re-enrolling the host requires running the install script with a registration token again.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
Example
“Unregister the decommissioned db-old server”
Confirm the UUID with get_server first—once unregistered, restoring the entry requires re-running the install script on the host.
star_server
Pin or unpin a server for the caller’s own faster access. This is a personal-preference flag, not a fleet-wide setting—it doesn’t change visibility, RBAC, or ACLs for anyone else.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
status | boolean | Yes | true to pin, false to unpin |
Example
“Star web-01 so I can find it faster”
Pins the server for the caller only; nobody else’s view of the inventory changes.
Server notes
Attach and manage freeform documentation on a server: maintenance logs, configuration notes, operational records.
list_server_notes
List documentation notes attached to a server, including titles, content, and timestamps. Use this to review existing operational records before adding new ones.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
Example
“What notes do we have on db-01?”
Returns every note recorded against that server.
create_server_note
Create a documentation note on a server with a title and content body. Use this to record operational notes, maintenance logs, or configuration documentation.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
title | string | Yes | Note title |
content | string | Yes | Note content |
Example
“Add a note to web-01: rotated the TLS cert on 2026-07-09”
Creates a new note attached to that server.
get_server_note
Get detailed information about a specific server note by its ID, including title, content, server, author, timestamps, and privacy settings. Look up the note ID with list_server_notes first.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
note_id | string | Yes | Note ID |
Example
“Show me the full content of that maintenance note”
Fetches the full detail of one note once you have its ID from list_server_notes.
update_server_note
Update an existing server note’s title or content by ID. This is a partial update—only the fields you provide are changed. At least one of title or content must be provided.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
note_id | string | Yes | Note ID |
title | string | No | New title |
content | string | No | New content |
Example
“Update that note to say the cert rotation is complete”
Only the content field changes; the title stays as-is unless you also pass a new one.
delete_server_note
Permanently delete a server note by its ID. This action cannot be undone.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
note_id | string | Yes | Note ID |
Example
“Delete the outdated maintenance note on db-01”
Confirm the note with get_server_note before deleting—there’s no undo.
Agent lifecycle
Control the Alpacon agent (Alpamon) running on a server, and trigger it to refresh the system information it reports.
restart_agent
Restart the Alpacon agent process on a server. The agent briefly goes offline during the restart. Use this when the agent is unresponsive or after configuration changes.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
Example
“Restart the agent on web-01, it’s not reporting metrics”
Restarts the agent process; the server briefly shows offline until it reconnects.
shutdown_agent
Shut down the Alpacon agent process on a server. The server appears offline in the workspace until the agent is manually restarted—remote access is lost until then.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
Example
“Shut down the agent on the decommissioned server”
Stops the agent; someone needs local or manual access to bring it back online.
upgrade_agent
Upgrade the Alpacon agent on a server to the latest available version. The agent briefly restarts during the upgrade.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
Example
“Upgrade the agent on web-01 to the latest version”
Triggers the upgrade on that server; loop over list_servers results to upgrade a whole fleet.
update_information
Refresh a server’s system information by triggering the agent to re-collect hardware, OS, network, and package data. Use this after hardware changes or OS updates so the dashboard reflects the current state.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
Example
“Refresh the info for web-01 after the RAM upgrade”
Triggers a re-scan; updated data appears once the agent finishes collecting it.
System control
Upgrade, reboot, or power off the operating system underneath a server.
upgrade_system
Upgrade all system packages on a server via the OS package manager (for example, apt upgrade or yum update). This may take several minutes depending on the number of pending updates—use with caution in production environments.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
Example
“Upgrade all packages on staging-02”
Runs a full package upgrade; a kernel update may require reboot_system afterward.
reboot_system
Reboot a server. It goes offline briefly and reconnects automatically once the agent starts back up. Use this after kernel updates or when a full system restart is required.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
Example
“Reboot staging-02 now that the kernel update finished”
Reboots the host; it reconnects on its own once it’s back up.
shutdown_system
Shut down a server completely. It powers off and does not automatically reconnect—bringing it back online requires manual intervention. Use with extreme caution.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID |
Example
“Shut down the old test server, we’re done with it”
Powers the server off for good until someone manually turns it back on.
Registration tokens & install guide
Issue and manage the tokens used to enroll new hosts, and fetch the platform-specific install script that uses them.
list_registration_tokens
List Alpamon registration tokens issued in the workspace—credentials embedded in the install script that authenticate a host on first run. Use this before issuing a new token or rotating a compromised one.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number for pagination |
page_size | integer | No | Number of results per page |
Example
“What registration tokens do we have active?”
Returns token IDs, names, and creation metadata for the workspace.
create_registration_token
Mint a new Alpamon registration token for installing the agent on a new host. The returned token is embedded in the install script (see get_registration_guide). Name tokens by cohort or batch (for example, prod-web-2026-q2) for clean rotation later.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Token name |
description | string | No | Token description |
Example
“Create a registration token for the new batch of web servers”
Mints a token you can pass straight into get_registration_guide.
delete_registration_token
Revoke an Alpamon registration token by ID. Already-enrolled hosts keep working—this only blocks future enrollments using the same token. Use this to rotate credentials after a suspected leak or once a rollout cohort is complete.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
token_id | string | Yes | Registration token UUID |
Example
“Revoke the token we used for last quarter’s rollout”
Blocks new installs with that token; hosts already enrolled are unaffected.
get_registration_guide
Get the platform-specific Alpamon install script for a registration token—the exact commands to run on the target host to bring it under Alpacon’s control. platform must be one of debian, rhel, darwin, or windows. Optionally pre-name the host with server_name.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
token_id | string | Yes | Registration token UUID |
platform | string | Yes | One of debian, rhel, darwin, windows |
server_name | string | No | Server name to pre-configure during installation |
Example
“Give me the install script for a new Debian server named web-05”
Returns the install commands for that token, pre-configured to name the host web-05.