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 (AP1 Seoul, US1 coming soon)

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: Single command installation on any Linux server
  • 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: Block dangerous commands, require approvals, enforce security policies
  • 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: Gateway can inspect and log commands for compliance

Related documentation:

IAM (Identity and access management)

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

User roles

1. User (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 levels

Server access levels:

  1. No access: User cannot see or access the server
  2. Read-only: View server info and metrics only
  3. Terminal access: Execute commands (without sudo)
  4. Full access: Terminal with sudo, WebFTP, Deploy Shell

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

A session represents an active connection between a user and a server.

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 (Enterprise)

Session recording

All terminal sessions are recorded for security and compliance:

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:

Deploy Shell

Deploy Shell allows you to execute pre-defined deployment scripts on servers.

Key features:

  • One-click deployments: Execute complex deployment workflows with a single click
  • Script templates: Pre-configured scripts for common deployment tasks
  • Environment variables: Pass dynamic values to deployment scripts
  • Execution logs: Complete logs of deployment execution and output
  • Rollback support: Easily rollback to previous deployments

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: Traditional login with strong password requirements
  • Google sign-in: Faster authentication with Google account
  • SSO (Enterprise): SAML 2.0 and OAuth 2.0 integration with your identity provider

Multi-factor authentication (MFA)

Supported MFA methods (from most to least secure):

  1. Hardware security keys: YubiKey, Titan Key (FIDO2/WebAuthn)
  2. Biometric authentication: TouchID, FaceID, Windows Hello
  3. TOTP apps: Google Authenticator, Authy, 1Password
  4. Email-based OTP: One-time codes via email
  5. SMS-based OTP: One-time codes via SMS (backup only)
  6. Recovery codes: One-time backup codes for emergency access

MFA enforcement:

  • Workspace superusers can require MFA for all users
  • Can restrict to hardware-backed methods only (hardware keys or biometrics)
  • Step-up authentication for privileged operations (Enterprise plan)

Related documentation:

API & CLI

Alpacon provides both API and CLI for programmatic access.

Personal access tokens (PAT)

PATs enable API and CLI access:

  • Scoped permissions: Read-only, write, or admin access
  • Expiration dates: 30 days, 90 days, 1 year, or no expiration
  • Revocable: Can be revoked at any time
  • Audit trail: All API calls logged with PAT identifier

Service accounts

Service accounts (Essentials plan+) are dedicated accounts for automation:

  • Not tied to individual users
  • Specific permission scopes
  • Audit trail for service account actions
  • 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: