# Computers **Page:** concepts/computers [Download Raw Markdown](./concepts/computers.md) --- # Computers A Hoody computer is a full Debian 13 Linux machine with systemd, its own filesystem, its own network stack and its own process tree. It boots, runs services and keeps its state, and it can hold terminals, desktops, databases and browsers. It is a machine you work in, operated over HTTP. A computer runs on a server: flat-rate bare metal rented from the marketplace, which is hardware you control, a paid subserver, or a shared free-tier server to start. Each of its services is a URL reachable from any network. Until the computer or its project sets [proxy permissions](/foundation/proxy/permissions/#open-by-default), anyone who has a URL can open it: before sharing anything sensitive, set them to require a password, token or sign-in. ## What does a computer include? | Part | What you get | | :--- | :--- | | **Operating system** | Debian 13 (Trixie) with the full `apt` package manager | | **Init** | systemd: service management, not a single entrypoint process | | **Filesystem** | Its own, persistent and writable, with the full Linux directory layout (FHS) | | **Network** | Its own network stack: own IP, own DNS, own routing table | | **Processes** | Its own process tree | | **Hoody Kit** | With the Kit enabled, the default: the [Kit services](/kit/), each a URL live from the moment the computer starts, with no setup or deployment step | One request creates a computer with the Kit and its developer tools ([every option](/foundation/computers/create-edit-delete/)). In the Hub, open **Computers** and press **Get a computer**. Check the server and project, and leave **Hoody kit** and **Developer kit** on under **More options**; both are on by default. Then press **Get computer**. ```bash # Create a computer: a full Linux computer hoody computers create --project "$PROJECT_ID" \ --server-id "$SERVER_ID" \ --name "dev-environment" \ --hoody-kit \ --dev-kit # Once it is running, the Kit services are live ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); // Spawn a full Linux computer const computer = await client.api.computers.create(process.env.PROJECT_ID!, { server_id: process.env.SERVER_ID!, name: 'dev-environment', hoody_kit: true, dev_kit: true }); // Once it is running: // computer.data?.id -> 890abcdef12345678901cdef // Terminal, Display, Files, Exec, SQLite, Browser, Agent, // Code, cURL, Notifications, Daemons, Cron, Pipe, Notes, // Watch, Run, Tunnel, Proxy Logs, Egress, VM: all at predictable URLs ``` ```bash # A single POST creates the computer curl -X POST "https://api.hoody.com/api/v1/projects/$PROJECT_ID/computers" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "server_id": "'"$SERVER_ID"'", "name": "dev-environment", "hoody_kit": true, "dev_kit": true }' # Response includes computer ID # Construct any service URL: # https://{projectId}-{computerId}-terminal-1.node-us.computers.hoody.com ``` Creates the computer with the Kit services live. It runs through another computer's `curl-1` service (`OTHER_COMPUTER_ID`), so the first computer in a project still comes from one of the other tabs. ## How does a computer differ from Docker or a VM? A Docker container is a build artifact: lightweight, stateless and disposable, made to ship software. A Hoody computer is a full machine, persistent by default, reached by URL from any network. [Docker](/foundation/computers/images/#run-docker-or-kubernetes-inside-a-computer) comes with its developer tools; Podman or anything else installs as usual. A virtual machine is also a full computer, but it assumes you SSH in, configure it by hand and manage each machine on its own. A Hoody computer takes HTTP as its primary interface. Row by row: [Docker](/concepts/computers/reference/#computer-or-docker-container) and [VM](/concepts/computers/reference/#computer-or-vm) comparisons. ## Which services does a computer run? A Kit-enabled computer, the default, runs the [Hoody Kit](/kit/): services that expose Linux capabilities as HTTP endpoints, such as a terminal, a desktop, files, SQLite, a browser and the Hoody Agent. They are its primary interface, each at `https://{projectId}-{computerId}-{service}[-{instance}].{server}.computers.hoody.com` ([anatomy](/concepts/everything-is-a-url/)). The [Kit](/kit/) lists every service; [URL labels](/concepts/computers/reference/#kit-service-url-labels). The tabs show different calls to the same services. ```bash # Run a command in the computer hoody terminal commands run -c "$COMPUTER_ID" \ --command "sudo apt update && sudo apt install -y nodejs" # Read a file hoody files get /home/user/app.js -c "$COMPUTER_ID" # Query an existing /hoody/databases/app.db that has a users table hoody db transactions run -c "$COMPUTER_ID" \ --db /hoody/databases/app.db \ --transaction '[{"query":"SELECT * FROM users"}]' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const { COMPUTER_ID, PROJECT_ID, SERVER_NAME } = process.env as Record; const computerClient = await client.withComputer({ id: COMPUTER_ID, project_id: PROJECT_ID, server: SERVER_NAME }); // Terminal: run a command const result = await computerClient.terminal.commands.run({ command: 'node --version', wait: true }); // Files: read application code const code = await computerClient.files.get('/home/user/app.js'); // SQLite: query an existing /hoody/databases/app.db that has a users table (via direct fetch to the computer service URL) const base = `https://${PROJECT_ID}-${COMPUTER_ID}`; const node = `${SERVER_NAME}.computers.hoody.com`; const data = await fetch(`${base}-sqlite-1.${node}/api/v1/sqlite/db?db=/hoody/databases/app.db`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ transaction: [{ query: 'SELECT count(*) FROM users' }] }) }); ``` ```bash # Terminal: install software curl -X POST "https://$PROJECT_ID-$COMPUTER_ID-terminal-1.$SERVER.computers.hoody.com/api/v1/terminal/execute" \ -H "Content-Type: application/json" \ -d '{"command": "sudo apt install -y python3", "wait": true}' # Files: download a log file curl "https://$PROJECT_ID-$COMPUTER_ID-files-1.$SERVER.computers.hoody.com/api/v1/files/var/log/syslog" \ -o syslog.txt # Display: take a screenshot of the desktop curl "https://$PROJECT_ID-$COMPUTER_ID-display-1.$SERVER.computers.hoody.com/api/v1/display/screenshot" \ -o desktop.png # Browser: navigate to a page curl "https://$PROJECT_ID-$COMPUTER_ID-browser-1.$SERVER.computers.hoody.com/api/v1/browser/browse?url=https%3A%2F%2Fexample.com" ``` The log and screenshot calls above use curl's `-o` flag to save the response to a local file; that flag has no equivalent in a link, so only the two requests below are linked directly. ## How are computers kept apart? Each computer's files, processes and network are its own. Computers cannot see each other's files, there are no shared volumes by default, and what runs in one computer is invisible to the next. To share a directory, set up a [storage share](/foundation/storage/sharing-files/) explicitly. A computer that already holds project-scoped ramdisk also shares `/ramdisk/project` with its project's computers on the same server ([details](/foundation/storage/ramdisk/reference/#paths)). Computers do not share an internal network. They communicate over HTTP URLs through Hoody Proxy, the same way any two computers on the internet do ([how URLs reach computers](/concepts/proxy/)). The separation is always on and does not depend on application code ([details](/concepts/security/reference/#computer-isolation)). No isolation boundary is absolute: a vulnerability could in principle affect the separation between computers. On a rented server, only your own computers share the machine, unless you share the server through a [pool](/foundation/servers/share/). ## Run several sessions in one computer For instance-aware services, the instance number in the URL (`-1`, `-2`, `-3`) selects a parallel session in the same computer, for different users or agents: ``` https://{projectId}-{computerId}-terminal-1.node-us.computers.hoody.com # Developer's shell https://{projectId}-{computerId}-terminal-2.node-us.computers.hoody.com # Build process https://{projectId}-{computerId}-terminal-3.node-us.computers.hoody.com # AI agent's session https://{projectId}-{computerId}-display-1.node-us.computers.hoody.com # Main desktop https://{projectId}-{computerId}-display-2.node-us.computers.hoody.com # A second, separate display https://{projectId}-{computerId}-sqlite-1.node-us.computers.hoody.com # SQLite service https://{projectId}-{computerId}-sqlite-2.node-us.computers.hoody.com # Same SQLite service; the instance segment does not select a database # Both reach the same files; pick the database with ?db=app or ?db=analytics ``` SQLite instead selects the database with the `db` query parameter; [other services](/kit/#run-several-instances-of-a-service) also ignore the number. A URL gives everyone the same address. To keep several viewers on one display, share it with `?sharing=true&steal=false`; otherwise a new connection takes over ([display sharing](/kit/displays/#share-a-display-with-other-people)). ## How many computers can I run? Computers have no per-unit cost. Once a server exists, you can create as many as its capacity and [limits](/foundation/computers/create-edit-delete/#how-many-computers-can-i-create) allow: 3 on a free-tier server, the plan's limit on a paid subserver. Each computer uses some of its server's resources, so check capacity before you create staging environments or a computer per feature or per AI agent. The CLI tab creates ten test runners one after another; the other tabs create four named computers in parallel. The server needs room for them. ```bash # Spawn 10 computers for parallel testing for i in $(seq 1 10); do hoody computers create --project "$PROJECT_ID" \ --server-id "$SERVER_ID" \ --name "test-runner-$i" \ --hoody-kit done # Each gets the Kit services, each isolated ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const projectId = process.env.PROJECT_ID!; const serverId = process.env.SERVER_ID!; // Spin up computers for each team member const names = ['alice', 'bob', 'carol', 'dave']; const computers = await Promise.all( names.map(name => client.api.computers.create(projectId, { server_id: serverId, name: `dev-${name}`, hoody_kit: true, dev_kit: true }) ) ); // 4 full Linux computers, each with the Kit services ``` ```bash # Create computers in parallel; there is no per-unit cost for name in frontend backend database worker; do curl -X POST "https://api.hoody.com/api/v1/projects/$PROJECT_ID/computers" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d "{ \"server_id\": \"$SERVER_ID\", \"name\": \"$name\", \"hoody_kit\": true, \"dev_kit\": true }" & done wait # 4 computers created in parallel # Each with terminal, display, files, exec, sqlite... ``` Creates one computer per open, sent through another running computer's `curl-1` (`OTHER_COMPUTER_ID`); the loop above fires this same call four times in parallel, once per name (`frontend`, `backend`, `database`, `worker`). ## What happens over a computer's life? A computer is not disposable: its disk files survive restarts until you restore a snapshot or delete it. `/ramdisk` is temporary storage: its contents survive computer restarts but are lost when the server reboots. You can stop it (running programs end) and start it again, pause it (memory is kept), [snapshot](/concepts/snapshots/) it, restore a snapshot, copy it to another server or project, and delete it for good, its snapshots included. [What each stage does, and how](/concepts/computers/reference/#lifecycle-stages). At every stage, the computer's identity is its set of URLs. They appear when you create the computer and disappear when you delete it. ## When should I create a new computer? Elsewhere the unit varies by layer (server, VM, pod, process, function). In Hoody it is the computer, so there is one abstraction and one URL pattern to learn: - A service runs in a computer. - An AI gets access through the computer's URLs. - A risky experiment goes in its own computer, away from everything else. - Rolling back means restoring a computer snapshot. - Sharing an environment means sharing a computer URL. When in doubt, create a computer. Computers are cheap, fast, isolated, and HTTP-native, and creating a new one is less work than configuring a shared one. ## Reference URL labels, comparisons and lifecycle stages: the [Computers reference](/concepts/computers/reference/). ## What's next - [The Hoody Proxy](/concepts/proxy/): how URLs reach computers - [Everything is a URL](/concepts/everything-is-a-url/): how addresses are built - [Create, Edit, Delete](/foundation/computers/create-edit-delete/): every create option - [The Hoody Kit](/kit/): what each service does