Getting Started
Welcome to the Host.com developer documentation. This guide covers everything from installing the CLI to deploying your first production server. You'll need a Host.com account — if you don't have one, sign up free in under two minutes.
Install the CLI
The host CLI is the fastest way to manage your infrastructure. Install it globally via npm:
npm install -g @hostcom/cliAlternatively, download platform-specific binaries from the Downloads page — no Node.js required.
node --version to check. We recommend using Volta or nvm to manage Node versions.Authenticate
After installation, authenticate the CLI with your Host.com account. This opens a browser window for OAuth, then stores a token securely at ~/.hostcom/config.
host auth login
# Opening https://host.com/cli/auth?token=... in your browser
# Waiting for authentication...
# ✓ Authenticated as [email protected]
# Token saved to ~/.hostcom/configFor non-interactive environments (CI/CD pipelines), set the HOSTCOM_API_KEY environment variable instead of using browser-based auth. The CLI will pick it up automatically.
Verify Your Setup
Confirm the CLI is authenticated and your account details are correct:
host account info{
"id": "usr_4j2kx9mf",
"email": "[email protected]",
"name": "Alex Chen",
"plan": "pro",
"balance_usd": 42.50,
"monthly_limit_usd": 500.00,
"2fa_enabled": true,
"created_at": "2024-03-15T09:12:00Z"
}Deploy Your First Server
Create a server with a single command. The --ssh-key flag references a key already added to your account (see SSH & Server Access):
host server create \
--name web-01 \
--size cx-21 \
--region nyc \
--os ubuntu-22-04 \
--ssh-key my-laptopThe command returns immediately with a provisioning response. The server will be reachable within 45–90 seconds:
{
"id": "srv_8x2nqprt",
"name": "web-01",
"status": "provisioning",
"ip_address": "198.51.100.42",
"region": "nyc",
"size": "cx-21",
"vcpus": 2,
"memory_mb": 4096,
"disk_gb": 80,
"os": "ubuntu-22-04",
"created_at": "2026-04-21T14:30:00Z"
}Poll status with host server get web-01 until status reads running, then SSH in using the returned IP address.
Core Concepts
Understanding Host.com's resource model, regions, and server lifecycle will help you architect reliable, cost-efficient deployments.
Regions
Choose the region closest to your users to minimize latency. All regions support the full feature set unless noted.
| Code | Location | Continent | IPv6 |
|---|---|---|---|
nyc | New York, USA | North America | Yes |
lax | Los Angeles, USA | North America | Yes |
dfw | Dallas, USA | North America | Yes |
mia | Miami, USA | North America | Yes |
fra | Frankfurt, Germany | Europe | Yes |
ams | Amsterdam, Netherlands | Europe | Yes |
lon | London, UK | Europe | Yes |
sto | Stockholm, Sweden | Europe | Yes |
sin | Singapore | Asia-Pacific | Yes |
tyo | Tokyo, Japan | Asia-Pacific | Yes |
syd | Sydney, Australia | Asia-Pacific | Yes |
bom | Mumbai, India | Asia-Pacific | Yes |
Server Lifecycle
Every server moves through a well-defined set of states. Understanding these states is critical for handling automation correctly:
- provisioning — Server is being allocated and the OS is being installed. Typically 45–90 seconds. No actions available.
- running — Server is live. Can be rebooted, resized (with downtime), snapshotted, or stopped.
- stopped — Server is powered off. Disk is preserved; IP address is held. You are still billed for disk and IP reservation.
- archived — Entered after explicit deletion. All data is permanently destroyed after 7 days. Billing stops immediately.
Resource Model
Each server plan is defined by four resources:
- vCPU — Dedicated virtual CPU cores (AMD EPYC or Intel Xeon, depending on region). No sharing — your cores are yours.
- RAM — ECC DDR5 memory allocated exclusively to your server instance.
- NVMe Storage — Local NVMe SSD. Fast sequential and random I/O. Not replicated — use block volumes or snapshots for durability.
- Bandwidth Pool — Monthly outbound transfer allowance. Inbound is always free. Overages billed at $0.01/GB. Unused bandwidth does not roll over.
Billing Model
Host.com uses an hourly accrual model. The monthly price shown is a cap — you never pay more than that in a calendar month, regardless of how many hours a server runs.
| Scenario | Behavior |
|---|---|
| Server runs full month | Billed exactly the monthly price (hourly rate × 730 hrs) |
| Server created mid-month | Billed hourly from creation to end of billing period |
| Resize up mid-month | New hourly rate applies from resize time; prorated on invoice |
| Resize down mid-month | Credit issued for unused portion at old rate |
| Stopped server | Full hourly rate continues (disk + IP still reserved) |
REST API Reference
https://api.host.com/v2 — All requests must be made over HTTPS. The API follows REST conventions and returns JSON for all responses including errors.Authentication
Every API request must include a Bearer token in the Authorization header. Generate API keys in your dashboard under Account → API Keys.
Authorization: Bearer YOUR_API_KEY
Content-Type: application/jsonRate Limits
The API enforces a limit of 3,000 requests per hour per API key, measured in a rolling window. When exceeded, the API returns HTTP 429 with a Retry-After header indicating how many seconds to wait before retrying.
HTTP/2 429 Too Many Requests
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1745244600
Retry-After: 847Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /servers | List all servers |
| POST | /servers | Create a new server |
| GET | /servers/{id} | Get a single server |
| PATCH | /servers/{id} | Update server metadata (name, tags) |
| DELETE | /servers/{id} | Delete (archive) a server |
| POST | /servers/{id}/actions/reboot | Reboot a running server |
| POST | /servers/{id}/actions/resize | Resize server to new plan (requires stop) |
| GET | /regions | List available regions |
| GET | /sizes | List available server sizes & pricing |
| GET | /images | List OS images and snapshots |
| GET | /ssh-keys | List SSH keys on account |
| POST | /ssh-keys | Add an SSH key |
| DELETE | /ssh-keys/{id} | Remove an SSH key |
| GET | /volumes | List block volumes |
| POST | /volumes | Create a block volume |
| POST | /volumes/{id}/actions/attach | Attach volume to a server |
Full Example: Create a Server
A complete request-response cycle creating a server via curl:
curl -X POST https://api.host.com/v2/servers \
-H "Authorization: Bearer hk_live_aBcDeFgHiJkLmN0pQrStUvWxYz" \
-H "Content-Type: application/json" \
-d '{
"name": "web-01",
"size": "cx-21",
"region": "nyc",
"image": "ubuntu-22-04",
"ssh_keys": ["key_7f3ab21c"],
"tags": ["production", "web"]
}'{
"server": {
"id": "srv_8x2nqprt",
"name": "web-01",
"status": "provisioning",
"ip_address": "198.51.100.42",
"ipv6_address": "2001:db8:85a3::42",
"region": "nyc",
"size": "cx-21",
"vcpus": 2,
"memory_mb": 4096,
"disk_gb": 80,
"bandwidth_gb": 3000,
"tags": ["production", "web"],
"created_at": "2026-04-21T14:30:00Z"
}
}Pagination
List endpoints return paginated results. Use the page and per_page query parameters to navigate. Default page size is 25; maximum is 200.
GET /servers?page=2&per_page=25{
"servers": [ /* … */ ],
"meta": {
"total": 83,
"page": 2,
"per_page": 25,
"pages": 4
}
}SSH & Server Access
SSH key-based authentication is the recommended way to access your servers. Password authentication is disabled by default on all Host.com servers.
Generate an SSH Key Pair
We recommend Ed25519 keys for their security and performance. Run the following to generate a dedicated key pair for Host.com:
ssh-keygen -t ed25519 -C "[email protected]" -f ~/.ssh/hostcom
# Generating public/private ed25519 key pair.
# Enter passphrase (empty for no passphrase): ••••••••
# Your identification has been saved in /home/user/.ssh/hostcom
# Your public key has been saved in /home/user/.ssh/hostcom.pubAdd Key to Your Account
Upload the public key to Host.com so it can be injected into new servers at creation time:
host ssh-key add \
--name "Laptop" \
--public-key ~/.ssh/hostcom.pub
# ✓ SSH key "Laptop" added (key_7f3ab21c)Connect to Your Server
ssh -i ~/.ssh/hostcom root@198.51.100.42For convenience, add an entry to ~/.ssh/config:
Host web-01
HostName 198.51.100.42
User root
IdentityFile ~/.ssh/hostcom
IdentitiesOnly yesThen simply run ssh web-01.
Recommended sshd_config Hardening
Apply these settings on fresh servers to reduce attack surface. Edit /etc/ssh/sshd_config and reload with systemctl reload sshd:
# Disable password auth — keys only
PasswordAuthentication no
ChallengeResponseAuthentication no
# Allow root login with a key but not password
PermitRootLogin prohibit-password
# Reduce brute-force window
MaxAuthTries 3
LoginGraceTime 20s
# Keep idle sessions alive (avoid NAT timeouts)
ClientAliveInterval 300
ClientAliveCountMax 2
# Restrict to IPv4 if IPv6 not needed
AddressFamily inetNetworking
Host.com provides software-defined networking: private VPCs for internal traffic, floating IPs for failover, hardware firewalls, load balancers, and managed DNS — all configurable via CLI or API.
Private VPC
Create an isolated private network for inter-server communication without exposing traffic to the public internet:
# Create the VPC
host network create \
--name prod-vpc \
--cidr 10.0.0.0/16 \
--region nyc
# ✓ Network "prod-vpc" created (net_3fa1c7b2)
# Attach an existing server to the VPC
host network attach \
--network prod-vpc \
--server web-01 \
--ip 10.0.1.10Once attached, servers communicate over the private interface (eth1 on Ubuntu) using their private IPs — free of charge, with no bandwidth counting against your pool.
Floating IPs
A floating IP is a static public IP you can reassign between servers in milliseconds — ideal for zero-downtime failover:
# Reserve a floating IP
host floating-ip create --region nyc
# ✓ Floating IP 203.0.113.100 reserved (fip_9c4de1f0)
# Assign to a server
host floating-ip assign fip_9c4de1f0 --server web-01
# Reassign to another server (failover)
host floating-ip assign fip_9c4de1f0 --server web-02Firewall Rules
Host.com firewalls are enforced at the hypervisor level — they block traffic before it reaches your server's NIC, protecting against malformed packets and volumetric attacks:
# Create a firewall group
host firewall create --name web-fw
# Allow HTTP and HTTPS from anywhere
host firewall rule add web-fw \
--direction inbound --proto tcp \
--port 80,443 --source 0.0.0.0/0
# Allow SSH only from your office CIDR
host firewall rule add web-fw \
--direction inbound --proto tcp \
--port 22 --source 203.0.113.0/24
# Apply the firewall group to a server
host firewall apply web-fw --server web-01Load Balancer
# Create a load balancer
host lb create \
--name prod-lb \
--region nyc \
--algorithm round-robin
# Add backend targets on port 8080
host lb target add prod-lb \
--server web-01 --port 8080
host lb target add prod-lb \
--server web-02 --port 8080
# Configure health check
host lb health-check prod-lb \
--path /health \
--interval 10 \
--timeout 3 \
--unhealthy-threshold 2DNS Management
# Create an A record pointing the apex to your server
host dns record create \
--zone example.com \
--type A \
--name @ \
--value 198.51.100.42 \
--ttl 300
# Create a CNAME for www
host dns record create \
--zone example.com \
--type CNAME \
--name www \
--value example.com.Security
Two-Factor Authentication
Enable TOTP-based 2FA on your account to require a one-time code on every login:
- Go to Account → Security → Two-Factor Authentication
- Click Enable 2FA. A QR code is displayed.
- Scan the QR code with an authenticator app (Authy, Google Authenticator, 1Password).
- Enter the 6-digit code to confirm. Save your backup codes in a secure location — they cannot be retrieved later.
- 2FA is now active. CLI authentication via
host auth loginwill prompt for the TOTP code.
API Key Scopes
| Scope | HTTP Methods Allowed | Use Case |
|---|---|---|
read | GET only | Monitoring, dashboards, read-only CI checks |
read-write | GET, POST, PATCH | Provisioning servers, managing DNS, deploying |
admin | All methods incl. DELETE + billing | Full account automation, Terraform, billing integrations |
IP Allowlisting
Restrict an API key to only accept requests from specific CIDR ranges — ideal for locking CI/CD runners to known IPs:
host api-key update key-abc \
--allowed-ips 203.0.113.0/24,10.0.0.0/8DDoS Protection Tiers
| Tier | Price | Mitigation Capacity | Mitigation Latency |
|---|---|---|---|
| Standard | Included | 100 Gbps | < 30s detection & null-route |
| Enhanced | +$10/mo per server | 1 Tbps | < 10s scrubbing |
| Premium | +$35/mo per server | 5 Tbps | < 10ms always-on scrubbing |
Hardened Web Server Firewall Example
# Allow public web traffic
host firewall rule add web-fw --direction inbound --proto tcp --port 80,443 --source 0.0.0.0/0
# Allow SSH only from the bastion host
host firewall rule add web-fw --direction inbound --proto tcp --port 22 --source 10.0.0.5/32
# Deny everything else inbound (implicit deny is default)
# Outbound is unrestricted by default
host firewall apply web-fw --server web-01 --server web-02Storage & Backups
Block Volumes
Block volumes are persistent NVMe SSDs that exist independently of any server. They survive server deletion and can be moved between servers in the same region.
# Create a 100 GB block volume
host volume create \
--name data-vol \
--size 100 \
--region nyc
# ✓ Volume "data-vol" created (vol_5e8af3c1)
# Attach to a server (appears as /dev/sdb)
host volume attach vol_5e8af3c1 --server web-01After attaching, SSH into your server and format/mount the volume:
# Format with ext4 (first time only — destroys existing data)
mkfs.ext4 /dev/sdb
# Create mount point and mount
mkdir -p /mnt/data
mount /dev/sdb /mnt/data
# Get UUID for fstab (survives device renaming)
blkid /dev/sdb
# /dev/sdb: UUID="a1b2c3d4-..." TYPE="ext4"Add to /etc/fstab for automatic remount on reboot:
UUID=a1b2c3d4-e5f6-7890-abcd-ef1234567890 /mnt/data ext4 defaults,nofail 0 2nofail fstab option prevents boot failures if the volume is temporarily detached. Always use it on cloud volumes.Object Storage
For unstructured files, static assets, backups, and logs at scale, use Host.com Object Storage — S3-compatible, 99.999999999% durability, no egress fees within our CDN network. See the Object Storage documentation for setup, SDK integration, and bucket policies.
Snapshots
# Create a snapshot of a server (server can be running)
host snapshot create --server web-01 --name pre-deploy-2026-04-21
# List snapshots
host snapshot list
# Restore: create a new server from snapshot
host server create \
--name web-01-restored \
--image snap_7b3ef19a \
--size cx-21 \
--region nycAutomated Backups
Enable daily automated backups on any server. Backups are crash-consistent snapshots taken during a low-traffic window each night:
host server update web-01 --backups enabled
# ✓ Automated backups enabled for web-01
# Additional cost: 20% of base server price per month| Backup Type | Frequency | Retention |
|---|---|---|
| Daily backups | Every 24 hours | 7 most recent kept |
| Weekly backups | Every Sunday 02:00 UTC | 4 most recent kept |
Scaling
Vertical Scaling (Resize)
Increase CPU and RAM by resizing to a larger plan. A resize requires a brief reboot (~60 seconds of downtime). The server's IP address, disk contents, and configuration are preserved.
# Stop the server first (resize requires stopped state)
host server stop web-01
# Resize from cx-21 (2 vCPU / 4 GB) to cx-41 (4 vCPU / 8 GB)
host server resize --server web-01 --size cx-41
# Start the server again
host server start web-01
# ✓ Server web-01 resized to cx-41 and started (~60s)Horizontal Scaling
For zero-downtime scaling, create identical servers from a snapshot and distribute traffic via a load balancer:
# 1. Take a snapshot of the current production server
host snapshot create --server web-01 --name web-golden
# 2. Create identical server from snapshot
host server create \
--name web-02 \
--image snap_web-golden \
--size cx-21 \
--region nyc
# 3. Add new server to existing load balancer
host lb target add prod-lb --server web-02 --port 8080Auto-Scaling Configuration
Define auto-scaling policies as YAML. The controller monitors metrics and adds/removes servers within your defined bounds:
name: web-autoscale
load_balancer: prod-lb
template:
image: snap_web-golden
size: cx-21
region: nyc
ssh_keys: [key_7f3ab21c]
scaling:
min: 2
max: 10
cpu_threshold: 75 # scale up when avg CPU > 75%
scale_down_threshold: 30 # scale down when avg CPU < 30%
cooldown_seconds: 300 # wait 5 min between scaling events
warmup_seconds: 60 # time for new instance to become healthy
health_check:
path: /health
interval: 10
timeout: 3
threshold: 2host autoscale apply -f autoscale.yml
# ✓ Auto-scaling policy "web-autoscale" appliedMonitoring & Alerts
Built-in Metrics
Every server emits metrics automatically — no agent required. Metrics are collected at 30-second resolution and retained for 30 days.
| Metric | Unit | Description |
|---|---|---|
cpu_usage | Percent (0–100) | Total CPU utilization across all vCPUs |
memory_used | MiB | Used RAM (includes buffers/cache) |
disk_io_read | KB/s | Disk read throughput |
disk_io_write | KB/s | Disk write throughput |
network_in | Mbps | Inbound network throughput |
network_out | Mbps | Outbound network throughput |
disk_used | GiB | Disk space consumed on root volume |
Create Alerts
# Alert when CPU exceeds 80% for 5 minutes
host alert create \
--server web-01 \
--metric cpu_usage \
--threshold 80 \
--duration 5m \
--notify email,slack
# Alert when disk usage exceeds 85%
host alert create \
--server web-01 \
--metric disk_used_pct \
--threshold 85 \
--notify emailWebhook Alert Payload
Configure a webhook URL to receive alert notifications as JSON POST requests:
{
"event": "alert.triggered",
"alert_id": "alr_2c9fe8b1",
"server_id": "srv_8x2nqprt",
"server_name":"web-01",
"metric": "cpu_usage",
"value": 87.4,
"threshold": 80,
"state": "firing",
"region": "nyc",
"timestamp": "2026-04-21T14:32:00Z",
"dashboard_url": "https://host.com/dashboard/servers/srv_8x2nqprt"
}Uptime Checks
Uptime checks probe your endpoints from 5 global nodes every 30 seconds. An alert fires after 2 consecutive failures (i.e., 60 seconds of confirmed outage) to reduce false positives:
# HTTP check
host uptime create \
--name prod-web \
--type http \
--url https://example.com/health \
--expect 200 \
--notify email,slack
# TCP port check (e.g. database port)
host uptime create \
--name db-port \
--type tcp \
--host 10.0.1.20 \
--port 5432External Integrations
Forward metrics and logs to your existing observability stack:
- Syslog forwarding: Configure
rsyslogorjournaldto forward to your SIEM. Use the server's private VPC IP for zero-cost log shipping. - Datadog: Install the Datadog agent and set
DD_API_KEY. Host.com metrics appear automatically under thehost.com.*namespace. - Grafana Cloud: Use the Prometheus remote_write endpoint at
https://api.host.com/v2/metrics/prometheuswith your API key as Bearer token.
Troubleshooting
API Error Codes
| HTTP Status | Code | Cause & Resolution |
|---|---|---|
400 | bad_request | Malformed JSON or invalid field value. Check the errors array in the response for field-level details. |
401 | unauthorized | Missing or invalid API key. Verify your Authorization header and that the key is not revoked. |
403 | forbidden | API key scope is insufficient. Upgrade key to read-write or admin as needed. |
404 | not_found | Resource ID does not exist or belongs to another account. Double-check the resource ID. |
409 | conflict | Server is not in the required state (e.g., trying to resize a running server). Check server state and retry. |
422 | unprocessable | Validation error — a required field is missing or a value is out of range. Inspect the errors field. |
429 | rate_limited | Rate limit exceeded. Wait the number of seconds in the Retry-After header before retrying. |
500 | internal_error | Unexpected server error. Retry with exponential backoff. If it persists, open a support ticket with the request_id from the response. |
Rescue Mode
If your server is unbootable due to a misconfigured bootloader, corrupted filesystem, or bad kernel parameter, boot into rescue mode — a minimal recovery OS that mounts your disk at /mnt/rescue:
# Enable rescue mode (reboots into recovery OS)
host server action --server web-01 --action enable-rescue
# ✓ Server is booting into rescue mode…
# Access via VNC console or SSH (temporary password shown in dashboard)
# After fixing the issue, exit rescue mode
host server action --server web-01 --action disable-rescueVNC Console
Access your server's virtual console directly from the browser — no SSH needed, no network configuration required. Navigate to Dashboard → Servers → [server name] → Console tab. The console connects to the serial port and shows output from boot-time through to the login prompt. Useful for diagnosing fsck failures, kernel panics, and misconfigured network interfaces.
Common Issues
Can't SSH into server
- Verify the server is in
runningstate:host server get web-01 - Check that port 22 is open in your firewall rules:
host firewall list web-fw - Confirm the correct private key:
ssh -i ~/.ssh/hostcom -v root@<IP>(look for "Offering public key") - Verify the key fingerprint matches what was uploaded to your account
- If firewall and key are correct, use VNC console to check sshd status:
systemctl status sshd
Server stuck in "provisioning" state
- Provisioning normally completes within 45–90 seconds.
- If the server has not transitioned to
runningafter 10 minutes, contact support and include the server ID. - Do not delete and recreate repeatedly — open a ticket so the engineering team can investigate the underlying host.
High CPU usage
- SSH in and run
toporhtopto identify the offending process. - Check for runaway cron jobs:
crontab -landcat /var/log/syslog | grep cron - If legitimate load, consider a vertical resize (
cx-21→cx-41) or adding a second server behind the load balancer. - Enable CPU alerts to get notified proactively:
host alert create --server web-01 --metric cpu_usage --threshold 80
Open a Support Ticket
For issues that can't be resolved with the documentation, open a support ticket directly from the CLI. Include as much context as possible — server ID, timestamps, and error messages reduce response time significantly.
host support ticket create \
--server web-01 \
--priority high \
--message "Server stuck in provisioning since 14:30 UTC.
Request ID from API: req_abc123. No SSH access."
# ✓ Ticket #48291 created — median response time: 8 minuteslow, normal, high, and critical. Use critical only for production outages — it pages the on-call engineer immediately.