The Mental Model

You have run the Quick Start, so you have seen a container answer on a URL. This page is the map for what follows: the short vocabulary worth memorising, the work the platform now does for you, and the table you will come back to, with the old habit on the left and the Hoody equivalent on the right.

The argument for why the platform works this way lives in Understanding Hoody. This page assumes you are convinced and want to know how to operate.

The words you carry

The only thing you have to keep in your head is a handful of service names:

terminal · display · files · agent

Those four cover most of what anyone does with a computer: run a command, look at a screen, reach a file, ask for help. Add sqlite, exec, curl, and run and you have most of the remainder. The Hoody Kit lists all of them. Remembering the word is enough to reach the thing.

That matters more than it sounds. When reaching a machine takes a client, a key and the right laptop, small ideas quietly do not get tried. A one-word interface makes trying one cost almost nothing.

The address is that word in context

The full hostname is the same pattern everywhere:

https://{projectId}-{containerId}-{service}-{instance}.{server}.containers.hoody.com

Read left to right: project, container, service, instance, server. There is no routing table; the name itself is the route. Knowing the five parts is enough to construct any address by hand, and in practice only the service word changes as you move between tasks.

Two things sit slightly outside the pattern and are worth knowing on day one:

Processes you start yourself answer at http-{port} in the service position. A dev server on port 3000 is reachable at {projectId}-{containerId}-http-3000.{server}.containers.hoody.com. The Kit’s own services sit on reserved ports below 80 inside the container, so 80 to 499 are free for your apps. Above 500, Hoody assigns pool ports as you start browser, display, or code instances, so a port that is free now can be taken later.
api.hoody.com is the control plane. You call it to create, start, stop, and snapshot containers. It is not in the path of your traffic: requests to a container URL are served by the proxy running on the host that carries the container, not by a central Hoody tier.

That is the whole addressing model.

Hold this

These are the facts that stay loaded. If something is not on this list, look it up when you need it.

The service name is the interface. terminal, display, files, agent and the rest of the Kit. Once you know a container’s address, the service word is the only part you change to switch tasks. The address is that word inside project-container-service-instance.server.containers.hoody.com, plus http-{port} for whatever you launch yourself.
The two 24-character IDs in the hostname are the credential. An unguessable URL is what makes “paste this to a teammate” work. It is also why a container URL should be handled like a password.
Set proxy permissions before you share anything you care about. A fresh container is reachable by anyone holding its URL. Password, IP range, JWT, and bearer rules are all applied at the proxy.
Instances are 1-based and plural. terminal-2 or display-2 is one edit to the hostname away, and those sessions are isolated from each other. Instance numbering does not mean the same thing for every service: SQLite instances share the container filesystem, and the database is chosen with the db query parameter.
api.hoody.com manages containers; container URLs are the container. Management calls go to Hoody’s API. Container traffic terminates at the proxy on the host serving that container. This is a statement about the request path, not about administrative access to the host, and a free-tier slice shares its host with others.
Snapshot before anything risky. A snapshot is a rollback point on the same host, not an off-server backup, and restore time scales with its size. When you would rather branch than gamble, copy the container instead of mutating it.
Containers carry no additional charge once the server exists. They still consume that server’s CPU, memory, and disk, so capacity is a real constraint even though billing is not.
Your window is a viewport, not the process. Closing a laptop stops nothing. Work handed to daemon or cron keeps running.
ssh hoody.com is the hosted CLI; @hoody.com is the AI entry point. ssh hoody.com signs you in and gives you the Hoody CLI with nothing installed. For a shell inside a container, use the container SSH host or the terminal URL.

Drop this

Each of these used to be a recurring task. On Hoody they are properties of the platform, so they stop being your job.

Certificate management. Every container URL is HTTPS with HTTP/2 and HTTP/3. There is nothing to issue, install, renew, or debug.
Public port mapping. The service word in the hostname selects the port. You still choose which port your app listens on; you no longer forward it anywhere.
Reverse proxy and ingress configuration. No nginx server block, no ingress object, no upstream definition for reaching a Kit service.
DNS records for internal things. Addresses are deterministic and derived from IDs you already have. An address you never use costs nothing.
VPN as a prerequisite for access. Access rules live on the address, not on the network your body happens to be on.
Protocol-specific client software. No SSH client, SFTP client, VNC viewer, or database GUI is required to reach a terminal, a file, a desktop, or a SQLite database.
Treating one laptop as the canonical machine. The persistent environment is server-side, and a browser reaches most of the Kit. Direct SSH and raw networking still want their own clients.
Keeping a window open so a job survives. Sessions are views onto processes that were never inside them.
Provisioning a separate paid machine per environment. Staging is a container name, not a purchase.

Do this instead

This is the part worth bookmarking. For the first week or two you will keep reaching for the old tool. Use this table when you catch yourself.

These are defaults, not prohibitions. SSH, PostgreSQL, and conventional pipelines still exist and are still correct when a workload genuinely calls for them. They simply stop being the first thing you reach for.

