Workspace management tools
These tools read and update workspace-wide settings—configuration that applies to everyone in the workspace, not a single user’s preferences. They cover the privilege-escalation and session-lifetime policy that governs sudo and tunnel access, the authentication and MFA requirements for signing in, notification channels, and workspace configuration like timezone, billing email, and allowed invite domains. They back requests like “what’s our workspace-wide sudo policy,” “is MFA required to sign in here,” or “turn on email notifications when a server disconnects.”
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 |
|---|---|---|
get_workspace_access_control | Get sudo/root access policy, tunnel and editor defaults, and Work Session TTLs | Read-only |
get_workspace_security | Get authentication and MFA requirements for the workspace | Read-only |
list_workspace_mfa_methods | List the MFA methods allowed for the workspace | Read-only |
get_workspace_notifications | Get notification channel settings | Read-only |
update_workspace_notifications | Update notification channel settings | Idempotent write |
get_workspace_preferences | Get workspace-wide preferences: timezone, locale, billing, and more | Read-only |
update_workspace_preferences | Update workspace-wide preferences | Idempotent write |
Access control
get_workspace_access_control
Gets the workspace access control settings: the sudo/root access policy (allow_sudo_with_mfa, allow_direct_root, block_local_sudo, sudo_timeout), tunnel and editor defaults, home_directory_permission, Work Session TTLs (work_session_max_ttl, work_session_pending_ttl), command-environment audit exposure, and shared_account_names. Use this to check what privilege-escalation and session-lifetime rules apply workspace-wide before requesting elevated access.
Self-hosted deployments omit the MFA-related fields (allow_sudo_with_mfa, block_local_sudo, sudo_timeout).
Access: Read-only
Example
“What’s our workspace-wide sudo and root access policy?”
The agent calls get_workspace_access_control and reports the sudo, root, and tunnel policy fields back to the user.
Security and MFA
get_workspace_security and list_workspace_mfa_methods require signing in through OAuth/SSO—a static API token is rejected before either tool sends a request. They’re also only available on Alpacon Cloud; self-hosted deployments report that the settings aren’t available on that deployment instead of returning a generic error.
get_workspace_security
Gets the workspace authentication and security settings: mfa_required, allowed_mfa_methods, mfa_timeout, and which actions require MFA.
Access: Read-only
Example
“Is MFA required to sign in to this workspace?”
The agent calls get_workspace_security and reports mfa_required and allowed_mfa_methods back to the user.
list_workspace_mfa_methods
Lists the MFA methods allowed for the workspace: allowed_mfa_methods and whether a passkey can satisfy MFA (passkey_as_mfa). Useful when a tool call fails with an MFA re-authentication requirement and you need to tell the user which methods complete the browser re-auth step.
Access: Read-only
Example
“A tool call just asked me to re-authenticate with MFA—what methods can I use?”
The agent calls list_workspace_mfa_methods and lists the allowed methods for the user to complete re-authentication with.
Notifications
get_workspace_notifications
Gets the workspace notification settings: disconnection_notification and the notification_channels used to deliver workspace-level alerts.
Access: Read-only
Example
“Do we get notified when a server disconnects?”
The agent calls get_workspace_notifications and reports disconnection_notification and the configured channels.
update_workspace_notifications
Updates the workspace notification settings. Only the fields you provide are sent (partial update).
notification_channels replaces the whole list—it does not append. To add a channel, first read the current list with get_workspace_notifications, merge in the new channel, then send the full list back; otherwise the channels you omit are dropped.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
disconnection_notification | boolean | No | Notify when a server disconnects/goes offline |
notification_channels | array | No | Channel types to notify through, e.g. email, webhook, push. Replaces the whole list |
Example
“Turn on email notifications when a server disconnects, and keep the existing webhook channel”
The agent calls get_workspace_notifications to read the current channels, then calls update_workspace_notifications with disconnection_notification=true and notification_channels set to the merged list including email and the existing webhook entry.
Preferences
get_workspace_preferences
Gets the workspace-wide preferences: timezone, locale (country/language), front_url, invite_ttl, enabled_extensions, websh_session_timeout, auto_agent_upgrade, package_proxy, billing_email, and allowed_domains. This is workspace-global configuration, not a per-user preference.
Access: Read-only
Example
“What timezone and invite settings is this workspace using?”
The agent calls get_workspace_preferences and reports timezone and invite_ttl back to the user.
update_workspace_preferences
Updates the workspace-wide preferences. Only the fields you provide are sent (partial update).
timezone is the workspace’s billing clock—changing it shifts the daily usage-aggregation boundary. enabled_extensions and allowed_domains replace the whole list rather than appending; read the current value with get_workspace_preferences, merge, then send the full list back to avoid dropping existing entries. Narrowing enabled_extensions also fails with HTTP 402 on non-enterprise plans. billing_email and allowed_domains are only accepted on Alpacon Cloud.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
front_url | string | No | Workspace front-end URL |
country | string | No | Workspace country code |
language | string | No | Workspace locale/language code |
timezone | string | No | Workspace timezone; also the billing clock |
invite_ttl | integer | No | Invitation link time-to-live, in seconds |
enabled_extensions | array | No | Enabled extension names. Replaces the whole list; narrowing it fails with HTTP 402 on non-enterprise plans |
websh_session_timeout | integer | No | Websh idle session timeout, in seconds |
auto_agent_upgrade | boolean | No | Whether agents auto-upgrade |
package_proxy | string | No | Proxy server URL for package installation, e.g. http://proxy.example.com:8080 |
billing_email | string | No | Billing contact email. Alpacon Cloud only |
allowed_domains | array | No | Allowed email domains for invites. Alpacon Cloud only; replaces the whole list |
Example
“Set the billing email to ops@example.com and move the workspace to the America/New_York timezone”
The agent calls update_workspace_preferences with billing_email="ops@example.com" and timezone="America/New_York", leaving every other field unchanged.
Related
- Access control & approvals tools: per-token ACLs and sudo policies, distinct from the workspace-wide policy these tools read
- Work Sessions: the sessions whose TTL bounds come from
get_workspace_access_control - Events & webhooks tools: configure individual webhook endpoints, as opposed to workspace-level notification channels