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, and workspace configuration like timezone, billing email, and allowed invite domains. They back requests like “what’s our workspace-wide sudo policy” or “is MFA required to sign in here.”
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_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.
Deployments without Auth0 (self-hosted) omit allow_sudo_with_mfa and sudo_timeout. They return block_local_sudo only while a stored value of true is in force, so it can still be found and turned off; it can’t be turned on there.
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). 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.
The same list decides whether a passkey sign-in counts as MFA: it does when the list is empty or includes webauthn-platform (biometric authentication) or webauthn-roaming (hardware security key). See Passkeys and allowed MFA methods. The response may also carry passkey_as_mfa, a retired setting that no longer changes the result.
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.
Preferences
get_workspace_preferences
Gets the workspace-wide preferences: timezone, locale (country/language), front_url, invite_ttl, enabled_extensions, websh_session_timeout, agent_rollout_policy, package_proxy, billing_email, and allowed_domains. This is workspace-global configuration, not a per-user preference.
The response also carries auto_agent_upgrade, a deprecated boolean kept for one release: true unless the rollout mode is manual. Read agent_rollout_policy instead.
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. enabled_extensions fails with HTTP 402 if the list includes an extension above the workspace’s plan—each extension has its own floor: Metrics needs Essentials, the rest need Enterprise (see Extensions). It fails with HTTP 400 workspace_extension_requires_extension if the list turns on DNS or Proxy without IP, or drops IP while DNS or Proxy stays in it. 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; fails with HTTP 402 if it includes an extension above the workspace’s plan (Metrics needs Essentials, the rest need Enterprise), and with HTTP 400 if it turns on DNS or Proxy without IP, or drops IP while either stays |
websh_session_timeout | integer | No | Websh idle session timeout, in seconds |
agent_rollout_policy | object | No | The agent rollout policy: {"mode": "latest" | "n_minus_1" | "manual", "window": {"days": [0-6, Monday is 0], "start_hour": 0-23, "length_hours": 1-24, "timezone": "<IANA>"}}. May name only part of the object; whatever it leaves out keeps its current value |
auto_agent_upgrade | boolean | No | Deprecated, kept for one release; use agent_rollout_policy. See Deprecated auto_agent_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 |
Agent rollout policy
manual runs no automatic upgrade; latest upgrades agents to new releases inside the maintenance window; n_minus_1 stays one release behind. Until verified upgrades are enabled, n_minus_1 is refused with preferences_agent_rollout_mode_unavailable; use latest or manual. A malformed agent_rollout_policy is rejected with a field-specific message before any request is sent. A value the server still refuses comes back with its error code (preferences_agent_rollout_policy_invalid, _mode_invalid, _window_days_invalid, _window_start_hour_invalid, _window_length_invalid, or _window_timezone_invalid) and a message saying what to fix. See the Workspace preferences API for each field’s range.
Deprecated auto_agent_upgrade
auto_agent_upgrade is still accepted for one release and is translated into a rollout policy write before the request is sent:
truebecomes{"mode": "latest"}, andfalsebecomes{"mode": "manual"}. The window isn’t changed.- When the same call also passes
agent_rollout_policy,agent_rollout_policywins on any field it names. - The response of a call that used it carries a
deprecation_note.
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.
“Only upgrade agents on weekends, from 10 PM for six hours, Seoul time”
The agent calls update_workspace_preferences with agent_rollout_policy={"window": {"days": [5, 6], "start_hour": 22, "length_hours": 6, "timezone": "Asia/Seoul"}}, leaving the mode unchanged.
- 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 webhook endpoints and event subscriptions