# Everything is a URL **Page:** concepts/everything-is-a-url [Download Raw Markdown](./concepts/everything-is-a-url.md) --- # Everything is a URL **In most platforms, URLs are an afterthought.** An address you bolt onto something after building it. A convenience. A nice-to-have. In Hoody, a URL is the thing itself. Your terminal is not "accessible at" a URL. Your terminal **is** a URL. Your desktop, your filesystem, your database, your AI agent -- they do not merely have addresses. They are addresses. Destroy the URL, destroy the resource. Share the URL, share the resource. Compose URLs, compose systems. This is not a metaphor. This is the architecture. Every process, on a server you own, is an HTTPS endpoint with HTTP/2 and HTTP/3 — zero certificates, zero configuration, zero excuses. You can embed any program in an iframe, control it from an AI agent, access it from `ssh hoody.com`, or just open it in a browser on your phone. The scale of what this enables is genuinely insane. --- ## The Anatomy of a Hoody URL Every resource in Hoody lives at a predictable, deterministic address: ``` https://{projectId}-{containerId}-{service}-{instance}.{serverName}.containers.hoody.icu ``` | Segment | Example | What It Encodes | | :--- | :--- | :--- | | `projectId` | `67e89abc123def456789abcd` | Which project owns this resource. 24 hex chars. | | `containerId` | `890abcdef12345678901cdef` | Which container runs it. 24 hex chars. Cryptographically unguessable. | | `service` | `terminal` | What kind of resource: terminal, display, files, exec, sqlite, browser, workspaces, code, curl, notifications, daemons, cron, pipe, watch, notes, run, tunnel, logs. | | `instance` | `1` | Which instance of that service. Change `1` to `2` and you get a different terminal session, a different desktop, a different database. | | `serverName` | `node-us` | The bare metal server hosting it. Geography encoded in the URL. | **Every segment is meaningful.** Change one segment and you reach a different resource. Every segment maps to a piece of real infrastructure -- a project boundary, a container filesystem, a service process, a physical server. This is not a routing convention. It is the topology of your infrastructure, expressed as text. --- ## Four Kinds of URLs Hoody has four URL families. Each serves a different purpose, but all follow the same principle: the address IS the interface. ### 1. Container Service URLs The workhorse. Every container gets 18 service URLs the moment it spawns: ``` https://67e89abc...-890abcdef...-terminal-1.node-us.containers.hoody.icu https://67e89abc...-890abcdef...-display-1.node-us.containers.hoody.icu https://67e89abc...-890abcdef...-files-1.node-us.containers.hoody.icu https://67e89abc...-890abcdef...-exec-1.node-us.containers.hoody.icu https://67e89abc...-890abcdef...-sqlite-1.node-us.containers.hoody.icu https://67e89abc...-890abcdef...-browser-1.node-us.containers.hoody.icu https://67e89abc...-890abcdef...-workspaces-1.node-us.containers.hoody.icu https://67e89abc...-890abcdef...-http-3000.node-us.containers.hoody.icu ``` No DNS setup. No port forwarding. No nginx configuration. The proxy reads the URL, routes to the container, dispatches to the service. Done. ### 2. API URLs The Hoody API itself is a URL: ``` https://api.hoody.icu/api/v1/containers https://api.hoody.icu/api/v1/projects https://api.hoody.icu/api/v1/servers ``` This is how you create, manage, and destroy resources. The API URL creates container URLs. Container URLs serve the resources. It is URLs all the way down. ### 3. Proxy Alias URLs When cryptographic URLs are too long for humans, create aliases: ``` https://my-app.node-us.containers.hoody.icu https://staging-api.node-eu.containers.hoody.icu https://client-demo.node-us.containers.hoody.icu ``` Same routing, same security, same proxy -- just a shorter address. Point a CNAME from your own domain, and your infrastructure lives at `api.yourcompany.com`. ### 4. Realm-Scoped URLs For multi-tenant isolation, realms namespace the API itself: ``` https://{realmId}.api.hoody.icu/api/v1/containers ``` Different realm, different universe. Auth tokens, containers, projects -- all scoped. One Hoody account, infinite isolated namespaces. --- ## Why URLs Are the Universal Interface Three audiences interact with computing infrastructure: humans, machines, and AI. The legacy world gives each a different interface. Humans get GUIs. Machines get wire protocols. AI gets SDKs. Hoody gives all three the same thing: **a URL.** ### Humans Open a browser. Type the URL. You are in a terminal. Change `terminal` to `display` in the address bar. Now you are on a desktop. Change `display` to `files`. Now you are browsing the filesystem. No client installation. No SSH keys. No VPN. ### AI Agents Give an LLM a container URL. It already knows HTTP. It already knows JSON. It already knows `GET`, `POST`, `PUT`, `DELETE`. No SDK, no adapter, no training. The URL IS the tool. ```bash # List containers -- the URL is the query hoody containers list # Get a specific container -- the URL identifies it hoody containers get 890abcdef12345678901cdef ``` ```typescript import { HoodyClient } from '@hoody-ai/hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.icu', token: process.env.HOODY_TOKEN }); // Every resource is a URL behind the scenes const container = await client.api.containers.get('890abcdef12345678901cdef'); // Construct any service URL from the container data const terminalUrl = `https://${container.data.project_id}-${container.data.id}-terminal-1.${container.data.server_name}.containers.hoody.icu`; ``` ```bash # The URL IS the resource curl https://api.hoody.icu/api/v1/containers/890abcdef12345678901cdef \ -H "Authorization: Bearer $HOODY_TOKEN" # Execute a command -- via URL curl -X POST "https://$PROJECT-$CONTAINER-terminal-1.$SERVER.containers.hoody.icu/api/v1/terminal/execute" \ -H "Content-Type: application/json" \ -d '{"command": "ls -la", "wait": true}' ``` ### IoT and Embedded Devices Can it make an HTTP request? Then it can control a full Linux computer. A Raspberry Pi. A smart thermostat. A CI/CD runner. If it speaks HTTP, it speaks Hoody. --- ## Composability Through URLs Here is where the URL-first model departs from everything else: **URLs compose.** If everything is a URL, then combining systems is combining URLs. No integration layer. No message queue. No adapter pattern. You compose addresses. ```bash # Chain container operations -- each is a URL call hoody snapshots create -c 890abcdef12345678901cdef --alias "before-experiment" # Clone from that snapshot to a new container hoody containers copy 890abcdef12345678901cdef \ --target-project-id abc123 \ --source-snapshot "before-experiment" ``` ```typescript import { HoodyClient } from '@hoody-ai/hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.icu', token: process.env.HOODY_TOKEN }); // Connect to Container B and read a file const containerB = await client.withContainer({ id: CONTAINER_B_ID, project_id: PROJECT_ID, server: SERVER_NAME }); const config = await containerB.files.get('/home/app/config.json'); // Connect to Container A and write to its SQLite const containerA = await client.withContainer({ id: CONTAINER_A_ID, project_id: PROJECT_ID, server: SERVER_NAME }); await containerA.sqlite.database.executeTransaction( { transaction: [{ statement: `INSERT INTO configs VALUES (?)`, values: [config.data] }] }, { db: 'app' } ); ``` ```bash # Container A executes a build in Container B's terminal curl -X POST "https://$PROJECT-$CONTAINER_B-terminal-1.$SERVER.containers.hoody.icu/api/v1/terminal/execute" \ -H "Content-Type: application/json" \ -d '{"command": "npm run build", "wait": true}' # Then reads the artifact via Container B's files curl "https://$PROJECT-$CONTAINER_B-files-1.$SERVER.containers.hoody.icu/home/app/dist/bundle.js" \ -o bundle.js # And uploads it to Container C curl -X PUT "https://$PROJECT-$CONTAINER_C-files-1.$SERVER.containers.hoody.icu/var/www/html/bundle.js" \ --data-binary @bundle.js ``` No orchestrator. No message bus. No service mesh. Just URLs calling URLs. The web already solved distributed systems. We just made infrastructure speak the same language. --- ## The Self-Documenting Infrastructure Legacy systems require documentation to explain how to reach them. IP addresses, port numbers, protocol versions, authentication mechanisms -- all living in wikis, READMEs, and tribal knowledge. A Hoody URL documents itself: ``` https://67e89abc123def456789abcd-890abcdef12345678901cdef-sqlite-1.node-us.containers.hoody.icu ``` Read it left to right: **Project** `67e89abc...` owns **Container** `890abcde...`, which runs a **SQLite** database, **instance 1**, on server **node-us**. The URL tells you what it is, where it is, and who owns it. Share a URL, and you have shared the documentation AND the access AND the interface -- in one string. Can you describe your infrastructure by listing URLs? If yes, your infrastructure is self-documenting. If no, you have a documentation problem disguised as an infrastructure problem. --- ## URLs in the AI Era Legacy infrastructure requires AI to learn bespoke interfaces: SSH key exchange, database wire protocols, custom CLIs. Every tool is a separate skill the AI must acquire. When everything is a URL, AI already has every skill it needs. HTTP is the most represented protocol in LLM training data. JSON is the most represented data format. An AI agent given a Hoody container URL can immediately: - Execute commands (POST to the terminal URL) - Read and write files (GET/PUT to the files URL) - Query databases (POST to the SQLite URL) - Automate browsers (POST to the browser URL) - Spawn new containers (POST to the API URL) - Access desktops (connect to the display URL) No SDK. No training. No fine-tuning. The URL is the interface the AI was trained on. This is not a feature. This is an inevitability. AI was trained on HTTP. Infrastructure should be HTTP. We just closed the gap. `@hoody.com` is the ultimate proof: it is a single URL that teaches any AI how to use every other URL in your infrastructure. Give it to ChatGPT, Claude Code, or Codex — they fetch a Skill, a structured map of every HTTP endpoint across your containers. One URL to rule them all. --- ## The Routing Contract Every Hoody URL is a contract: 1. **The URL identifies the resource.** Change the URL, change the resource. 2. **The URL routes the request.** The [proxy](/concepts/proxy/) reads the URL segments, finds the container, dispatches to the service. 3. **The URL enforces security.** The 48+ hex characters in the URL are cryptographically unguessable. Knowing the URL IS the first layer of authorization. 4. **The URL enables composability.** Anything that can construct a URL can interact with anything in Hoody. 5. **The URL survives context switches.** Copy it to Slack, paste it in a CI pipeline, embed it in an iframe, hand it to an AI -- the URL works everywhere, always. --- ## What This Means in Practice Stop thinking about servers, ports, protocols, and clients. Start thinking about URLs. | Old question | New question | | :--- | :--- | | "What's the IP address?" | "What's the URL?" | | "What port is it on?" | It is in the URL. | | "What protocol does it use?" | HTTPS. Always. | | "What client do I need?" | A browser. Or `curl`. Or `fetch`. | | "How do I give someone access?" | Send them the URL. | | "How do I revoke access?" | Delete the container. The URL dies. | | "How do I document this?" | The URL IS the documentation. | **URLs are the API, the interface, and the documentation -- all in one.** --- **Next:** [Containers](/concepts/containers/) -- what lives at these URLs.