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:

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 Gateway
  • 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:

Alpacon Gateway

The Alpacon Gateway is the central hub that routes all connections between users and servers.

Architecture:

User (Browser/CLI) → Alpacon Gateway → Alpamon Agent → Server

Why gateway-based architecture?

Unlike traditional end-to-end encryption (like direct SSH), Alpacon’s gateway approach enables:

  • Complete audit trail: Every command and action logged for forensic analysis
  • Real-time monitoring: Security teams can monitor sessions for suspicious activity
  • Policy enforcement: Approval workflows for sensitive access, ACL-scoped tokens for automation, and AI risk analysis of commands and sessions
  • Session recording: Record sessions for compliance (SOC 2, HIPAA, PCI-DSS)
  • Centralized access control: Instant revocation across all servers

Data in transit: All data is encrypted using TLS 1.3 while flowing through the gateway.

Related documentation:

Websh protocol

Websh is Alpacon’s proprietary protocol for secure terminal sessions over WebSocket.

Protocol stack:

Terminal Data (Websh)
  ↓
WebSocket Frames (WSS)
  ↓
TLS 1.3 Encryption
  ↓
TCP/IP

Features:

  • Built on WebSocket Secure (WSS): Industry-standard transport protocol
  • Optimized for terminals: Low latency, real-time bidirectional communication
  • Browser-native: Works in any modern browser without plugins
  • Command auditing: Commands are logged and risk-scored for compliance

Related documentation:

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 read, write, or owner permissions 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

Related documentation:

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:

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 by plan:

  • Essentials plan: 1 year
  • Enterprise plan: 5 years

Use cases:

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

Related documentation:

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: Respects file system permissions and IAM access levels

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:

Multi-server commands

Run commands across one or more servers from the Alpacon CLI using a work session 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:

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)
  • SSO (Enterprise): SAML 2.0 single sign-on with your identity provider

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 or voice call
  • 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
  • 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:

API & CLI

Alpacon provides both API and CLI for programmatic access.

API tokens

API tokens enable API and CLI access:

  • Granular scopes: Per-resource read/write/owner scopes plus command and server ACL rules
  • Expiration: Choose an expiration or no expiration
  • 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:

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:

  • Default: 90 days
  • Enterprise: Up to 5 years
  • Immutable: Logs are tamper-proof and cannot be modified

Use cases:

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

Related documentation:

Next steps

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

Last updated: