Your First API

With hoody-exec, any script in its scripts directory is a live HTTP endpoint: write the file, and the URL exists. You do not need Express, Docker, or a CI/CD pipeline. Always write exec scripts through the exec service’s own scripts/write endpoint (not the Files service) so they land in the exec-managed scripts directory and pass validation.

---

Step 1: Write a script

CLI

# Write a script to the exec scripts directory (path is relative to that dir)
# All kit commands require a target container: -c CONTAINER_ID (or HOODY_CONTAINER)
hoody exec scripts write -c CONTAINER_ID --path "api/hello.js" --create-dirs --content \
'// @mode serverless
const name = metadata.query.name || "World";
return { message: `Hello, ${name}!`, timestamp: new Date().toISOString() };'

SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

// The three values the quickstart captured when it spawned the container
const { PROJECT_ID, CONTAINER_ID, SERVER_NAME } = process.env;
if (!PROJECT_ID || !CONTAINER_ID || !SERVER_NAME) {
  throw new Error('Set PROJECT_ID, CONTAINER_ID and SERVER_NAME to the values from the quickstart');
}

// Scope to your container, then write through the exec service (not the Files service)
const box = await client.withContainer({ id: CONTAINER_ID, project_id: PROJECT_ID, server: SERVER_NAME });

const script = `// @mode serverless
const name = metadata.query.name || "World";
return { message: \`Hello, \${name}!\`, timestamp: new Date().toISOString() };`;

await box.exec.scripts.write({
  path: 'api/hello.js',
  content: script,
  createDirs: true,
  validate: true
});

HTTP

# Write the script via the exec service's scripts/write endpoint.
# `path` is relative to the exec scripts directory.
curl -X POST "https://$PROJECT_ID-$CONTAINER_ID-exec-1.$SERVER_NAME.containers.hoody.com/api/v1/exec/scripts/write" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "api/hello.js",
    "content": "// @mode serverless\nconst name = metadata.query.name || \"World\";\nreturn { message: `Hello, ${name}!`, timestamp: new Date().toISOString() };",
    "createDirs": true,
    "validate": true
  }'

URL

?

One request, one link

cURL runs inside your container and can wrap any HTTP request into a single GET URL. The call stops being something you need a client for and becomes something you can paste into a browser, send in a chat, bookmark, schedule with cron, or drop into a no-code tool.

Nothing is installed on the machine that opens it. The link does carry whatever credentials the call needs, so treat it as you would treat those credentials.

Slashes, colons and braces pass through as they are. The one character you must encode is an & inside a value, which happens when the wrapped URL carries its own query string. Left raw it ends the value early, and the rest is read as cURL's own parameters, so you get a 200 on a request you did not make.

How the wrapping works Chaining calls into one link Turning a link into a shortcut

Writes the script through the exec service’s own endpoint, the same call the CLI and SDK make.

Copy

https://PROJECT_ID-CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://PROJECT_ID-CONTAINER_ID-exec-1.SERVER.containers.hoody.com/api/v1/exec/scripts/write&method=POST&json={"path":"api/hello.js","content":"//%20@mode%20serverless\nconst%20name%20=%20metadata.query.name%20||%20\"World\";\nreturn%20{%20message:%20`Hello,%20${name}!`,%20timestamp:%20new%20Date().toISOString()%20};","createDirs":true,"validate":true}&response=transparent

---

Step 2: Call it

Your script is already live at:

https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.com/api/hello

CLI

# Call your new API endpoint directly via its URL
curl "https://$PROJECT_ID-$CONTAINER_ID-exec-1.$SERVER_NAME.containers.hoody.com/api/hello?name=Developer"

SDK

// Exec scripts are live HTTP endpoints; call them directly
const response = await fetch(
  `https://${PROJECT_ID}-${CONTAINER_ID}-exec-1.${SERVER_NAME}.containers.hoody.com/api/hello?name=Developer`
);
const data = await response.json();
console.log(data);
// { message: "Hello, Developer!", timestamp: "2026-03-04T..." }

HTTP

curl "https://$PROJECT_ID-$CONTAINER_ID-exec-1.$SERVER_NAME.containers.hoody.com/api/hello?name=Developer"

Response:

{ "message": "Hello, Developer!", "timestamp": "2026-03-04T12:00:00.000Z" }

URL

?

One request, one link