Old reflex	Hoody equivalent	Reference
SSH in to run a command	Open the terminal URL. It is the live session, so it is also shareable. `terminal-2` is one edit away.	Terminals
`scp` a file across	`GET` or `PUT` the path on the files URL, or drag and drop in a browser.	Files
Start VNC or RDP, or screen-share a server-side app	Open the display URL. Everyone who opens it connects to the same live session rather than watching a video of it.	Displays
Stand up PostgreSQL for scratch data	Send SQL to the sqlite URL. Pick the database with `?db=scratch` to keep throwaway tables apart.	SQLite
Write a deployment pipeline for an internal script	Put the script in `exec`. The file existing is the deployment.	Exec
Build a glue service to wrap an awkward API	Save the call with `curl`. Simple requests collapse into one GET URL you can bookmark or hand to a webhook; retries, sessions, and scheduling use the POST form. Treat any URL carrying a credential as a secret.	Curl
Install the tool locally before trying it	Ask `run` for it. It resolves the name across Nix, pkgx, AppImage, and OCI registries into the exact launch command, with a preview handoff to the display where it will appear.	Run
Screen-share your own physical machine	Stream it through `pipe` and send the URL. One sender, up to 256 receivers.	Pipe
`nohup`, `tmux`, or `screen` to keep something alive	Hand the program to `daemon`. It is supervised under a restart policy you set, and its stdout and stderr are readable over HTTP.	Daemons
`crontab -e` over SSH	Create the schedule through `cron`. It fires whether or not your laptop is open.	Cron
`tail -f` an app’s output over SSH	Read stdout and stderr from the `daemon` API for any supervised program.	Daemons
Dig through access logs on the box	Query or stream `logs` for inbound proxy traffic.	Proxy logs
Poll for a file to change	Subscribe to `watch`, which streams filesystem events over SSE.	Watch
Make a rollback point before a risky change	Snapshot the container. Copying it branches the machine instead. For disaster recovery, keep a copy off the server.	Snapshots
Run `ngrok` to demo local work	Expose it with `tunnel`: visitors hit the tunnel URL and land on your laptop’s port. The same service pulls the other way too, reaching a local database from inside the container.	Tunnel
Build an integration so your AI can drive Hoody	Point the AI at the published Skill bundle at `hoody.com/SKILLS/` and give it a scoped token. Nothing to host.	Agent Skill Bundle
Set up VS Code Remote-SSH to edit on the server	Open the `code` URL. The editor runs in the container and reaches it in a browser tab.	Code
Install Chrome and a driver locally to scrape or test	Drive the container’s `browser` service over HTTP.	Browser
Provision a staging VPS	Create another container on the server you already have.	Projects and Containers

The reflex test

If you are about to install something locally, deploy something in order to call it, start a VNC session, or share your screen to show a colleague something running on a server, check the table first. What you are about to build usually already has an address.

One real limitation: the proxy serves HTTP, HTTP/3, and WebSocket traffic only. Other protocols reach a container through tunnel in pull mode, the container firewall, or a dedicated IPv4.

What Hoody still leaves to you

Hoody removes operations, not responsibility. These stay yours.

Still yours	Why
Access policy	Containers are open to URL holders until you set proxy permissions. The platform enforces your rules; it does not invent them.
Secrets and credentials	Automatic TLS protects traffic in transit. It says nothing about what you commit, log, or paste.
Application-level authorization	Proxy rules gate who reaches the service. Who may do what inside your application is still your code.
Server capacity	Containers are free of extra charge, not free of CPU, memory, and disk.
Snapshot discipline	Snapshots exist because you took them. Nothing is automatic.
Off-server backups	A snapshot lives on the same machine as the container. It is a rollback, not disaster recovery.
DNS for custom domains	Certificates are still automatic once the domain resolves, but pointing the records is yours to do.
Non-HTTP networking	The proxy serves HTTP, HTTP/3, and WebSocket. Anything else goes through tunnel, the firewall, or a dedicated IPv4.

Useful questions

Is SSH forbidden now?

No. The terminal URL replaces SSH as the default because it is shareable, embeddable, and callable from anything that speaks HTTP. Real SSH is still there: ssh hoody.com gives you the Hoody CLI with nothing installed, and each container has its own SSH host for a genuine shell.

Is a container URL really a password?

Functionally, yes, until you configure otherwise. The two 24-character identifiers are the secret. That property is what makes sharing a link work at all, and it is why the first thing to do with anything sensitive is set proxy permissions.

When should I use a real database instead of the SQLite service?

When you need cross-host replication, automatic failover, a database wire protocol your client library expects, or write throughput past SQLite’s serialized writes. Concurrency alone is not a reason to leave: databases under /hoody/databases/ are shared across containers on the same server with locking handled for you.

Why is `api.hoody.com` not in the traffic path?

Because the proxy that mints and serves container URLs runs on your server. The API creates and manages containers. Once one is running, requests to it resolve to your machine directly.

My process is running but its URL returns an error.

Check that the process is running and that the port in the hostname matches the port it is listening on. See Proxy for the full sequence.

Troubleshooting

These are the errors that come from misreading the model rather than from a broken system.

Symptom	What to check
Hostname does not resolve	Wrong `{server}` segment. Everything left of it is one DNS label under that server’s wildcard, so only the server name can fail resolution.
Resolves, but the proxy returns an error	A malformed or misspelled left-hand label. Check the order: project, container, service, instance.
401 or 403 on your own container	A proxy permission rule is applied and your request does not satisfy it, or the proxy is disabled for that container.
`http-{port}` connection error	Check that the process is running and that the port in the hostname matches the port it listens on. See Proxy for the full sequence.
Management call sent to a container URL	Container creation and lifecycle live on `api.hoody.com`, not on the container’s own address.

What’s next

Containers: create, start, snapshot, and delete
Proxy: the permission rules referenced throughout this page
Everything is a URL: the addressing model in full
The Hoody Kit: what each of the services in the table above actually does
Understanding Hoody: why the platform is built this way