Search documentation… ⌘ K

Developer Documentation

Everything you need to deploy, manage, and scale infrastructure on Host.com — from your first server to production-grade multi-region deployments.

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:

TERMINAL
npm install -g @hostcom/cli

Alternatively, download platform-specific binaries from the Downloads page — no Node.js required.

Tip: Requires Node.js 18 or later. Run 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.

TERMINAL
host auth login # Opening https://host.com/cli/auth?token=... in your browser # Waiting for authentication... # ✓ Authenticated as [email protected] # Token saved to ~/.hostcom/config

For 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:

TERMINAL
host account info
JSON RESPONSE
{ "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):

TERMINAL
host server create \ --name web-01 \ --size cx-21 \ --region nyc \ --os ubuntu-22-04 \ --ssh-key my-laptop

The command returns immediately with a provisioning response. The server will be reachable within 45–90 seconds:

JSON RESPONSE
{ "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.

CodeLocationContinentIPv6
nycNew York, USANorth AmericaYes
laxLos Angeles, USANorth AmericaYes
dfwDallas, USANorth AmericaYes
miaMiami, USANorth AmericaYes
fraFrankfurt, GermanyEuropeYes
amsAmsterdam, NetherlandsEuropeYes
lonLondon, UKEuropeYes
stoStockholm, SwedenEuropeYes
sinSingaporeAsia-PacificYes
tyoTokyo, JapanAsia-PacificYes
sydSydney, AustraliaAsia-PacificYes
bomMumbai, IndiaAsia-PacificYes

Server Lifecycle

Every server moves through a well-defined set of states. Understanding these states is critical for handling automation correctly:

provisioning running stopped archived
  • 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.
Warning: Archived servers are unrecoverable after 7 days. Take a snapshot before deleting if you may need the data later.

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.

ScenarioBehavior
Server runs full monthBilled exactly the monthly price (hourly rate × 730 hrs)
Server created mid-monthBilled hourly from creation to end of billing period
Resize up mid-monthNew hourly rate applies from resize time; prorated on invoice
Resize down mid-monthCredit issued for unused portion at old rate
Stopped serverFull hourly rate continues (disk + IP still reserved)

REST API Reference

Base URL: 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.

HTTP HEADER
Authorization: Bearer YOUR_API_KEY Content-Type: application/json

Rate 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.

RATE LIMIT RESPONSE HEADERS
HTTP/2 429 Too Many Requests X-RateLimit-Limit: 3000 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1745244600 Retry-After: 847

Endpoints

MethodEndpointDescription
GET/serversList all servers
POST/serversCreate 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/rebootReboot a running server
POST/servers/{id}/actions/resizeResize server to new plan (requires stop)
GET/regionsList available regions
GET/sizesList available server sizes & pricing
GET/imagesList OS images and snapshots
GET/ssh-keysList SSH keys on account
POST/ssh-keysAdd an SSH key
DELETE/ssh-keys/{id}Remove an SSH key
GET/volumesList block volumes
POST/volumesCreate a block volume
POST/volumes/{id}/actions/attachAttach volume to a server

Full Example: Create a Server

A complete request-response cycle creating a server via curl:

REQUEST
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"] }'
RESPONSE — 201 Created
{ "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.

PAGINATED REQUEST
GET /servers?page=2&per_page=25
RESPONSE META
{ "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:

TERMINAL
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.pub

Add Key to Your Account

Upload the public key to Host.com so it can be injected into new servers at creation time:

TERMINAL
host ssh-key add \ --name "Laptop" \ --public-key ~/.ssh/hostcom.pub # ✓ SSH key "Laptop" added (key_7f3ab21c)

Connect to Your Server

TERMINAL
ssh -i ~/.ssh/hostcom root@198.51.100.42

For convenience, add an entry to ~/.ssh/config:

~/.ssh/config
Host web-01 HostName 198.51.100.42 User root IdentityFile ~/.ssh/hostcom IdentitiesOnly yes

Then 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:

/etc/ssh/sshd_config
# 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 inet
VNC Console Fallback: If you lose SSH access (misconfigured firewall, broken sshd config), access your server via the browser-based VNC console: Dashboard → Servers → [your server] → Console tab. This connects directly to the serial port regardless of network state.

Networking

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:

TERMINAL
# 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.10

Once 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:

TERMINAL
# 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-02

Firewall 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:

TERMINAL
# 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-01

Load Balancer

TERMINAL
# 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 2

DNS Management

TERMINAL
# 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:

  1. Go to Account → Security → Two-Factor Authentication
  2. Click Enable 2FA. A QR code is displayed.
  3. Scan the QR code with an authenticator app (Authy, Google Authenticator, 1Password).
  4. Enter the 6-digit code to confirm. Save your backup codes in a secure location — they cannot be retrieved later.
  5. 2FA is now active. CLI authentication via host auth login will prompt for the TOTP code.

API Key Scopes

ScopeHTTP Methods AllowedUse Case
readGET onlyMonitoring, dashboards, read-only CI checks
read-writeGET, POST, PATCHProvisioning servers, managing DNS, deploying
adminAll methods incl. DELETE + billingFull 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:

TERMINAL
host api-key update key-abc \ --allowed-ips 203.0.113.0/24,10.0.0.0/8
Never commit API keys to git. Use environment variables or a secrets manager. If a key is exposed, rotate it immediately from the dashboard — old keys are invalidated within 60 seconds.

DDoS Protection Tiers

TierPriceMitigation CapacityMitigation Latency
StandardIncluded100 Gbps< 30s detection & null-route
Enhanced+$10/mo per server1 Tbps< 10s scrubbing
Premium+$35/mo per server5 Tbps< 10ms always-on scrubbing

Hardened Web Server Firewall Example

TERMINAL
# 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-02

Storage & 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.

TERMINAL — Create & Attach Volume
# 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-01

After attaching, SSH into your server and format/mount the volume:

SERVER SHELL
# 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:

/etc/fstab entry
UUID=a1b2c3d4-e5f6-7890-abcd-ef1234567890 /mnt/data ext4 defaults,nofail 0 2
Tip: The nofail 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

TERMINAL
# 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 nyc

Automated Backups

Enable daily automated backups on any server. Backups are crash-consistent snapshots taken during a low-traffic window each night:

TERMINAL
host server update web-01 --backups enabled # ✓ Automated backups enabled for web-01 # Additional cost: 20% of base server price per month
Backup TypeFrequencyRetention
Daily backupsEvery 24 hours7 most recent kept
Weekly backupsEvery Sunday 02:00 UTC4 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.

TERMINAL
# 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)
Disk size can only be increased, never decreased. If you need to downsize disk, migrate to a new server from a snapshot.

Horizontal Scaling

For zero-downtime scaling, create identical servers from a snapshot and distribute traffic via a load balancer:

TERMINAL
# 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 8080

Auto-Scaling Configuration

Define auto-scaling policies as YAML. The controller monitors metrics and adds/removes servers within your defined bounds:

autoscale.yml
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: 2
TERMINAL — Apply Policy
host autoscale apply -f autoscale.yml # ✓ Auto-scaling policy "web-autoscale" applied

Monitoring & Alerts

Built-in Metrics

Every server emits metrics automatically — no agent required. Metrics are collected at 30-second resolution and retained for 30 days.

MetricUnitDescription
cpu_usagePercent (0–100)Total CPU utilization across all vCPUs
memory_usedMiBUsed RAM (includes buffers/cache)
disk_io_readKB/sDisk read throughput
disk_io_writeKB/sDisk write throughput
network_inMbpsInbound network throughput
network_outMbpsOutbound network throughput
disk_usedGiBDisk space consumed on root volume

Create Alerts

TERMINAL
# 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 email

Webhook Alert Payload

Configure a webhook URL to receive alert notifications as JSON POST requests:

WEBHOOK PAYLOAD (POST application/json)
{ "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:

TERMINAL
# 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 5432

External Integrations

Forward metrics and logs to your existing observability stack:

  • Syslog forwarding: Configure rsyslog or journald to 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 the host.com.* namespace.
  • Grafana Cloud: Use the Prometheus remote_write endpoint at https://api.host.com/v2/metrics/prometheus with your API key as Bearer token.

Troubleshooting

API Error Codes

HTTP StatusCodeCause & Resolution
400bad_requestMalformed JSON or invalid field value. Check the errors array in the response for field-level details.
401unauthorizedMissing or invalid API key. Verify your Authorization header and that the key is not revoked.
403forbiddenAPI key scope is insufficient. Upgrade key to read-write or admin as needed.
404not_foundResource ID does not exist or belongs to another account. Double-check the resource ID.
409conflictServer is not in the required state (e.g., trying to resize a running server). Check server state and retry.
422unprocessableValidation error — a required field is missing or a value is out of range. Inspect the errors field.
429rate_limitedRate limit exceeded. Wait the number of seconds in the Retry-After header before retrying.
500internal_errorUnexpected 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:

TERMINAL
# 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-rescue

VNC 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

  1. Verify the server is in running state: host server get web-01
  2. Check that port 22 is open in your firewall rules: host firewall list web-fw
  3. Confirm the correct private key: ssh -i ~/.ssh/hostcom -v root@<IP> (look for "Offering public key")
  4. Verify the key fingerprint matches what was uploaded to your account
  5. 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 running after 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 top or htop to identify the offending process.
  • Check for runaway cron jobs: crontab -l and cat /var/log/syslog | grep cron
  • If legitimate load, consider a vertical resize (cx-21cx-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.

TERMINAL
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 minutes
Pro tip: Priority levels are low, normal, high, and critical. Use critical only for production outages — it pages the on-call engineer immediately.