---
title: "Key concepts"
description: "Essential Alpacon concepts explained. Learn about workspaces, the Alpamon agent, Websh, identity management, sessions, and audit logs for secure server access."
---

> Full documentation index: https://docs.alpacax.com/llms.txt

# Key concepts

Essential concepts you need to know to understand and use Alpacon effectively.

## Workspace

A **workspace** is an isolated environment for managing your infrastructure and team.

**Key characteristics**:

- **Dedicated URL**: Each workspace has a unique subdomain (`<workspace>.<region>.alpacon.io`)
- **Complete isolation**: Data, users, and servers are completely isolated between workspaces
- **Team collaboration**: Invite team members and manage their access within the workspace
- **Regional data storage**: Choose your data region (US1 Virginia, AP1 Seoul)

**Related documentation**:

- [Workspace management](/use/workspace/)
- [Data security](/learn/security/data-security/)

## Alpamon agent

**Alpamon** is a lightweight agent that runs on your servers to establish secure connections with Alpacon.

**How it works**:

- **Agent-based architecture**: Unlike traditional SSH, servers never expose inbound ports
- **Outbound-only connections**: Agent initiates secure WebSocket (WSS) connections to Alpacon
- **Zero open ports**: Eliminates network scanning, SSH brute force, and direct server attacks
- **Automatic reconnection**: Resilient connection with exponential backoff retry logic

**Key benefits**:

- **Enhanced security**: No exposed ports means no attack surface
- **Firewall friendly**: Works behind corporate firewalls and proxies
- **Simple deployment**: Quick installation on Linux, macOS, and Windows servers
- **Lightweight**: < 20MB memory footprint

**Related documentation**:

- [Network security](/learn/security/network/)
- [Agent installation](/use/servers/register/install/)

## Central access control

Alpacon is the single place your team goes to reach servers, so access is granted, revoked, and audited in one place instead of server by server.

**What you get**:

- **One place for access**: Grant or revoke access to any server from a single console, and it takes effect everywhere at once
- **Real-time visibility**: Admins can watch active sessions live and see who is connected right now
- **Instant revocation**: Cut off access immediately across all servers, without touching each host
- **Built-in governance**: Approval for sensitive access, scoped tokens for automation, and AI risk analysis of commands and sessions
- **Session recording**: Sessions are recorded for compliance (SOC 2, HIPAA, PCI-DSS)

Every connection is encrypted with TLS.

**Related documentation**:

- [Security overview](/learn/security/)
- [Data security](/learn/security/data-security/)

## Websh

**Websh** is Alpacon's terminal in the browser: a full shell on your server with no client software or SSH keys.

**Features**:

- **No setup**: Works in any modern browser, with nothing to install and no keys to manage
- **A real terminal**: Full interactive shell with vim, colors, and special keys, low-latency and responsive
- **Recorded for audit**: Sessions can be recorded, and commands are risk-scored for compliance
- **MFA-gated**: Access can require multi-factor authentication, with step-up verification for privileged actions

**Related documentation**:

- [Network security](/learn/security/network/)
- [Using Websh](/use/work-sessions/terminal/)

## IAM (Identity and access management)

Alpacon uses **role-based access control (RBAC)** to manage user permissions.

### User roles

**1. Member (regular user)**

- Access only to assigned servers
- Cannot modify workspace settings or invite users
- Can create terminal sessions and use assigned features

**2. Staff**

- Administrative privileges for day-to-day operations
- Can manage servers, invite users, configure user groups
- Can view audit logs
- Cannot modify billing or delete workspace

**3. Superuser**

- Full administrative access
- Can modify all workspace settings and security policies
- Can manage billing and subscriptions
- Can delete workspace

### User groups

**User groups** allow efficient permission management:

- Assign permissions to multiple users at once
- Organize users by team, department, or role
- Dynamic access control (add user to group → instant access)
- Support for wildcard server matching (`production-*`, `web-*`)

### Access control

Access is granted in two layers:

1. **RBAC roles and object scopes**: Roles grant `resource:action` permissions (for example `server:read`, `server:update`) on specific resources (servers, groups), assigned directly or through groups
2. **Work session scopes**: To use a server, you request a time-bound work session scoped to specific actions—Web terminal, File transfer, Execute commands, Code editor, Port forwarding, and Privilege elevation

On Windows servers, the code editor is not available, and port forwarding needs Alpamon 2.5.1 or later. See [Windows servers](/reference/platforms/windows/).

**Related documentation**:

- [Authentication & access control](/learn/security/authentication/)
- [IAM management](/use/iam/)
- [User groups](/use/iam/groups/)

## Servers

**Servers** are the infrastructure resources you manage through Alpacon.

**Server registration**:

1. Install Alpamon agent on your server
2. Agent connects to Alpacon and registers the server
3. Server appears in your workspace immediately

**Server metadata**:

- **Name**: Custom server name (e.g., `web-01`, `db-prod`)
- **Platform**: Detected OS and version (Ubuntu, CentOS, etc.)
- **Groups**: Organize servers by purpose, environment, or team
- **Tags**: Additional metadata for filtering and organization
- **Status**: Online/offline state and health metrics

**Server groups**:

Organize servers into logical groups:

- **By environment**: `production`, `staging`, `development`
- **By function**: `web`, `database`, `cache`, `worker`
- **By team**: `backend`, `frontend`, `devops`, `data`

**Related documentation**:

- [Server management](/use/servers/)
- [Connect a server](/use/servers/connect/)

## Sessions

Alpacon distinguishes two related ideas:

- A **work session** is the approved, time-bound grant of access to a server—you request it, it's scoped to specific actions, and it expires automatically.
- A **terminal session** (Websh) is a connection you open and use within a work session.

