Getting Started

This guide will help you set up WebXTerm and connect to your first machine.

Prerequisites

Before you begin, ensure you have:

• An active WebXTerm account
• At least one server/machine you want to connect to
• Admin access to your organization (for initial setup)

Step 1: Sign Up or Login

1. Navigate to the WebXTerm login page
2. Enter your email and password
3. Click "Sign In"

Community Edition Auth

WebXTerm Community Edition uses its own built-in JWT authentication. Your email and password are hashed with bcrypt and stored securely — no external identity provider required.

Enterprise Edition

OIDC/OAuth2 login with Microsoft, GitHub, Okta, Azure AD, and Keycloak-based authentication are available in the Enterprise Edition. Learn more.

Step 2: Get Your API Key

After signing in, navigate to your Profile page to find your API Key. You'll need this to register the WebXTerm Agent on your machines.

• Go to Profile in the top-right menu
• Copy your API Key — this is what authenticates the agent with your account

tip

If your API key is ever compromised, you can regenerate it from the Profile page. Note that regenerating it will disconnect all agents using the old key.

Step 3: Install & Register the Agent on Your Machine

WebXTerm works by installing a lightweight agent (vsay-agent) on the machine you want to access. The agent connects back to the WebXTerm backend over gRPC — no inbound firewall rules required.

Install the Agent

Download and install vsay-agent on your machine. Choose the package for your operating system and architecture:

Linux (amd64)

curl -LO https://releases.vsayterminal.com/vsay-agent/latest/vsay-agent-linux-amd64.tar.gz
tar -xzf vsay-agent-linux-amd64.tar.gz
sudo mv vsay-agent /usr/local/bin/

Or via DEB package (Debian/Ubuntu):

sudo dpkg -i vsay-agent_amd64.deb

Linux (arm64)

curl -LO https://releases.vsayterminal.com/vsay-agent/latest/vsay-agent-linux-arm64.tar.gz
tar -xzf vsay-agent-linux-arm64.tar.gz
sudo mv vsay-agent /usr/local/bin/

macOS (Intel)

curl -LO https://releases.vsayterminal.com/vsay-agent/latest/vsay-agent-darwin-amd64.tar.gz
tar -xzf vsay-agent-darwin-amd64.tar.gz
sudo mv vsay-agent /usr/local/bin/

macOS (Apple Silicon)

curl -LO https://releases.vsayterminal.com/vsay-agent/latest/vsay-agent-darwin-arm64.tar.gz
tar -xzf vsay-agent-darwin-arm64.tar.gz
sudo mv vsay-agent /usr/local/bin/

Windows

Invoke-WebRequest -Uri "https://releases.vsayterminal.com/vsay-agent/latest/vsay-agent-windows-amd64.zip" -OutFile "vsay-agent.zip"
Expand-Archive vsay-agent.zip -DestinationPath "C:\Program Files\vsay-agent\"
# Add C:\Program Files\vsay-agent\ to your PATH

Configure the Agent

Run the configure command with your API key and the WebXTerm backend URL:

sudo vsay-agent configure \
  --token YOUR_API_KEY \
  --host http://your-webxterm-instance.com:8080 \
  --linux-user ubuntu

Flag	Description
--token	Your API key from the Profile page
--host	URL of your WebXTerm backend
--linux-user	The system user that terminal sessions will run as
--allow-sudo	(Optional) Allow sudo commands in terminal sessions

This command will:

1. Save the configuration to /etc/vsay/agent.yaml
2. Install and start a systemd service (vsay-agent.service) that auto-starts on boot

Verify the Agent is Running

systemctl status vsay-agent

Once the agent starts, it registers itself with the backend and your machine will appear in the Machines dashboard within seconds.

Step 4: Connect to Your Machine

Once your machine appears in the dashboard:

1. Go to the Machines list
2. Find your machine — it should show Online status
3. Click "Connect"
4. The Web Terminal opens and you're connected directly to your machine

Step 5: Check Command History

Every command you run in a session is recorded against that machine, so you can look back at what you've done:

1. Go to the Machines list
2. Open a machine and find its Command History tab
3. See the commands you've run, in order, with timestamps

Community keeps this simple command list — it does not include full session (keystroke-by-keystroke) recording or a separate audit-log dashboard; those are Enterprise features (see below).

Next Steps

Community is intentionally minimal — sign up, add a machine, connect, and check command history. There's no team setup or roles to configure. If you outgrow that, the Enterprise Edition adds:

• Team Collaboration (RBAC) - Multi-user organizations, roles, and per-machine access grants
• Real-time Monitoring - CPU/memory/disk stats from agent heartbeats
• Audit Logs - Full activity history across logins, admin actions, and commands
• Session Recording - Full terminal I/O playback

Community vs Enterprise

Feature	Community	Enterprise
Secure Remote Access (Agent-Based)	✅	✅
Web Terminal	✅	✅
Command History	✅	✅
WebXTerm Shell CLI	✅	✅
WebXTerm VSCode Extension	✅	✅
API Access	✅	✅
TLS Encryption	✅	✅
Team Collaboration (RBAC)	❌	✅
Session Recording	❌	✅
Audit Logs	❌	✅
Real-time Monitoring	❌	✅
mTLS (Mutual TLS)	❌	✅
Keycloak Authentication	❌	✅
OIDC/OAuth2 Login (Microsoft, GitHub, Okta, Azure AD…)	❌	✅
Multi-tenancy (Organizations)	❌	✅
Organization API	❌	✅
Priority Support	❌	✅

Enterprise Edition

Need OIDC/OAuth2 login, Keycloak authentication, or multi-organization support? See the Enterprise Edition.

Learn More

See the full feature comparison on the How We Are Different page.