cURL runs inside your container and can wrap any HTTP request into a single GET URL. The call stops being something you need a client for and becomes something you can paste into a browser, send in a chat, bookmark, schedule with cron, or drop into a no-code tool.

Nothing is installed on the machine that opens it. The link does carry whatever credentials the call needs, so treat it as you would treat those credentials.

Slashes, colons and braces pass through as they are. The one character you must encode is an & inside a value, which happens when the wrapped URL carries its own query string. Left raw it ends the value early, and the rest is read as cURL's own parameters, so you get a 200 on a request you did not make.

How the wrapping works Chaining calls into one link Turning a link into a shortcut

Runs the same GET through the container’s cURL service and returns the script’s JSON response as-is.

Copy

https://PROJECT_ID-CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://PROJECT_ID-CONTAINER_ID-exec-1.SERVER.containers.hoody.com/api/hello?name=Developer&method=GET&response=transparent

That URL works from anywhere: a browser, a webhook, an AI agent, a phone. There is no separate deployment step.

---

Step 3: Chain services

Exec scripts can call any other service in the container. Sibling services share the same host as your script; only the service slug changes. Derive the base host from metadata.url (the full request URL) and swap in the target service:

scripts/default/1/api/deploy-report.ts

// @mode serverless
// metadata.url is the full request URL, e.g.
// https://PROJECT_ID-CONTAINER_ID-exec-1.SERVER.containers.hoody.com/api/deploy-report
const { hostname } = new URL(metadata.url);
const host = (svc, idx = 1) =>
  `https://${hostname.replace(/-exec-\d+\./, `-${svc}-${idx}.`)}`;

// Run the build. ephemeral=true creates an isolated one-shot PTY; send it to the
// terminal-0 hostname, because on any terminal-N hostname the proxy forces
// terminal_id=N and ephemeral can no longer auto-generate an id.
const build = await fetch(`${host('terminal', 0)}/api/v1/terminal/execute?ephemeral=true`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ command: 'npm run build', wait: true })
});

// wait: true returns the finished command, so read its outcome before reporting one
const result = build.ok ? await build.json() : null;
const succeeded = result?.status === 'completed' && result.exit_code === 0;

// Log to database; the first deploy has to create the table it writes to
await fetch(`${host('sqlite')}/api/v1/sqlite/db?db=logs&create_db_if_missing=true`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    transaction: [
      { statement: 'CREATE TABLE IF NOT EXISTS deploys (status TEXT NOT NULL, time TEXT NOT NULL)' },
      {
        statement: 'INSERT INTO deploys (status, time) VALUES (?, ?)',
        values: [succeeded ? 'success' : 'failure', new Date().toISOString()]
      }
    ]
  })
});

// Send a notification: `display` is required, and `1` is the container's primary desktop
await fetch(`${host('n')}/api/v1/notifications/notify`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    display: '1',
    summary: succeeded ? 'Deploy complete' : 'Deploy failed',
    body: succeeded ? 'Build succeeded' : `Build exited ${result?.exit_code ?? 'without a result'}`
  })
});

return { status: succeeded ? 'deployed' : 'failed', timestamp: new Date().toISOString() };

One script coordinates three services with plain HTTP requests and no additional infrastructure.

Aliases and custom domains

The hostname rewrite keeps working when the request arrives through a proxy alias or a custom domain. The proxy rewrites the alias Host header to the canonical hostname before the request reaches the container, so metadata.url always carries the {projectId}-{containerId}-exec-1.{server} form regardless of the URL the caller used; the caller’s original hostname is in req.headers['x-forwarded-host']. Note that URLs derived this way contain the project and container IDs, so avoid echoing them into a response when an alias is supposed to keep those IDs out of the URL you hand out.

Tip

hoody-exec injects the metadata object. query and parameters are the same merged object (URL query params plus dynamic route segments; either name works). The object also includes method, url, clientIp, path, and executionId. See the Exec documentation for the full reference.

---

What you built

You created a live API endpoint by writing a file, with no npm install, docker build, or deploy command; maintaining a package.json is optional. The script’s path, relative to the exec scripts directory, is the URL path:

Script path	URL path
api/hello.js	/api/hello
api/users/list.js	/api/users/list
api/deploy.ts	/api/deploy
webhooks/stripe.js	/webhooks/stripe

Each script is an endpoint, each endpoint can call any service in the container, and every service speaks HTTP. Writing the script, calling it, and chaining services all happened through URLs.

Next: The Hoody Kit →