### Terminal sessions

**Terminal sessions** provide command-line access to servers:

- **Web-based**: Access from any browser without SSH client
- **Multiple concurrent sessions**: Open multiple terminals simultaneously
- **Session persistence**: Sessions survive network disconnections
- **Session sharing**: Share terminal sessions with team members (Essentials plan and above)

### Session recording

**Websh sessions can be recorded** on paid plans for security and compliance (tunnel and code-editor sessions are not recorded):

**Retention**: Recordings are retained according to your plan. See the [pricing page](https://www.alpacax.com/alpacon/pricing) for retention windows.

**Use cases**:

- Compliance auditing (SOC 2, HIPAA, PCI-DSS)
- Security forensics and incident investigation
- Training and knowledge sharing
- Troubleshooting and debugging

**Related documentation**:

- [Using Websh](/use/work-sessions/terminal/)
- [Session management](/use/work-sessions/terminal/sessions/)
- [Data security](/learn/security/data-security/)

## WebFTP

**WebFTP** provides browser-based file transfer to your servers.

**Features**:

- **Drag-and-drop upload**: Upload files directly from your browser
- **Directory browsing**: Navigate server filesystem visually
- **Download files**: Download files and folders from servers
- **Permission-aware**: On Linux and macOS, respects file system permissions and IAM access levels. On Windows, the agent runs as SYSTEM with no home-directory boundary, so access is governed by Alpacon roles and the users allowed to connect

**Access control**:

- Requires **full access** permission to server
- Can be restricted by user role and group
- All file operations are logged in audit trail

**Related documentation**:

- [Using WebFTP](/use/work-sessions/files/)

## Multi-server commands

Run commands across one or more servers from the [Alpacon CLI](/reference/cli/) using a [work session](/use/work-sessions/) with the **Execute commands** feature—useful for deployments, maintenance, and batch operations.

**Use cases**:

- Application deployments
- Database migrations
- Service restarts
- Configuration updates
- Backup operations

**Related documentation**:

- [Session features](/reference/work-session-features/)
- [`alpacon exec` reference](/reference/cli/exec/)

## Authentication & MFA

Alpacon uses **Auth0 by Okta** for authentication, providing enterprise-grade security.

### Authentication methods

**Primary authentication**:

- **Email & password**: Login managed through Auth0 (Alpacon Cloud)
- **Single sign-on**: Google Workspace through Auth0; Enterprise workspaces can integrate Okta (Okta Integration Network) or a SAML IdP arranged during onboarding

### Multi-factor authentication (MFA)

**Supported MFA methods**:

- **Hardware security key**: WebAuthn-compatible keys such as YubiKey
- **Biometric authentication (FaceID, Fingerprint)**: Your device's built-in biometric sensor
- **One-time password**: Authenticator apps such as Google Authenticator
- **Email**: One-time codes via email
- **Phone**: One-time codes via SMS
- **Recovery code**: One-time backup codes for emergency access

**MFA enforcement**:

- Workspace admins can enforce MFA at login ("MFA enforced") and choose the allowed MFA methods
- Whether a passkey sign-in counts as MFA follows the allowed methods: see [Passkeys and allowed MFA methods](/use/workspace/settings/#passkeys-and-allowed-mfa-methods)
- Step-up MFA can be required for privileged actions (for example, running as a system account or root) through the "Require MFA for" settings

**Related documentation**:

- [Authentication & access control](/learn/security/authentication/)
- [Security FAQ](/learn/security/faq/)

## API & CLI

Alpacon provides both **API** and **CLI** for programmatic access.

### API tokens

**API tokens** enable API and CLI access:

- **Granular scopes**: Per-resource `resource:action` scopes such as `server:read` and `server:update`, plus command and server ACL rules
- **Expiration**: Every new token expires, no later than the workspace's maximum token lifetime
- **Revocable**: Can be revoked at any time
- **Activity log**: API calls are recorded per token

### Applications and service tokens

**Applications** are non-human identities for automation. Each application issues **service tokens** that inherit its permissions:

- Not tied to individual users
- Permissions defined by the application's role and scopes
- Activity logged per token
- Ideal for CI/CD pipelines and integrations

**Related documentation**:

- [API reference](/reference/api/)
- [CLI reference](/reference/cli/)

## Audit logs

**Audit logs** provide a complete trail of all activities in your workspace.

**Logged events**:

- **Authentication**: Login/logout, MFA verification, password changes
- **Authorization**: Permission changes, role assignments, access denials
- **Resource access**: Server connections, terminal sessions, file operations
- **Configuration**: Workspace settings, security policy changes

**Log retention**:

- Audit logs are retained according to your plan. See the [pricing page](https://www.alpacax.com/alpacon/pricing) for retention windows.
- Workspace members can't edit or delete audit records.

**Use cases**:

- Security monitoring and threat detection
- Compliance auditing (SOC 2, HIPAA, PCI-DSS)
- Forensic investigation
- User activity tracking

**Related documentation**:

- [Audit logging](/learn/security/authentication/#audit-logging)
- [Viewing command history](/use/audit/events/commands/)

---

## Next steps

Now that you understand the key concepts, explore these guides:

- [Quickstart guide](/learn/quickstart/) - Get started with Alpacon in 5 minutes
- [Security overview](/learn/security/) - Understand Alpacon's security architecture
- [Infrastructure setup](/use/servers/configure-network/) - Understand how to setup infrastructure for Alpacon
- [IAM setup](/use/iam/) - Configure user access and permissions

Source: https://docs.alpacax.com/learn/key-concepts/