1Make an API key
- In the console, open Security and make an API key. Choose Read and write if the tools should change anything.
- To run commands on servers with
eh servers exec, also turn on Run commands for the key.
- Copy the key (it starts with
ehk_). It's shown once.
A key acts as you, with your role. Keep it out of files you share. You can limit a key to some servers, and you can revoke it on the same page at any time.
2Get the tools
The eh command is one file with nothing else to install, for Linux (x64 and Arm), macOS (Apple silicon and Intel, signed and notarized by Apple) and Windows. On Linux or a Mac, this downloads the right one, checks it and installs it:
$ curl -fsSL https://entityhosting.net/downloads/eh/install.sh | sh
On Windows, or to download by hand, take the file for your system below and compare it with SHA256SUMS:
The Terraform provider needs no download: Terraform 1.0 or later fetches it from entityhosting.net on terraform init and checks its signature.
3Use the eh command
Sign in once. The key is kept in a file only you can read. You can also set EH_API_KEY instead, which is handy in scripts.
$ eh login
$ eh whoami
See what you can order, then build a server and wait until it's ready:
$ eh plans --location us-ca-1
$ eh ssh-keys add ~/.ssh/id_ed25519.pub --name laptop
$ eh servers create --plan vps-kvm-2 --location us-ca-1 \
--hostname web1.example.com --os debian-12 --ssh-key laptop --wait
A server can be named by its hostname or its id. A few things you can do with it:
$ eh servers list
$ eh servers ssh web1.example.com
$ eh servers exec web1.example.com -- uptime
$ eh firewall add-rule web1.example.com --protocol tcp --port 22 --source 203.0.113.0/24
$ eh firewall enable web1.example.com
$ eh snapshots create web1.example.com --description "before the upgrade" --wait
$ eh servers resize web1.example.com --plan vps-kvm-4 --wait
$ eh apps install web1.example.com n8n --wait
$ eh apps password web1.example.com
$ eh databases create --name app-db --engine postgresql --size db-1 --location us-ca-1
$ eh databases allow app-db --server web1.example.com
- Add
--json to any command to get the answer as JSON for scripts.
--wait waits until a build, resize, reinstall or snapshot has finished.
- Anything that erases data asks first. In a script, add
--yes; without it, nothing is changed.
eh servers exec exits with the command's own exit code, so it works in scripts and CI.
eh help lists every command: servers, snapshots, firewall rules and groups, private networks, extra and reserved IPv4 addresses, load balancers, gateways, databases, DNS, BGP, alerts, snapshot and power schedules, domains, SSH keys and invoices.
4Use Terraform
Set the key in your environment, then describe what you want:
$ export EH_API_KEY=ehk_...
terraform {
required_providers {
entityhosting = { source = "entityhosting.net/entitysolutions/entityhosting" }
}
}
resource "entityhosting_ssh_key" "laptop" {
name = "laptop"
public_key = file("~/.ssh/id_ed25519.pub")
}
resource "entityhosting_server" "web" {
hostname = "web1.example.com"
plan = "vps-kvm-2"
location = "us-ca-1"
os = "debian-12"
ssh_key = entityhosting_ssh_key.laptop.public_key
}
resource "entityhosting_firewall" "web" {
server_id = entityhosting_server.web.id
rule {
protocol = "tcp"
port = "22"
source = "203.0.113.0/24"
}
rule {
protocol = "tcp"
port = "443"
}
}
output "ip" { value = entityhosting_server.web.ipv4_address }
resource "entityhosting_app" "web" {
server_id = entityhosting_server.web.id
app = "wordpress"
keep_updated = true
}
output "site" { value = entityhosting_app.web.site_url }
$ terraform init
$ terraform apply
terraform apply orders the server and waits until it's built and ready. What each change does:
- A bigger plan resizes the server in place. It restarts, about a minute offline. Disks can't shrink, so a smaller plan is refused when you run
terraform plan, before anything happens.
- A new hostname or tags change in place.
- A new location, operating system, SSH key or startup script builds a new server and deletes the old one. Terraform shows this as "must be replaced" in the plan.
The app is on HTTPS at the server's free hostname (entityhosting_server.web.public_hostname) unless you set domain. Its first admin password is in entityhosting_app.web.initial_password (sensitive). Changing app erases the server and installs the new one, so Terraform only does it with allow_erase = true.
There are also entityhosting_private_network and entityhosting_private_network_member for private networks, entityhosting_load_balancer for load balancers, and data sources for plans, locations and operating systems: entityhosting_plans, entityhosting_locations and entityhosting_os_images.
Plan names, locations and operating systems are checked against what we offer when you run terraform plan, so a typo shows up before an order is placed.
5Bring in servers you already have
Every resource can be imported by its id, which the console and eh servers list show:
$ terraform import entityhosting_server.web 3f0c...
$ terraform import entityhosting_firewall.web 3f0c...
The SSH key and startup script a server was built with can't be read back. After importing, add them to ignore_changes in a lifecycle block so Terraform doesn't rebuild the server to set them.
6Billing and deleting
Servers made with the eh command or Terraform are billed by the hour unless you choose monthly, and terraform destroy or eh servers delete stops the charges. A monthly server runs to the end of the term you've paid for, so the API won't delete it: cancel it with POST /services/{id}/cancel and it ends when that term does (POST /services/{id}/keep undoes it).
Deleting a server erases it and everything on it for good. Take a snapshot or a backup first if you might need anything on it.